Docker Model RunnerのOCI配布とAPI境界を検証

先に結論

Docker Model Runnerの再現性は「modelをOCI artifactにした」だけでは成立しません。source hash、license、package command、OCI digest、推論engine、platform、API path、到達可能なclientを同じrelease単位で固定して初めて、配布物と実行条件を追跡できます。

formatの基本分岐は、local・省memoryを優先するGGUF／llama.cppと、対応NVIDIA環境でconcurrencyを狙うSafetensors／vLLMです。ただし現行公式文書には、vLLMのWindows WSL2対応やSafetensors package optionについてページ間の表記差があります。本稿では2026年8月6日に開いたCLI referenceをcommand構文の基準とし、実行環境のdocker model package --helpとdocker model statusで再確認する設計にします。

確認日時: 2026年8月6日 05:30（Asia/Tokyo）
対象資料: Docker Model Runner overview、inference engines、REST API、docker model package CLI referenceの現行版
固定範囲: text generation、GGUF／llama.cpp、Safetensors／vLLM、OCI-compatible registry、OpenAI互換chat completion
検証区分: 公式文書間を照合した机上調査・検証計画。この制作環境にDocker CLIがないため、package、push、pull、GPU推論、network到達性、性能は未検証
適用外: Diffusers、DDUF、第三者registry固有の認証・課金、model品質、SLA、internet公開用gatewayの実装

確認済み事実と文書差分

2026年8月6日時点の公式文書から、次を確認しました。

modelはDocker Hub、OCI-compatible registry、Hugging Faceからpullされ、localへcacheされる
request時にmemoryへloadされ、一定の非活動時間後にunloadされる
llama.cppはdefault engineで、GGUFとmacOS／Windows／Linuxを広く扱う
vLLMはSafetensorsとNVIDIA CUDAを前提にする
host processのOpenAI互換base URLは通常http://localhost:12434/engines/v1
Desktopのcontainerからはhttp://model-runner.docker.internal、Engineのcontainerからは条件付きで172.17.0.1:12434またはhost-gatewayを使う
Model Runner APIは認証されず、Authorization headerも無視される
APIへ到達できるclientはmodelのpull、load、run、推論requestを行える

一方、同じ公式site内でも次の差があります。

inference enginesの比較表はvLLMをLinux x86_64のみとする一方、詳細節はDocker Desktop 4.54+のWindows WSL2をsupportedとする
inference engines本文のpackage例は—safetensorsと書く箇所がある一方、現行CLI referenceのusageとoptionは—safetensors-dirである
overviewの全体minimumと、特定engineのminimumは別であり、Desktop全体の4.41+をvLLM利用条件として扱えない

したがって、記事上の一般論だけでcommandやplatform対応を確定しません。固定版のCLI help、statusが示すengine、対象platform節を実行記録へ残します。

artifactに固定するもの

OCI tagは後から同じ文字列へ別digestを付け直せます。再現可能な配布ではtagだけでなくdigestとsourceを保存します。

層	固定する値	戻すために残すもの
source	model repository、revision、filename、SHA-256、license	元file／directoryと取得記録
package	Docker／DMR version、package command、chat template、context size	command lineとstderr
artifact	registry、repository、tag、manifest digest	旧digestと署名・provenance
engine	llama.cpp／vLLM、engine build、backend、driver	`docker model status —json`
runtime	context、sampling、GPU、memory上限、同時request	設定snapshot
API	base URL、engine path、model ID、到達可能network	client設定とnetwork rule

license fileをartifactへ含めても、元modelの利用条件を自動判定できるわけではありません。再配布可能性、派生物の表示義務、商用条件はpackage前に別途確認します。

GGUFとSafetensorsを別経路でpackageする

現行CLI referenceのusageは次です。

docker model package \
  (--gguf <path> | --safetensors-dir <path> | --dduf <path> | --from <model>) \
  [--license <path>...] [--mmproj <path>] [--context-size <tokens>] [--push] MODEL

GGUF／llama.cpp

single fileまたはshard先頭を指定し、まずlocal content storeへpackageします。いきなりpushせず、作成物をrunできることを確認します。

MODEL_GGUF="/absolute/path/to/model.Q4_K_M.gguf"
LICENSE_FILE="/absolute/path/to/LICENSE"

shasum -a 256 "$MODEL_GGUF"
docker model package \
  --gguf "$MODEL_GGUF" \
  --license "$LICENSE_FILE" \
  myorg/model:gguf-q4

上のmodel名はlocal package用の構文例です。registryへpushする実運用では管理下の完全な参照へ置き換え、credentialをcommand lineや記事へ書きません。sharded GGUFは先頭shardと命名規則から自動検出されるため、全shardのhashと個数を別に記録します。

Safetensors／vLLM

CLI referenceでは、.safetensorsだけでなくmodel configとtokenizerを含むdirectoryを—safetensors-dirへ渡します。

MODEL_DIR="/absolute/path/to/safetensors-model"
LICENSE_FILE="/absolute/path/to/LICENSE"

docker model package \
  --safetensors-dir "$MODEL_DIR" \
  --license "$LICENSE_FILE" \
  myorg/model:vllm

このcommandが通っても、vLLMで実行できる保証にはなりません。architecture support、CUDA、driver、GPU memory、platform条件を先に確認します。baselineはLinux x86_64＋supported NVIDIA GPUへ限定し、Windows WSL2はDocker Desktop 4.54+と詳細節の条件を満たす別matrixとして扱います。macOS、AMD、CPU-onlyへvLLM結果を一般化しません。

engine選択を比較する条件

公式文書の「llama.cppはlocal向け、vLLMはhigh throughput向け」は選定の入口であり、benchmark結果ではありません。比較では、同等model familyでもformatとquantizationが違えばweight自体が同一でない点を明示します。

固定・観測項目	llama.cpp経路	vLLM経路
platform	OS、CPU／GPU、driver	Linux x86_64または条件付きWSL2、NVIDIA、driver
model	GGUF revision、quantization、hash	Safetensors revision、dtype、全file hash
request	同じ意味のprompt、model別token列も保存	同左
workload	concurrency、prompt token、output上限、到着間隔	同左
観測	load時間、TTFT、ITL、request/s、RSS／VRAM、error	同左
適用判断	single-user、memory制約、CPU／Apple Silicon	supported NVIDIAで複数同時request

実行していないため、本稿は速度差やmemory差の数値を示しません。official pageにある定性的な推奨を、自分のSLOを満たす実測と混同しないでください。

APIの接続境界を先に決める

DMRのAPI key欄は「不要」であり、任意のkeyを送っても認証境界にはなりません。安全なdefaultは、到達できるclientをhostまたは限定networkへ絞ることです。

host application
  -> localhost:12434/engines/llama.cpp/v1/chat/completions
  -> DMR
  -> approved local model digest

containerから使う場合も、同じDocker networkの全containerを信頼しません。専用network、egress／ingress rule、実行user、container inventoryを固定し、不要なserviceを接続しない構成にします。public interface、LAN、internetへ直接bindせず、認証gatewayを別途置く設計は本稿の適用外として独立reviewへ回します。

API pathは複数engineを同時運用する場合に明示します。

curl --fail-with-body \
  http://localhost:12434/engines/llama.cpp/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d @request.json

auto-selectの/engines/v1/chat/completionsは入門には便利ですが、engine差を測るrunではengine-specific pathを使います。model IDはnamespaceとtagを含め、request body、response metadata、resolved artifact digestを同じrun IDへ結び付けます。

失敗時の戻し方

package syntaxが認識されない

internet上の例を混ぜず、対象hostのdocker model package —helpへ戻ります。特にSafetensors optionは文書差があるため、installed CLIが—safetensors-dirを持たない場合、推測で別flagへ置換せずDMR／Docker versionと公式referenceの対応を確認します。

artifactはpullできるがloadできない

source formatとengineを分けます。GGUFをllama.cpp、SafetensorsをvLLMへ固定し、model architecture、config、tokenizer、shard不足、driver、memoryを1項目ずつ確認します。tagを再利用して上書きせず、修正版は新tagと新digestにします。

APIへ意図しないcontainerから到達できる

APIを停止またはhost-side TCPを無効にし、network membershipを縮小します。dummy API key追加では解決しません。到達試験は許可clientと拒否clientの両方から行い、pull／load／inferenceの各endpointが拒否されることを記録します。

新版で結果が変わる

artifact digestが同じでもengine build、driver、context default、chat templateが違えば結果は変わります。旧DMR／engineの記録とartifact digestへ戻し、1変数ずつ更新します。tagだけをrollback単位にしません。

採用判断

DMRを配布基盤へ採用する条件は、OCIへpushできることではありません。sourceとdigestを追跡でき、対象platformでengineを固定でき、SLOを満たす実測があり、未認証APIへ到達できるclientを列挙・制限でき、旧digestへ戻せることです。

最初のCLI／API確認がまだなら、Docker Model Runner入門：最初のAPI応答までから進めてください。container基礎とmodel runner固有機能は分け、一般的なDockerの概念はDocker完全ガイドで補えます。

参考資料

Docker公式：Docker Model Runner overview（2026年8月6日確認）
Docker公式：Inference engines（2026年8月6日確認）
Docker公式：DMR REST API（2026年8月6日確認）
Docker公式：docker model package CLI reference（2026年8月6日確認）
Docker公式：docker model status CLI reference（2026年8月6日確認）