深入AI模型分发规范：Docker Model Runner如何用OCI打包与传输模型

Docker Model Runner 是 Docker 官方的 AI 模型运行工具，它的一个核心亮点是：直接用OCI（Open Container Initiative）规范来打包和传输 AI 模型。你不再需要手动下载几十 GB 的 GGUF / safetensors 文件——一条docker model pull命令，就能像拉取容器镜像一样，从 Docker Hub 或任意 OCI 兼容的 registry 把模型拉下来，并支持断点续传、并行上传、多架构 manifest 等"镜像级"的能力。本文带你深入它的模型分发规范，看懂 Docker Model Runner 是怎么用 OCI 打包模型的。

为什么模型分发需要一套 OCI 标准？

AI 模型文件动辄几个 GB 到上百 GB，传统分发方式存在几个痛点：

• 没有统一格式：GGUF、safetensors、DDUF、diffusers 目录……各家各不同；
• 下载体验差：大文件下载中断就要从头再来；
• 缺少校验与版本管理：无法像镜像一样通过 digest 精确锁定版本。

Docker Model Runner 的解法是：把模型当作一种OCI 制品（Artifact），复用容器镜像几十年积累的 registry 基础设施——manifest、layer、content-addressed 存储、Range 断点续传，全部照搬。相关实现集中在 pkg/distribution/ 目录下，架构设计文档可参考 MODEL_TYPES.md。

拆解一个模型的 OCI 包：Manifest、Config 与 Layers

一个模型包在 registry 里的结构和容器镜像几乎一致，定义在 pkg/distribution/oci/manifest.go 中：

几个关键设计：

1. 每个文件一个 Layer

模型权重文件按文件拆分成 layer，每个 layer 用 OCI 媒体类型标注内容。这些媒体类型定义在 pkg/distribution/types/config.go：

application/vnd.docker.ai.gguf.v3 # GGUF 权重（v3） application/vnd.docker.ai.safetensors # safetensors 权重 application/vnd.docker.ai.dduf # Diffusers Unified Format application/vnd.docker.ai.mmproj # 多模态 projector application/vnd.docker.ai.chat.template.jinja # Jinja 对话模板 application/vnd.docker.ai.license # 许可证文本

2. 配置版本化演进

模型 config 有两版媒体类型（见 config.go）：v0.1 是遗留格式；v0.2（application/vnd.docker.ai.model.config.v0.2+json）采用"每文件一个 layer + 文件路径注解"的方式，能保留嵌套目录结构（例如text_encoder/model.safetensors这类 diffusers 模型的目录布局）。

3. 自动识别模型格式

打包时不需要手动指定格式，构建器会自动按文件扩展名识别 GGUF / safetensors / DDUF，并发现分片文件（shard）。逻辑在 pkg/distribution/format/format.go 的DetectFromPath，各格式的具体处理策略（如 dduf.go）通过注册表模式接入，方便扩展新格式。

双格式支持：Docker 格式与 CNCF ModelPack

Docker Model Runner 并非只认自家格式。构建器（pkg/distribution/builder/builder.go）支持两种输出：

• Docker 格式（默认）：application/vnd.docker.ai.*媒体类型；
• CNCF ModelPack 格式：application/vnd.cncf.model.*媒体类型，manifest 的artifactType为application/vnd.cncf.model.manifest.v1+json。

ModelPack 的原生支持在 pkg/distribution/modelpack/types.go 中实现——它直接复用官方 model-spec 的类型定义，保证与 CNCF 规范同步。这意味着你既能 pull 用modctl等第三方工具打包的 ModelPack 模型，也能把自己的本地模型以 ModelPack 格式 push 出去，实现跨工具生态互通。

本地存储：像容器一样内容寻址

pull 下来的模型存放在一个本地 store 中，核心实现是 pkg/distribution/internal/store/store.go。目录结构非常眼熟——和 OCI layout 规范一脉相承：

• layout.json：store 版本标记（当前为1.0.0）；
• models.json：模型索引，记录所有已拉取模型的引用与 tag；
• blobs/sha256/...：内容寻址的 blob 存储，相同内容的权重文件天然去重。

这套设计带来两个实用特性：一是安全——Reset清理前会先校验layout.json是否存在，防止误删非模型目录（见 store.go#L51-L70）；二是自动清理——初始化时会清理超过 7 天的未完成下载文件，避免中断的下载泄漏磁盘空间。

传输层：断点续传与并行上传

大模型传输的关键在 registry 交互层 pkg/distribution/oci/remote/remote.go，它基于 containerd 的 remotes 实现，针对"大文件"场景做了专门优化：

• Range 断点续传：内部有一个rangeTransport，在下载时附加 HTTPRange头，并会在传输层手动跟随重定向（最多 10 跳），确保 registry 把 blob 请求重定向到 CDN 后，续传偏移量信息不丢失；
• 有界并行上传：push 时最多 5 个 layer 并行上传（maxConcurrentLayerPushes = 5），既提速又避免打满 registry 连接；
• Registry 镜像加速：支持配置 registry mirror，优先走镜像源拉模型。

上手体验：三条命令感受 OCI 模型分发

理解了规范，实际使用却非常简洁。CLI 命令定义见 pkg/../cmd/cli/commands/pull.go，完整命令参考 cmd/cli/docs/reference/：

# 从 Docker Hub 拉取模型 docker model pull ai/smollm2 # 从 HuggingFace 拉取 GGUF（未指定 tag 时默认 Q4_K_M 量化版） docker model pull hf.co/bartowski/Llama-3.2-1B-Instruct-GGUF # 推送到 Docker Hub 或 Hugging Face docker model push mymodel:latest

不依赖 Docker 的用户可以直接使用独立二进制dmr（构建入口见 cmd/dmr/），dmr pull ai/gemma3即可走完全相同的 OCI 分发流程。

总结：镜像基础设施在模型世界的复用

Docker Model Runner 的模型分发规范可以概括为三个词：

1. 标准化：模型即 OCI 制品，Manifest + Config + Layers 三件套，媒体类型精确到文件角色；
2. 可互通：原生支持 CNCF ModelPack，与modctl等社区工具生态打通；
3. 可靠传输：内容寻址去重、Range 断点续传、CDN 重定向感知、有界并行上传。

这套方案的启发在于：当 AI 模型体量逼近容器镜像时，直接复用成熟的 registry 基础设施，是比另起炉灶更聪明的选择。