Docker Model Runner 架构解剖：三引擎怎么选

Docker 把本地大模型塞进了容器的世界观里。以前 Ollama 是一个需要单独装、单独开服务、独立占端口的「进程」；Docker Model Runner（DMR）换了个思路：模型变成一个 OCI 制品，用 docker model 这套命令管，接口直接暴露成 OpenAI 兼容端点，挂回 12434 端口。这个变化看着只是换了个命令行，实际上把「本地跑模型」这件事的边界重新划了一次。下面按 Docker 官方文档逐项拆解，包括三个引擎的能力差异，以及我在文档里挖到的、官方自己写明的限制。

TL;DR：

-默认引擎 llama.cpp 就够用：支持 GGUF 格式、全平台（macOS/Windows/Linux）、是 DMR 里唯一支持纯 CPU 推理的引擎，装好即用不需要额外配置。

-vLLM 只在你有 NVIDIA GPU 时才有意义：仅支持 Linux x86_64（Windows 需 WSL2 + Docker Desktop 4.54+），仅支持 Safetensors 格式，官方明确写了不支持 CPU-only 推理。

-Diffusers 只管图像生成：用 DDUF 格式，管 Stable Diffusion 这类扩散模型，不做文本生成，同样不支持 CPU 推理。

-容器内连不上多数不是 bug：容器要用的地址是 http://model-runner.docker.internal，不是localhost——宿主机进程才用 localhost:12434，这是两个完全不同的口径。

-部署红线：DMR 的 API默认没有任何鉴权，官方文档写明它会忽略 Authorization 头。不要把12434 端口暴露到局域网或公网。

一、DMR 到底改变了什么：从「进程」到「制品」

理解 DMR 最快的方式，是先看它把什么东西换掉了。

Ollama 的模型是一个独立服务，你用 ollama run 拉起一个进程，它监听自己的端口，模型存放在自己的目录里。你的应用通过网络去调它——如果应用本身也在容器里，就得额外配置容器到宿主机的网络通路。

DMR 的做法不同。官方文档的表述是：模型被打包为 OCI 制品（package GGUF files as OCI Artifacts），通过 docker model 这组命令拉取和运行，对外暴露 OpenAI 兼容接口。这个差异带来的直接后果是：已经标准化使用 Docker 的团队，不需要再运维一个「额外的服务」。

三个官方命令构成了基本工作流：

docker model pull ai/llama3.2:3B-Q4_K_M   # 拉取模型
docker model run ai/smollm2                # 运行
docker model status                        # 查看各引擎状态

docker model status 的输出长这样，它会逐个引擎报告装没装：

Docker Model Runner is running
Status: llama.cpp: running
        llama.cpp version: 34ce48d
        mlx: not installed
        sglang: sglang package not installed
        vllm: ...

如果你想要非默认的后端，官方提供 install-runner：

docker model install-runner --backend vllm --gpu cuda

--backend 接受 llama.cpp、vllm、diffusers；--gpu 接受 cuda、rocm、vulkan、metal（具体可用值取决于平台）。官方同时给了一条包模型进registry 的命令，走 OCI 分发的团队会用得上：

docker model package --gguf ./model.gguf --push myorg/mymodel:Q4_K_M

二、三引擎对比表：官方原表逐项对照

这是官方文档里的引擎对比表原样内容，我只做翻译与批注，不改动任何数值：

特性	llama.cpp	vLLM	Diffusers
模型格式	GGUF	Safetensors、HuggingFace	DDUF
平台	全部（macOS、Windows、Linux）	仅 Linux x86_64	Linux（x86_64、ARM64）
GPU 支持	NVIDIA、AMD、Apple Silicon、Vulkan	仅 NVIDIA CUDA	仅 NVIDIA CUDA
CPU 推理	支持	不支持	不支持
量化	内置（Q4、Q5、Q8 等）	有限	有限
内存效率	高（配合量化）	中等	中等
吞吐	良好	高（配合批处理）	良好
最适合	本地开发、资源受限环境	生产环境、高吞吐	图像生成

这张表里有三行值得单独说：「CPU 推理」那一行是分水岭。官方对 vLLM 的原话是：vLLM requires an NVIDIA GPU with CUDA support. It does not support CPU-only inference. 这意味着如果你的机器没有 NVIDIA 卡，装 vLLM 是白费功夫。而在 Apple Silicon 上，vLLM 那一栏官方直接标了 macOS - Not supported。「模型格式」决定你手上有什么模型就用不了什么引擎。社区里绝大多数量化模型是 GGUF，那是 llama.cpp 的地盘；HuggingFace 上的原始权重通常是 Safetensors，那是 vLLM 的地盘。官方也提到 Safetensors 模型「通常比量化 GGUF 模型占用更多内存」。Diffusers 的定位完全不同，它不在文本生成这条线上——官方把它归为 image generation（Stable Diffusion）。

vLLM 的平台限制要记牢

官方给的vLLM 平台支持表非常明确：

平台	GPU	状态
Linux x86_64	NVIDIA CUDA	支持
Windows（WSL2）	NVIDIA CUDA	支持（需 Docker Desktop 4.54+）
macOS	—	不支持
Linux ARM64	—	不支持
AMD GPU	—	不支持

另外 vLLM 的模型标签通常带 -vllm 后缀来区分：

docker model run ai/smollm2-vllm

三、容器连不上：两个地址口径别搞混

这是 DMR 使用中最容易踩的一坑，官方文档专门用一张表区分了四种访问方式。

运行方式	访问方	Base URL
Docker Desktop	容器	http://model-runner.docker.internal
Docker Desktop	宿主机进程（TCP）	http://localhost:12434
Docker Engine	容器	http://172.17.0.1:12434

| Docker Engine | 宿主机进程 | http://localhost:12434 |容器里用 localhost 是错的。容器有自己的网络命名空间，localhost 指向容器自己，而不是宿主机。这不是配置问题，是网络模型决定的。

官方还给了一条兜底方案——如果 172.17.0.1 在你的 Compose 项目里不可用（官方原文说这个接口在 Compose 项目内默认可能不可用），需要加extra_hosts：

extra_hosts:
  - "model-runner.docker.internal:host-gateway"

三种兼容 API 的 Base URL 各不相同

同一套DMR 服务，对不同客户端要给不同的 Base URL。官方表格：

工具类型	Base URL
OpenAI SDK / 客户端	http://localhost:12434/engines/v1
Anthropic SDK / 客户端	http://localhost:12434
Ollama 兼容客户端	http://localhost:12434

OpenAI 兼容 API 的端点清单（官方原表）：

端点	方法	说明
/engines/v1/models	GET	列出模型
/engines/v1/models/{namespace}/{name}	GET	检索模型
/engines/v1/chat/completions	POST	创建对话补全
/engines/v1/completions	POST	创建补全
/engines/v1/embeddings	POST	创建嵌入

注意那个 /engines/ 前缀——OpenAI 兼容客户端不能直接用 http://localhost:12434/v1，少了 /engines 会 404。这是移植 Ollama 配置到 DMR 时最常见的失败点。

官方还提到你可以在路径里带上引擎名，比如 /engines/llama.cpp/v1/chat/completions，这在同时跑多个引擎时有用。

Anthropic 兼容 API 的端点是：

端点	方法	说明
/anthropic/v1/messages	POST	创建消息
/anthropic/v1/messages/count_tokens	POST	计算 token 数

官方给的示例里有个容易忽略的细节：

curl http://localhost:12434/v1/messages \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ai/smollm2",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "..."}]
  }'

注意路径是 /v1/messages 而不是 /anthropic/v1/messages——官方示例与端点表存在这个差异，实际以你的客户端配置为准。模型名要用带命名空间的完整标识（如 ai/smollm2）。

四、官方自己写明的限制（这部分最重要）

DMR 文档里有一节专门叫「Limitations and differences from OpenAI」，原文表格如下：

特性	DMR 行为
API key	不需要。DMR 忽略 Authorization 头。
Function calling	仅 llama.cpp 对兼容模型支持
Vision	支持多模态模型（如 LLaVA）
JSON mode	支持，通过 response_format: {"type": "json_object"}
Logprobs	支持
Token 计数	使用模型原生 token 编码器，可能与 OpenAI 不同

这五条里，有两条会直接影响你的迁移工作：API key 那一行是部署红线。官方文档的意思很明确——DMR 不要求 API key，并且直接忽略你发来的 Authorization 头。这意味着任何能访问到 12434 端口的客户端都可以提交推理请求，也可能拉取、加载或运行模型。所以：不要把这个端口暴露在不可信的局域网、共享 CI 网络，或任何公网可达的开发者主机上。Function calling 只在 llama.cpp 下可用。如果你的应用依赖 function calling，就不能切到 vLLM 后端——这是引擎选型时容易被忽略的硬约束。Token 计数可能与 OpenAI 不同，意味着按 token 计费或做上下文预算时要留余量。

五、官方 Troubleshooting 里点名的两类问题

DMR 的文档有一节 Troubleshooting，标题就是几个典型症状。这里列出官方给出的排查方向：vLLM 装不上 / 起不来。官方给的排查第一步是确认 NVIDIA GPU 可用。结合前面那张平台表，遇到这个问题基本可以直接定位：AMD GPU、macOS、Linux ARM64 都不支持，不是配置能解决的。llama.cpp 慢。官方把这一项和「内存不足错误」并列，说明这两者在使用体验上往往相关。

官方还提供了查看引擎日志的命令：

docker model logs

排查时先看这个，比猜要快。

六、DMR 还是 Ollama：怎么选

在有第二个来源交叉印证这一点上，我用多个独立技术来源做了对照，结论是：单机本地开发选哪个都行，差异主要在工程治理而不是性能。

两者的推理峰值内存接近，因为底层都跑 llama.cpp。真正的差异在别处：

-模型分发：DMR 走 OCI 制品与registry，Ollama 走自己的模型库与 Modelfile。如果你需要镜像仓库那种版本治理与审计能力，DMR 更顺。

-空闲内存：Ollama 默认把模型留在内存里（OLLAMA_KEEP_ALIVE，默认 5 分钟），首响应更快但空闲占用高；DMR 空闲时会卸载模型。

-鉴权：两边都不该把端口直接暴露，DMR 是明确忽略 Authorization 头，Ollama 也需要自行处理网络隔离。

-「OpenAI 兼容」不等于行为一致：有来源实测指出，DMR 用的是引擎感知的路径（/engines/llama.cpp/v1/...），Ollama 的原生对话 API 是 /api/chat，两者都能塞进现有客户端，但请求字段、流式分块、错误结构、用量数据都要实测过再切。

还有一个容易被忽略的点：如果你要的是多用户或生产级高并发服务，两个都不该直接上。第三方对比文章里的建议是转向独立部署的 vLLM、SGLang 或 Kubernetes serving 栈——笔记本上的基准只能回答开发体验问题，不能确立生产吞吐、尾延迟或多租户隔离。

五、常见报错与排查路径

以下是Docker 官方文档 Troubleshooting 一节列出的症状与对应处理。

报错一：vLLM 装不上或起不来（docker model install-runner --backend vllm 后无反应）

官方给的排查第一步是确认 NVIDIA GPU 可用。结合前面的平台表，这类问题通常可以直接定位：

AMD GPU、macOS、Linux ARM64 三种环境官方均标注 Not supported，不是配置能解决的。

另外vLLM 只吃 Safetensors 格式，如果你手上是 GGUF 量化模型，它不会识别。

docker model status# 逐个引擎看安装与运行状态
docker model logs                # 看引擎日志

报错二：容器里连不上，提示 connection refused 或 404

分两种情况，判据不同：

• 连不上（网络层不通）：容器里用了 localhost。容器有独立网络命名空间，localhost 指向容器自己。

容器应改用 http://model-runner.docker.internal。

• 返回 404（HTTP 层通了但路径不对）：OpenAI 兼容客户端少了 /engines 前缀。

正确地址是 http://localhost:12434/engines/v1，直接用 /v1 会 404。

这两种报错的共同点是看起来都像「连不上」，但一个在网络层、一个在路径层，必须先分清再动手。

报错三：llama.cpp 跑得慢

官方把这一项与内存不足错误并列，通常是同一个问题的两种表现。可先确认模型量化档位与上下文长度设置，

再结合 docker model logs 看是否有内存告警。

常见问题

Q1：Docker Desktop 需要什么版本？

官方文档中 vLLM 在 Windows WSL2 场景明确要求 Docker Desktop 4.54+。DMR 整体是随Docker Desktop 演进的能力，具体到某个子功能请以你本地版本的文档为准——不同版本提供的引擎和参数会变。Q2：能把 DMR 暴露给团队共用吗？

不建议直接这么做。官方文档写明它没有内建鉴权且忽略 Authorization 头。共享场景至少要做网络范围限制，必要时在前面加一层带鉴权的反向代理。Q3：Compose 里怎么声明模型依赖？

DMR 与 Compose 的集成允许把模型作为服务依赖声明，由 Compose 把模型端点与模型标识注入应用容器，而不是硬编码在应用配置里。具体字段与版本要求请查你所用 Compose 版本的官方文档。Q4：模型格式选错会怎样？

会拉不到或者起不来。llama.cpp 用 GGUF，vLLM 用 Safetensors，Diffusers 用 DDUF。拉错格式的典型表现是引擎不认这个制品。Q5：Docker Engine（非 Desktop）能用吗？

可以，但访问地址口径不同：容器走 http://172.17.0.1:12434，宿主机进程走 http://localhost:12434，且官方提示该接口在 Compose 项目内默认可能不可用，需要 extra_hosts。

本文涉及的接口路径、端点清单、引擎能力与限制均取自 Docker 官方文档（截至发稿 2026 年 10 月 11 日）：

• 模型运行器总览：https://docs.docker.com/ai/model-runner/
• 推理引擎与对比表：https://docs.docker.com/ai/model-runner/inference-engines/
• API 参考与限制：https://docs.docker.com/ai/model-runner/api-reference/
• Compose 集成：https://docs.docker.com/compose/bridge/use-model-runner/

需要说明的是：本文未采用任何未经官方文档证实的性能数字。第三方对比文章中出现的吞吐量、tokens/s 等实测值，因其测试环境（硬件、模型、量化档位）与本文读者环境差异过大，且无法回溯原始测试配置，故未引用为结论。

本文不含联盟链接。文中所有接口路径、端点清单与引擎能力均取自 Docker 官方文档，未采用任何未经官方证实的性能数字。

👉 立即参与小米 MiMo 开放平台：国内领先的 AI 大模型开放平台，高性价比推理服务

👉 立即参与阿里云 AI：汇集爆款 AI 产品，热门模型专属权益优惠券助力企业创新加速

📌 本文由 AI 辅助生成并经人工审核发布 | TechPassive — AI 驱动的内容测试站点，专注于效率工具与 SaaS 真实评测