Docker Model Runner：使用 Docker 运行 LLM，无需 Ollama

#为什么使用 Docker Model Runner？

Docker Model Runner 是 Docker 对 Ollama 的回应：让您无需离开 Docker 生态系统，就能在本地运行 LLM。您不再需要单独管理守护进程或另设模型目录——模型以 OCI 制品的形式分发，从注册表拉取的方式与容器镜像完全相同，并通过一组新的 docker model 命令进行控制。

从技术上看，Model Runner 底层的推理引擎与 Ollama、LM Studio 和 Jan 相同，都是 llama.cpp。因此，区别在于集成，而非纯粹的运行速度。如果您的电脑或服务器已经在使用 Docker，Model Runner 就能让您免于再添加一个工具，并让容器自然地与本地模型交互。

OCI格式模型

LLM 可以像 Docker 镜像一样拉取、进行版本管理和推送。使用同样的镜像仓库、同样的身份验证方式，也沿用同样的操作习惯。

兼容 OpenAI 的 API

端点路径 /engines/v1/chat/completions、/completions、/models。任何 OpenAI 客户端只需更改基础 URL 即可接入。

无需额外工具

无需另外安装 Ollama。使用 docker CLI 即可，推理功能也能集成到 Compose 中。

直接使用 GPU

引擎在主机上运行（Apple Silicon 通过 Metal，NVIDIA 通过 CUDA），而不是在容器中运行，以避免失去加速效果。

#先决条件

较新版本的 Docker Desktop

Model Runner 随 Docker Desktop 4.40 推出，最初用于搭载 Apple 芯片的 macOS，随后扩展到配备 NVIDIA GPU 的 Windows。请更新至最新可用版本。

或在Linux上使用Docker Engine

在无Docker Desktop的Linux服务器上，Model Runner可通过docker-model-plugin包安装（详见下文）。

显存或统一内存

在 Q4_K_M 量化下，3B 模型约需 2 GB，7B 模型约需 5 GB，14B 模型约需 9 GB，32B 模型约需 19 GB。在 Mac 上，统一内存可作为显存使用。

建议使用 GPU

入门可选 RTX 3060 12 GB，中端可选 RTX 4070/4080，运行大模型则可选 RTX 4090 24 GB 或 Mac M4 Pro（24–48 GB 统一内存）。仅靠 CPU 也能运行，但速度较慢。

#1. 启用Docker Model Runner

该功能并不总是默认启用。在 Docker Desktop 中，可以在设置中找到它；通过命令行，只需一条指令即可启用。

1. 01
   通过 Docker Desktop

   打开 Settings → AI（或「Beta features」，视版本而定），勾选「Enable Docker Model Runner」。若需从主机调用 API，还需开启「Enable host-side TCP support」，并记录建议端口（默认为 12434）。
2. 02
   通过命令行界面

   一条命令即可启用服务，并可选择在宿主机上开放 TCP 端口，以便从您的机器访问 API，无需经过容器。
3. 03
   检查

   docker model status confirme que le runner tourne. docker model version affiche la version du plugin installé.

# Activer Model Runner
docker desktop enable model-runner

# Activer + exposer l'API sur le port hôte 12434
docker desktop enable model-runner --tcp 12434

# Vérifier l'état
docker model status

在配备 Docker Engine 的 Linux 服务器上（不使用 Docker Desktop），Model Runner 以插件形式添加。在 Debian/Ubuntu 发行版上：

sudo apt-get update
sudo apt-get install docker-model-plugin

# Confirmer
docker model version

#2. 下载 OCI 格式模型

Docker 在 Docker Hub 的 ai/ 命名空间下托管了以 OCI 格式打包的模型库。用户可像拉取镜像一样使用 docker model pull 命令获取模型。标签中编码了模型的大小和量化方式。

# Un petit modèle pour tester rapidement
docker model pull ai/smollm2

# Un modèle plus capable, tag explicite
docker model pull ai/qwen3.5

# Une variante quantifiée précise (taille + quantization)
docker model pull ai/gemma4:12B-Q4_K_M

# Lister ce qui est stocké localement
docker model ls

ai/smollm2

非常小的模型，即使没有 GPU，也很适合在几秒内验证安装是否成功。

ai/qwen3.5 · ai/gemma4 · ai/granite4.2

2026 年表现可靠的通用模型；请根据您的显存容量选择模型规模（2B、4B、9B、12B 等）。在 8 GB 显存上，Qwen 3.5 9B（Q4 量化下约 6.6 GB）是一个合适的默认选择；这些模型均采用 Apache 2.0 许可协议。

量化标签

9B-Q4_K_M 这样的标签标明了模型规模和压缩方式。Q4_K_M 是推荐的质量与内存占用折中方案；Q5_K_M 和 Q8_0 占用的空间更大。

OCI 格式意味着这些模型可以存放在任何兼容的镜像仓库中：既可以是 Docker Hub，也可以是企业私有仓库。因此，您可以像推送镜像一样推送内部模型，使用相同的身份验证方式和访问策略。

#3. 使用 docker model run 进行对话

如同 docker run 启动一个容器，docker model run 启动一次对话。不传消息参数时，会在终端中打开一个交互式聊天界面；传入提示词后，模型仅响应一次并交出控制权——非常适合脚本使用。

# Chat interactif
docker model run ai/qwen3.5

# Prompt unique (mode « one-shot », scriptable)
docker model run ai/qwen3.5 "Explique le format OCI en une phrase."

首次调用模型时会将其加载到内存中；后续调用则复用已加载的实例。模型闲置一段时间后，引擎会自动将其卸载以释放显存，无需您管理守护进程。

# Détails d'un modèle (taille, quantization, architecture)
docker model inspect ai/qwen3.5

# Logs du moteur d'inférence
docker model logs

# Supprimer un modèle pour récupérer de l'espace disque
docker model rm ai/smollm2

#4. 兼容 OpenAI 的 API

Docker Model Runner 的真正优势，就像 Ollama 一样，是其兼容 OpenAI 的 API。任何为 OpenAI API 设计的工具，只需更改基础 URL 即可运行。根据调用位置，存在两种地址。

从主机访问（TCP）

http://localhost:12434/engines/v1/… si vous avez activé le support TCP côté hôte (port 12434 par défaut).

从容器中

http://model-runner.docker.internal/engines/v1/… — un nom DNS interne résolu automatiquement dans le réseau Docker.

在启用 TCP 端口后，通过 curl 从主机直接调用聊天接口：

curl http://localhost:12434/engines/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ai/qwen3.5",
    "messages": [
      {"role": "system", "content": "Tu réponds en français, de façon concise."},
      {"role": "user", "content": "Qu'\''est-ce qu'\''un artefact OCI ?"}
    ]
  }'

model 字段必须对应已拉取到本地的模型。使用 OpenAI 的 Python SDK 时，只需将 base_url 指向本地服务；API 密钥可以是任意字符串，Model Runner 在本地不要求提供 API 密钥。

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:12434/engines/v1",
    api_key="docker",  # non vérifiée en local
)

resp = client.chat.completions.create(
    model="ai/qwen3.5",
    messages=[
        {"role": "user", "content": "Donne trois idées de noms pour un projet open source."}
    ],
)
print(resp.choices[0].message.content)

#5. 将容器连接到模型

Docker 集成的优势在此体现：您的应用容器可通过内部 DNS 调用模型，而无需在主机上暴露端口。容器内运行的代码中，基础 URL 变为 model-runner.docker.internal。

curl http://model-runner.docker.internal/engines/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ai/qwen3.5",
    "messages": [{"role": "user", "content": "Bonjour"}]
  }'

实际使用中，通过环境变量传递 URL，让同一份代码既能在本地运行（端口 12434），也能在容器中运行（内部 DNS）。以下是将端点注入应用服务的 docker-compose.yml 片段：

services:
  app:
    build: .
    environment:
      OPENAI_BASE_URL: http://model-runner.docker.internal/engines/v1
      OPENAI_API_KEY: docker
      MODEL_NAME: ai/qwen3.5

#Docker Model Runner 或 Ollama，根据您的工作流选择

两者均运行 llama.cpp 并提供兼容 OpenAI 的 API。选择取决于您所处的生态系统，而非纯粹的性能表现。

选择 Model Runner

当Docker已经是您的基础平台时：您希望容器能通过Docker网络与LLM通信，通过私有OCI注册表分发模型，并避免安装和维护额外工具。

选择 Model Runner

适用于这样的 Compose 技术栈：模型是其中的一项服务，与您的镜像采用同样的方式进行版本管理和部署。

继续使用Ollama

当您希望拥有最广泛、最新的模型目录，活跃的社区和丰富的文档，以及无需 Docker Desktop 就能在 Windows、macOS 和 Linux 上以相同方式运行的工具时。

继续使用Ollama

对于简单的办公用途，如果不涉及任何容器化环境，在端口 11434 上运行 Ollama 仍是最直接的选择，而且已有一套与之对接的界面生态（Open WebUI、LM Studio）。

#故障排除

« docker: 'model' is not a docker command »

插件未安装，或 Model Runner 未启用。请更新 Docker Desktop，启用该功能，或在 Docker Engine 上安装 docker-model-plugin。

API 在 localhost:12434 上未响应

主机端的 TCP 支持尚未启用。请重新运行 docker desktop enable model-runner --tcp 12434，或在 Settings → AI 中勾选相应选项。

容器无法连接到模型

从容器中使用 model-runner.docker.internal，而非 localhost：localhost 指向容器自身，而非主机。

加载缓慢或出现“out of memory”错误

模型所需的显存超过了您的显存容量。请拉取更轻量的版本（使用 Q4_K_M 标签，而不是 Q5/Q8）或更小的模型，并检查 GPU 是否被正确识别。

未使用 GPU（Windows）

Windows 下对 NVIDIA GPU 的支持是在最初发布之后才加入的。请确保您使用的 Docker Desktop 版本支持这一功能，并且驱动程序已更新至最新版本。

#深入了解

Docker Model Runner 与网站上已覆盖的其他本地 AI 组件结合使用，体验更佳：

安装 Ollama：Windows、macOS 和 Linux

用于实际对比作为参照的替代方案及其 11434 端口，并判断哪一种更符合您的工作流。

Q4、Q5、Q8：选择哪种量化

用于正确理解 OCI 模型标签（7B-Q4_K_M 等），并在拉取模型前权衡质量、速度和内存需求。

llama-server：基于llama.cpp的本地OpenAI API服务

了解同一引擎如何以另一种方式提供服务，并更精细地控制 GPU 卸载。