Docker Model Runner入門：最初のAPI応答まで

先に結論

Docker Model Runner（DMR）は、AI modelをregistryからpullし、localへcacheし、必要になったときだけ推論engineへloadして、CLIまたは互換APIから使う機能です。最初はDocker DesktopでDMRを有効にし、小型のai/smollm2:360M-Q4_K_Mをpullして1回だけ実行します。その後、host側TCPを明示的に有効にした環境だけでlocalhost:12434のOpenAI互換APIを確認します。

重要なのは、Model Runner APIに認証がないことです。入門段階ではlocal machineの外へportを公開せず、reverse proxyやport forwardingも追加しません。本稿は2026年8月6日時点のDocker公式文書を照合した机上手順であり、この制作環境にはDocker CLIがないため、model download、推論、API応答は実機未検証です。

確認日時: 2026年8月6日 05:30（Asia/Tokyo）
対象: Docker Model Runnerの現行公式文書。全体要件はDocker Desktop macOS 4.40+、Windows 4.41+、またはDocker Engine
最短経路: Docker Desktop、defaultのllama.cpp engine、GGUF量子化model、host processからlocalhost接続
検証区分: 公式overview、Get started、REST API、CLI referenceに基づく机上調査。Docker CLI、model、GPUを使った実行は未実施
対象外: vLLM、Diffusers、外部公開、認証proxy、特定modelの品質・license保証

始める前に確認すること

DMRでは「container imageをrunする」のではなく、modelをDockerの管理対象としてpull・cacheし、推論時にengineへloadします。local開発のdefault engineはllama.cpp、model formatはGGUFです。最初からvLLMや独自modelのpackagingへ進まず、公式catalogの小型GGUFで経路を確認します。

必要条件は次のとおりです。

macOSならDocker Desktop 4.40以降、Windowsなら4.41以降、Linuxなら対応するDocker Engineがある
Docker DesktopのSettingsにあるAI画面で「Enable Docker Model Runner」を有効にできる
model fileを保存するdiskと、modelをloadできるmemoryに余裕がある
API確認時だけ「Enable host-side TCP support」を有効にし、portを12434として確認できる
modelのlicenseと利用条件を配布元で確認する

WindowsのGPU・driver、Linuxのbackend、Apple Silicon以外の条件はplatformごとに異なります。本稿では共通化せず、まずdocker model statusが認識するengineを基準にします。

最短手順：Pull、Run、APIの順に進む

1. DMRが使えることを確認する

Docker DesktopでDMRを有効にした後、terminalで次を実行します。

docker model version
docker model status

成功確認は、docker modelがcommandとして認識され、statusがModel Runnerと推論engineの状態を表示することです。version番号やengine buildは環境で変わるため、架空の出力例は示しません。結果をそのまま作業記録へ保存してください。

2. 小型modelをpullする

公式Get startedで例示される量子化tagを明示します。

docker model pull ai/smollm2:360M-Q4_K_M

初回はregistryからmodelを取得するため時間がかかります。完了後はlocalへcacheされます。途中で止まった場合、別のtagへ次々切り替えず、disk空き、network、registryの到達性、model名の綴りを確認して同じcommandを再実行します。

3. 1回のpromptでrunする

公式CLI referenceの構文はdocker model run MODEL [PROMPT]です。

docker model run ai/smollm2:360M-Q4_K_M \
  "ローカル推論の確認項目を3つ挙げてください。"

成功条件は、modelがerrorなくloadされ、promptに対する応答が返り、commandが異常終了しないことです。回答内容はmodelとsamplingで変わるため、本稿では正解文を作りません。応答品質の評価は、最初の動作確認と分けます。

4. localhostのOpenAI互換APIを確認する

Docker Desktopではhost側TCPを明示的に有効にします。Docker Engineでは公式Get startedがTCP port 12434をdefaultとしています。どちらも外部interfaceやrouterへ公開せず、host processからlocalhostへ送ります。

curl --fail-with-body \
  http://localhost:12434/engines/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "ai/smollm2:360M-Q4_K_M",
    "messages": [
      {"role": "user", "content": "応答確認とだけ答えてください。"}
    ],
    "max_tokens": 32,
    "temperature": 0
  }'

HTTP成功だけでなく、JSONにmodel応答があり、error objectではないことを確認します。DMRは要求されたlocal modelをon-demandでloadできるため、APIの前に必ずdocker model runする必要はありません。ただし入門では、CLI成功とAPI失敗を分けて切り分けるため、この順序にしています。

つまずきやすい点と戻し方

docker: ‘model’ is not a docker command

まずDocker Desktop／EngineのversionとDMRの有効化を確認します。macOSでplugin pathを見失った場合、公式overviewにはCLI pluginへのsymlink修復例がありますが、pathはinstallationごとに違います。存在確認なしにsymlinkを作らず、Docker Desktopを再起動してから公式の既知問題手順を使います。

modelをpullできない

model referenceをai/smollm2:360M-Q4_K_Mへ戻し、disk空きとregistry到達性を確認します。巨大modelへ変えて解決を試みません。licenseや配布停止を確認できないmodelは別名で代用せず、作業を止めます。

CLIは動くがlocalhost:12434へ接続できない

Docker Desktopでhost-side TCP supportが有効か、設定したportが12434かを確認します。container内からのbase URLはDesktopとEngineで異なるため、host用URLと混ぜません。APIを外部へ公開して解決するのではなく、まずCLI動作へ戻ります。

401を期待したが認証されない

故障ではありません。公式REST APIはAPI key不要で、Authorization headerを無視すると明記しています。安全性はkeyではなく到達範囲で確保します。LAN、公開cloud、共有Docker networkへ露出している疑いがあればTCPを無効にし、local CLIだけへ戻してください。

memory不足または応答が極端に遅い

同時にcontext、model、backendを変えず、小型Q4 modelへ戻します。DockerのRequests／Logs画面またはdocker model logsで、load errorと推論中の問題を分けます。必要memoryの考え方はローカルLLMに必要なVRAMの計算方法も参照してください。

次に進む条件

docker model status、1回のCLI応答、localhost APIの3点を同じmodel tagで確認できたら、初回成功です。次に独自GGUFをOCI artifactへpackageする場合は、file hash、license、tag、engine、API到達範囲を固定します。

詳しいformat分岐、registry配布、host／containerのbase URL、未認証APIの境界設計は、Docker Model RunnerのOCI配布とAPI境界を検証で扱います。

参考資料

Docker公式：Docker Model Runner overview（2026年8月6日確認）
Docker公式：Get started with DMR（2026年8月6日確認）
Docker公式：DMR REST API（2026年8月6日確認）
Docker公式：docker model run CLI reference（2026年8月6日確認）