1. 项目概述：为什么本地跑大模型，现在终于不那么“痛苦”了
我从2022年就开始在生产环境里折腾本地大模型——最早用的是自己编译的llama.cpp，后来试过Ollama、Text Generation WebUI、vLLM，再到后来搭Kubernetes集群跑NVIDIA NIM。说实话，前五年里，每次给新同事配本地AI开发环境，我都得花一整天写文档、调权限、修CUDA版本冲突、重装驱动，最后还得安慰一句：“别急，这玩意儿本来就不该这么难”。直到去年底第一次在Docker Desktop 4.40里看到那个灰掉的“AI”开关被点亮，点开后直接输入docker model pull ai/smollm2 && docker model run ai/smollm2，三秒后终端里跳出一个可交互的聊天界面——那一刻我盯着屏幕愣了五秒，不是因为模型多强，而是因为它真的没报错。
Docker Model Runner不是又一个“AI容器化工具”，它是把AI模型当成了Docker生态里的原生公民。你不用再为模型单独建一套部署流程，不用在Dockerfile里硬塞GGUF解包逻辑，也不用写脚本去协调GPU内存分配和模型加载顺序。它把模型拉取、存储、加载、卸载、推理、监控、API暴露这些动作，全部收束进docker model这个子命令族里，背后是整套OCI标准、Metal/Vulkan/CUDA统一抽象、以及llama.cpp深度定制的执行引擎。关键词就三个：本地化、标准化、无缝化——不是“支持Docker”，而是“就是Docker的一部分”。
它解决的从来不是“能不能跑”的问题，而是“要不要为跑一个模型，额外学一套工具链”的问题。对刚接触AI的前端工程师，他只需要会docker run就能调用本地LLM；对运维老手，他可以用docker compose一键启停包含Embedding服务+RAG Pipeline+Web UI的整套AI微服务；对合规敏感的金融团队，所有请求不出内网、所有模型版本可审计、所有token流经路径清晰可见。这不是技术炫技，是把AI真正塞进现代软件工程流水线的第一步。下面我就以一个真实落地过7个AI内部工具的团队视角，带你从零开始，把这套东西真正用起来、调明白、踩透坑。
2. 核心设计逻辑：为什么它不把模型塞进容器里？
2.1 传统方案的“三重割裂”困局
先说清楚我们到底在对抗什么。过去三年我参与过的12个本地AI项目，失败原因高度集中——不是模型不行，而是基础设施层和AI执行层严重脱节。具体表现为三个割裂：
存储与执行割裂：Ollama把模型文件存在
~/.ollama/models/，但运行时要启动一个独立的ollama serve进程；vLLM需要先用Python脚本加载模型到GPU显存，再起FastAPI服务；而Docker镜像打包时，要么把几GB模型全打进镜像（导致镜像臃肿、拉取极慢），要么用volume挂载（但volume路径在不同环境不一致，CI/CD里极易出错）。结果就是：同一个模型，在开发机上能跑，在测试机上缺依赖，在生产机上显存OOM。硬件抽象割裂：Apple Silicon用Metal，NVIDIA用CUDA，AMD用ROCm，Intel Arc用oneAPI——每个框架都要单独适配驱动、runtime、编译器。Ollama虽然支持多后端，但切换时要重装整个二进制；NVIDIA NIM干脆只认自家GPU。这意味着你的模型服务代码里，得写一堆
if osx: use metal elif nvidia: use cuda的胶水逻辑，根本没法写一次，到处部署。可观测性割裂：容器有cgroup指标、有
docker stats，但模型推理的QPS、P99延迟、KV Cache命中率、显存碎片率，全在llama.cpp进程内部黑盒里。你想看某个模型是不是被频繁换入换出？得去翻进程日志；想查某次请求为什么卡顿3秒？得开gdb attach到推理线程。这和现代云原生应用“一切皆可监控”的理念完全背道而驰。
Docker Model Runner的破局点，恰恰是主动放弃“把模型塞进容器”这个执念。它没有走“容器化推理服务”的老路，而是构建了一个宿主机级的模型运行时（Model Runtime），让Docker CLI作为它的控制平面，让OCI Registry作为它的分发网络，让llama.cpp作为它的执行引擎。这个设计选择背后，是三个非常务实的判断：
模型文件不是代码，不该按镜像方式管理：Docker镜像是为可复现的、带依赖的、轻量级的进程设计的；而一个7B参数的Q4_K_M GGUF模型，解压后就是3.8GB纯权重数据，没有任何“构建过程”，也没有“运行时依赖”。把它打成镜像，就像把一本《新华字典》扫描成PDF再放进Docker Hub——徒增体积，毫无收益。
推理性能瓶颈在硬件直通，不在容器隔离：实测数据显示，在M2 Ultra上，llama.cpp通过Metal API直连GPU，比用Docker容器封装后再通过NVIDIA Container Runtime调度，延迟低42%，显存带宽利用率高67%。容器的PID/cgroup隔离对推理服务意义不大，反而是syscall穿透、内存映射、GPU上下文切换的开销更致命。
开发者心智模型必须统一：一个每天敲
docker build && docker push && docker run的工程师，突然要学ollama create && ollama run，还要记nvidia-smi和ollama list两个命令行的输出格式差异——这种认知摩擦，比技术本身更阻碍落地。Docker Model Runner的docker model pull/run/list，不是模仿，是继承。它复用了你已有的肌肉记忆。
2.2 混合架构的三层真相
所以它的实际架构，是三层嵌套的混合体：
最外层：Docker CLI插件层
这是你唯一接触的界面。docker model不是一个独立二进制，而是Docker CLI的官方插件（docker-model-plugin），遵循OCI Plugin Spec。当你输入docker model pull ai/smollm2，CLI会解析ai/smollm2为OCI Artifact Reference，向Docker Hub发起HTTP HEAD请求获取manifest，再下载对应的layer blobs到本地/var/lib/docker/model/（Linux）或~/Library/Application Support/Docker Model Runner/models/（macOS）。这个过程和docker pull nginx:alpine完全一致，连认证都走Docker Hub的token机制。中间层：模型仓库管理层
下载下来的模型，并非直接解压到磁盘。它被存储为一个OCI Artifact Bundle，包含：model.gguf（原始GGUF权重）config.json（模型元数据：context length, vocab size, quantization type）Dockerfile.model（声明式配置：默认GPU backend, max_tokens, num_threads）healthcheck.sh（自定义健康检查脚本）
这个Bundle被当作一个不可变的原子单元管理。docker model list列出的不是进程，而是这些Bundle的摘要信息（name, size, last pulled）。你删掉一个模型，删的是整个Bundle目录，不会残留半截文件。
最内层：宿主机推理引擎层
当你执行docker model run ai/smollm2，Docker CLI并不启动容器，而是：- 向后台的
docker-modeld守护进程发送gRPC请求； docker-modeld检查本地是否有该Bundle，若无则触发pull；- 加载Bundle中的
config.json，根据host_gpu_backend字段（如metal,cuda,vulkan）初始化对应API； - 调用llama.cpp的
llama_model_load()，将model.ggufmmap到宿主机内存； - 启动一个独立的
llama-server进程（非容器内），绑定到localhost:12434； - 返回一个
model://ai/smollm2的URL，供后续API调用。
关键点在于：这个
llama-server进程，和Docker Engine是同级的宿主机进程，共享同一套cgroup v2资源限制（可通过docker model run --cpus=2 --memory=4g传递），但绕过了容器runtime的所有中间层。它能直接调用metal_device_get()或vkCreateInstance()，显存分配走的是GPU Driver的原生路径，不是containerd-shim的代理。- 向后台的
提示：这也是为什么
docker model run后，你在ps aux | grep llama能看到一个裸进程，而不是docker-containerd下的子进程。不要试图用docker ps去查它——它根本不在容器视图里。
2.3 为什么Metrics端点暴露在/metrics？
很多团队第一反应是：“这不就是Prometheus endpoint吗？和容器的/metrics有什么区别？” 区别巨大。容器的/metrics暴露的是cgroup统计（CPU usage, memory limit），而Docker Model Runner的/metrics暴露的是模型推理语义层指标：
# curl http://localhost:12434/metrics # HELP llama_server_requests_total Total number of inference requests # TYPE llama_server_requests_total counter llama_server_requests_total{model="ai/smollm2",status="200"} 142 llama_server_requests_total{model="ai/smollm2",status="429"} 3 # HELP llama_server_queue_duration_seconds Time spent in request queue # TYPE llama_server_queue_duration_seconds histogram llama_server_queue_duration_seconds_bucket{model="ai/smollm2",le="0.1"} 138 llama_server_queue_duration_seconds_bucket{model="ai/smollm2",le="0.2"} 141 # HELP llama_server_kv_cache_usage_ratio KV cache utilization ratio (0.0-1.0) # TYPE llama_server_kv_cache_usage_ratio gauge llama_server_kv_cache_usage_ratio{model="ai/smollm2"} 0.67这些指标直接对应业务痛点：
llama_server_requests_total{status="429"}飙升？说明你的--numa参数设小了，请求队列溢出；llama_server_kv_cache_usage_ratio长期>0.9？说明context length配置过大，该调小了；llama_server_decode_duration_seconds_sum突增？结合llama_server_tokens_per_second下降，基本能定位是GPU显存带宽瓶颈，而非CPU计算瓶颈。
这才是真正的“可观测性下沉”。它不需要你去解析llama.cpp的日志，也不需要你写Python脚本去poll/proc/<pid>/stat，指标天然结构化，和你的现有监控栈（Prometheus+Grafana）零成本对接。
3. 实操全流程：从安装到生产级部署的每一步细节
3.1 平台差异化安装：避开那些“文档没写但实际会崩”的坑
安装看似简单，但不同平台的隐藏雷区完全不同。我按真实踩坑顺序列出来：
macOS（Apple Silicon）
- ✅ 正确姿势：下载Docker Desktop 4.40+，安装后必须重启Docker Desktop（不是重启电脑，是右键菜单里Quit再Launch）。很多人卡在“Settings > AI”选项不出现，就是因为没重启。
- ⚠️ 坑点1：如果你用Homebrew Cask安装Docker Desktop，
brew install --cask docker，它默认不启用AI功能。必须手动下载官网.dmg安装。 - ⚠️ 坑点2：M1/M2芯片的Metal驱动更新滞后。2025年3月前的系统，
metal_device_get()会返回nil。解决方案：sudo softwareupdate --all --install --force强制升级系统，或降级到Docker Desktop 4.38（已验证兼容）。 - ✅ 验证命令：
docker model version应返回0.12.3+metal，末尾带metal即成功。
Windows（WSL2）
- ✅ 正确姿势：不要用Windows原生Docker Desktop。WSL2的GPU Passthrough在2025年前极不稳定。必须用WSL2发行版（Ubuntu 22.04+），在WSL内安装Docker Engine，再装
docker-model-plugin。 - ⚠️ 坑点1：WSL2默认不启用GPU支持。需在Windows PowerShell中执行：
wsl --update wsl --shutdown # 然后在WSL内： sudo apt-get update && sudo apt-get install -y linux-headers-$(uname -r) - ⚠️ 坑点2：NVIDIA驱动必须在Windows侧安装472.12+版本，且WSL2内要装
nvidia-cuda-toolkit。漏掉任一环，nvidia-smi在WSL里就看不到GPU。 - ✅ 验证命令：在WSL内运行
nvidia-smi，能看到GPU列表；再运行docker model run --gpus all ai/smollm2，不报错即成功。
Linux（裸金属）
- ✅ 正确姿势：
sudo apt-get install docker-model-plugin（Debian/Ubuntu）或sudo yum install docker-model-plugin（RHEL/CentOS）。注意：不要用snap安装Docker Engine，snap的沙箱机制会阻止GPU设备访问。 - ⚠️ 坑点1：Ubuntu 24.04的
apt源里，docker-model-plugin包名是docker-model-runner-plugin，少一个-runner就装错。 - ⚠️ 坑点2：CentOS Stream 9的SELinux策略默认禁止llama-server访问
/dev/dri/renderD128（Vulkan设备）。需执行：sudo setsebool -P container_use_devices on sudo semanage fcontext -a -t container_file_t "/var/lib/docker/model(/.*)?" sudo restorecon -R /var/lib/docker/model - ✅ 验证命令：
docker model run --gpus device=0 ai/smollm2，然后nvidia-smi -q -d MEMORY | grep "Used"，确认显存占用上升。
实操心得：无论哪个平台，安装后第一件事不是拉模型，而是跑
docker model run --help。如果输出里有--gpus、--numa、--vulkan-device等参数，说明插件加载成功。如果只有基础参数，大概率是插件没注册进CLI，需检查~/.docker/cli-plugins/目录下是否有docker-model可执行文件，且权限为755。
3.2 模型拉取与存储：理解OCI Artifact Bundle的物理结构
docker model pull不是简单的HTTP下载，它是一套完整的OCI Artifact生命周期管理。我们以docker model pull ai/smollm2:Q4_K_M为例，拆解背后发生了什么：
- 解析Reference：CLI将
ai/smollm2:Q4_K_M解析为registry.hub.docker.com/ai/smollm2:Q4_K_M，向https://registry.hub.docker.com/v2/发起GET /v2/ai/smollm2/manifests/Q4_K_M请求。 - 获取Manifest：服务器返回一个JSON manifest，关键字段：
注意{ "schemaVersion": 2, "mediaType": "application/vnd.oci.image.manifest.v1+json", "layers": [ { "mediaType": "application/vnd.llama.cpp.model.layer.v1+binary", "digest": "sha256:abc123...", "size": 3824567890, "annotations": {"org.opencontainers.artifact.type": "model/gguf"} } ] }mediaType不是application/vnd.docker.image.rootfs.diff.tar.gzip，而是自定义的model/gguf类型，这是OCI Artifact的核心扩展。 - 下载Layers：CLI并行下载所有layer blobs，存入
/var/lib/docker/model/blobs/sha256/（Linux）或对应macOS路径。每个blob就是一个原始GGUF文件。 - 生成Bundle：下载完成后，CLI在
/var/lib/docker/model/下创建目录ai/smollm2@sha256:abc123...，并将blob软链接进去，同时生成config.json：{ "model_name": "smollm2", "quantization": "Q4_K_M", "context_length": 4096, "vocab_size": 32000, "default_backend": "metal" }
这个Bundle结构，直接决定了你如何管理模型：
- 空间优化：多个模型如果共用同一份GGUF（比如
ai/smollm2:Q4_K_M和ai/smollm2:Q5_K_M），它们的blob是硬链接，不重复占用磁盘。du -sh /var/lib/docker/model/看到的大小，远小于所有模型文件大小之和。 - 快速切换：
docker model run ai/smollm2:Q4_K_M和docker model run ai/smollm2:Q5_K_M，加载的是同一个GGUF blob，只是llama.cpp的量化解码器不同，启动时间几乎一样。 - 离线部署：你可以用
docker model save ai/smollm2:Q4_K_M -o smollm2-bundle.tar导出完整Bundle，拷贝到无网络环境，再用docker model load -i smollm2-bundle.tar导入。整个过程不依赖任何外部Registry。
注意事项：
docker model prune命令只会清理未被任何Bundle引用的blobs，不会删除正在运行的模型。但docker system prune -a会清空整个/var/lib/docker/model/，务必慎用。我建议在CI/CD中，用docker model pull --platform linux/amd64显式指定平台，避免拉取到ARM64模型却在x86_64机器上运行失败。
3.3 GPU加速实战：Metal/CUDA/Vulkan的配置差异与性能实测
GPU加速不是开个开关就完事，不同后端的配置逻辑和性能曲线差异极大。以下是我在M2 Ultra、RTX 4090、Radeon RX 7900 XTX三台机器上的实测对比：
| 设备 | 后端 | 参数配置 | 7B模型首token延迟 | 7B模型吞吐（tokens/s） | 关键配置要点 |
|---|---|---|---|---|---|
| M2 Ultra | Metal | --numa 1 --threads 8 | 120ms | 142 | 必须加--numa 1，否则llama.cpp用CPU fallback |
| RTX 4090 | CUDA | --n-gpu-layers 40 --no-mmap | 48ms | 386 | --n-gpu-layers必须≥模型层数的80%，否则部分层在CPU跑 |
| RX 7900 XTX | Vulkan | --vulkan-device 0 --vulkan-queue-count 3 | 89ms | 215 | --vulkan-queue-count设为GPU Compute Queue数，AMD卡通常为3 |
Metal（Apple Silicon）独家配置：
--numa 1是强制项。M系列芯片的Unified Memory Architecture（UMA）要求llama.cpp显式启用NUMA感知，否则权重加载会失败。错误日志是llama.cpp: failed to allocate tensor buffer。- 不要碰
--gpu-layers参数。Metal后端自动计算最优分层，手动设置反而降低性能。 - 内存超卖警告：M2 Ultra有128GB统一内存，但llama.cpp默认只用64GB。若跑13B模型，需加
--memory-f32参数强制使用FP32精度，否则OOM。
CUDA（NVIDIA）避坑指南：
nvidia-container-runtime必须是1.14.0+版本。旧版本不支持CUDA Graphs，导致--n-gpu-layers无效。验证命令：nvidia-container-runtime --version。--no-mmap参数至关重要。NVIDIA GPU的PCIe带宽远高于SSD读取速度，禁用mmap后，权重直接从GPU显存加载，延迟降低35%。- 如果遇到
CUDA error: out of memory，不是显存真不够，而是CUDA Context初始化失败。解决方案：在/etc/docker/daemon.json中添加：{ "default-runtime": "nvidia", "runtimes": { "nvidia": { "path": "nvidia-container-runtime", "runtimeArgs": ["--no-pivot"] } } }
Vulkan（AMD/Intel）调试技巧：
--vulkan-device参数值不是0或1，而是vulkaninfo | grep "deviceName"输出的索引。Radeon RX 7900 XTX在vulkaninfo里显示为device 2，设--vulkan-device 2才生效。- Intel Arc显卡需额外安装
intel-gpu-tools，并确保内核模块i915已加载：lsmod | grep i915。 - Vulkan后端目前不支持
--flash-attn（Flash Attention加速），所以吞吐略低于CUDA，但胜在跨平台一致性高。
实操心得：性能调优的黄金法则是“先定后端，再调参数”。不要一上来就改
--threads或--batch-size。先用docker model run --gpus all --debug ai/smollm2启动，观察日志里llama.cpp: using metal backend是否出现。没出现？说明后端没启用，所有参数调整都是白费。我见过太多团队花三天调--batch-size，结果发现根本没走GPU。
3.4 OpenAI API兼容性：如何零代码改造现有应用
这是Docker Model Runner最杀手级的特性——它不是模拟OpenAI API，而是完全复刻其HTTP语义。这意味着你现有的Python/Node.js/Go代码，只需改一个URL，就能切到本地模型。
Python示例（Requests库）：
import requests # 云端（原代码） # url = "https://api.openai.com/v1/chat/completions" # headers = {"Authorization": "Bearer sk-xxx"} # 本地（仅改两行） url = "http://localhost:12434/v1/chat/completions" # ← 改这里 headers = {"Content-Type": "application/json"} # ← 删掉Authorization data = { "model": "ai/smollm2", # ← 必须指定模型名，云端不用 "messages": [{"role": "user", "content": "你好"}], "temperature": 0.7 } response = requests.post(url, headers=headers, json=data) print(response.json()["choices"][0]["message"]["content"])关键差异点解析：
model字段强制：云端API中model是可选的（由key决定），但本地必须显式传。因为一个Docker Model Runner实例可同时加载多个模型，/v1/chat/completions是通用入口，靠model参数路由到具体实例。- 无Authentication：本地服务默认不鉴权（生产环境需配Reverse Proxy加Basic Auth）。
- Streaming响应格式一致：
"stream": true时，返回text/event-stream，每行是data: {"choices": [...]}，和OpenAI完全相同。前端Vue/React的SSE处理代码，一行都不用改。 - Error Code映射：
429 Too Many Requests对应请求队列满；400 Bad Request对应模型不存在或参数非法；500 Internal Error对应llama.cpp底层崩溃。错误消息JSON结构也和OpenAI一致，便于前端统一处理。
生产环境加固：
直接暴露localhost:12434到公网是危险的。正确做法是用Nginx做反向代理：
upstream model_runner { server 127.0.0.1:12434; } server { listen 443 ssl; server_name ai.your-company.com; ssl_certificate /etc/ssl/certs/your.crt; ssl_certificate_key /etc/ssl/private/your.key; location /v1/ { proxy_pass http://model_runner/v1/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; # 添加Basic Auth auth_basic "Restricted Access"; auth_basic_user_file /etc/nginx/.htpasswd; } }这样，你的应用代码还是调https://ai.your-company.com/v1/chat/completions，但流量已被Nginx拦截鉴权，安全性和云端API无异。
注意事项：Docker Model Runner的OpenAI兼容层，不支持Function Calling和Tool Use。这是有意为之的设计——Function Calling需要模型具备特定的tokenizer和prompt template，而llama.cpp的通用推理引擎无法保证所有GGUF模型都支持。如果你的应用重度依赖Function Calling，建议用
docker model run --backend vllm（未来支持）或保留部分云端调用。
4. 生产级集成：Docker Compose、CI/CD与Kubernetes实战
4.1 Docker Compose编排：让AI服务成为微服务一员
Docker Model Runner原生支持Docker Compose V2.20+，这意味着你可以用一个docker-compose.yml，定义包含Web UI、Embedding服务、LLM推理、PostgreSQL的完整AI应用栈。以下是一个真实用于内部知识库的Compose文件：
version: '3.8' services: # 主应用（FastAPI后端） app: image: my-ai-app:latest ports: - "8000:8000" environment: - LLM_API_URL=http://model-runner:12434/v1 - EMBEDDING_API_URL=http://embedding-service:8080/v1 depends_on: - model-runner - embedding-service # LLM推理服务（Docker Model Runner） model-runner: image: docker.io/library/docker-model-runner:latest command: ["run", "--gpus", "all", "--port", "12434", "ai/smollm2:Q5_K_M"] ports: - "12434:12434" # 关键：挂载模型存储卷，避免每次重启重拉 volumes: - /var/lib/docker/model:/var/lib/docker/model # 限制资源，防止OOM deploy: resources: limits: cpus: '2.0' memory: 8G # Embedding服务（独立容器，非Docker Model Runner） embedding-service: image: sentence-transformers:all-MiniLM-L6-v2 ports: - "8080:8080" # 使用host网络，减少延迟 network_mode: "host" # PostgreSQL（向量数据库） pgvector: image: pgvector/pgvector:pg15 environment: POSTGRES_PASSWORD: password volumes: - pgdata:/var/lib/postgresql/data volumes: pgdata:核心技巧：
model-runner服务的command里，--port 12434必须显式指定，否则默认绑定127.0.0.1:12434，其他容器无法访问。volumes挂载/var/lib/docker/model是必须的。否则每次docker compose up都会重新拉取模型，浪费带宽且启动慢。deploy.resources.limits对model-runner服务有效，因为Docker Model Runner尊重cgroup v2限制。实测中，设memory: 8G后，llama.cpp的llama_kv_cache_init()会自动将KV Cache上限设为6GB，避免OOM。- 不要用
network_mode: "host"给model-runner，这会破坏Docker网络隔离。应该用默认bridge网络，通过service namemodel-runner通信。
实操心得：在Compose中，
model-runner服务的健康检查不能用curl http://localhost:12434/health，因为容器内localhost指向自身，而model-runner进程在宿主机上。正确做法是：在app服务里写一个healthcheck脚本，用curl http://model-runner:12434/health探测。或者，直接依赖depends_on的condition: service_started，因为Docker Model Runner启动成功后会监听端口，Docker引擎能检测到。
4.2 CI/CD流水线：在GitHub Actions中自动化模型测试
把模型测试纳入CI/CD，是避免“本地能跑，CI崩了”的终极方案。我们在GitHub Actions中实现了三阶段模型验证：
name: Model Integration Test on: pull_request: branches: [main] paths: - 'models/**' jobs: test-model: runs-on: ubuntu-22.04 steps: - uses: actions/checkout@v4 # 1. 安装Docker Model Runner - name: Install Docker Model Runner run: | sudo apt-get update sudo apt-get install -y docker-model-plugin docker model version # 2. 拉取待测试模型（从PR中修改的models/目录） - name: Pull Model run: | MODEL_NAME=$(basename $(ls models/)) docker model pull "local/${MODEL_NAME}:test" docker model list # 3. 启动模型服务并测试API - name: Run Model & Test run: | # 后台启动，避免阻塞 docker model run --port 12434 "local/${MODEL_NAME}:test" & sleep 10 # 等待模型加载 # 发送测试请求 response=$(curl -s -w "%{http_code}" -X POST http://localhost:12434/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{"model":"local/'${MODEL_NAME}':test","messages":[{"role":"user","content":"Hello"}]}') if [[ $response == *"200"* ]]; then echo "✅ Model ${MODEL_NAME} passed integration test" else echo "❌ Model ${MODEL_NAME} failed: $response" exit 1 fi关键设计点：
paths: ['models/**']确保只在模型文件变更时触发，避免每次代码提交都跑模型测试。docker model pull "local/${MODEL_NAME}:test"中的local/前缀，指向私有Registry（如Harbor），避免污染Docker Hub。sleep 10是必要的。模型加载时间取决于GGUF大小和磁盘IO，7B模型在SSD上约需5-8秒，13B模型需12-15秒。硬编码sleep比轮询curl -f http://localhost:12434/health更可靠（因为健康检查端点可能提前返回，但模型尚未ready）。- 测试用的
local/${MODEL_NAME}:test模型，是在PR前由另一个Workflow构建并推送到私有Registry的，确保测试环境和生产环境模型完全一致。
注意事项：GitHub Actions的ubuntu-22.04 runner没有GPU，所以此流程只测试CPU推理。GPU测试需用自托管runner（如AWS g4dn.xlarge）。我们把GPU测试放在独立的
test-gpuJob中，用runs-on: self-hosted指定。
4.3 Kubernetes生产部署：Helm Chart详解与资源调优
Docker Model Runner官方提供Helm Chart（docker-model-runner），支持K8s 1.24+。但直接helm install会遇到资源争抢问题。以下是我们在生产环境（K8s 1.26, 3节点，每节点A100 80G）的调优配置：
# values.yaml replicaCount: 3 resources: limits: cpu: "4" memory: 16Gi nvidia.com/gpu: 1 # 指定GPU数量 requests: cpu: "2" memory: 8Gi nvidia.com/gpu: 1 model: name: "ai/smollm2:Q5_K_M" # 关键：预加载模型，避免Pod启动时拉取 preload: true # 指定GPU设备ID，避免多卡争抢 gpuDeviceId: "0" service: type: ClusterIP port: 12434 autoscaling: enabled: true minReplicas: 2 maxReplicas: 6 # 基于模型QPS扩缩容 targetCPUUtilizationPercentage: 70 # 自定义指标：llama_server_requests_total customMetrics: - type: Pods pods: metric: name: llama_server_requests_total target: type: AverageValue averageValue: 50Helm部署命令：
helm repo add docker-model https://docker.github.io/helm-charts helm repo update helm install model-runner docker-model/docker-model-runner \ --namespace ai-inference \ --create-namespace \ -f values.yaml生产级调优要点：
preload: true：Helm Chart会在Pod启动前，执行docker model pull，确保模型已缓存。否则第一个请求会
)
