2026 Kimi K3 vLLM 部署报错：先查环境再查缓存

官方 Kimi K3 vLLM Recipe 当前要求专用 CUDA 13 镜像与宿主机 r580+ NVIDIA 驱动；prefix caching 也不是默认开启。因此，遇到启动失败、OOM 或 NCCL 错误时，最快路径不是立即缩短上下文，而是先核对镜像、驱动和依赖，再处理显存与多节点通信，最后验证缓存行为。相关前置条件以vLLM 官方 Kimi K3 Recipe为准。

这篇文章适合已经进入自托管阶段的推理平台工程师、AI Agent 基础设施团队和多节点 GPU 集群运维人员。你可以按首条异常进入对应模块，不必重复完整安装流程。

最后更新于 2026 年 8 月 11 日；数据核实自 vLLM 官方 Recipe、vLLM 发布说明与 NVIDIA CUDA 13 官方文档。

首条异常决定排查方向

启动 Kimi K3 前，先保存完整启动命令、容器标签、vLLM 版本、nvidia-smi 输出、GPU 拓扑和第一条异常。不要只截取最后一行，因为最后的 worker exited、engine failed 或 NCCL error，经常只是前面环境故障的结果。

官方发布文章确认，Kimi K3 的依赖组合较复杂，推荐通过专用 Docker 镜像运行；当前公开快速启动路径使用 vLLM 0.27.0+。(vLLM Kimi K3 发布说明)

nvidia-smi
docker image inspect vllm/vllm-openai:kimi-k3
docker run --rm --gpus all vllm/vllm-openai:kimi-k3 nvidia-smi
python -m vllm --version

CUDA 13 与 r580 的环境边界

为什么同一台机器能运行旧 vLLM，却无法直接启动 Kimi K3？

Kimi K3 官方专用镜像目前按 CUDA 13 构建，recipe 要求宿主机使用 r580+ NVIDIA 驱动。NVIDIA 的 CUDA 13.0 发布说明列出的 Linux CUDA 13.0 GA 驱动版本为 580.65.06 或更高。(NVIDIA CUDA 13.0 发布说明)

这里必须拆开看：

• 宿主机驱动：负责与 GPU 内核交互，是容器能否初始化 CUDA 的第一道边界。
• 容器 CUDA runtime：由镜像提供，决定 vLLM 使用的用户态 CUDA 库。
• 本地 CUDA Toolkit：主要用于本地编译，安装它不会自动升级宿主机驱动。

如果 nvidia-smi 显示宿主机仍是 r575 或更低版本，优先选择以下合规路径：

1. 升级宿主机到官方要求的 r580+ 驱动，重启后再次执行容器内 nvidia-smi。
2. 按 Kimi K3 对应分支自行构建兼容环境，并记录 PyTorch、CUDA、vLLM 与编译参数。

不要在旧驱动宿主机上，把容器内 CUDA 12.9、CUDA 13 用户库和旧 nightly wheel 混装，随后把“能导入 Python 模块”当作环境已兼容。NVIDIA 的驱动兼容性文档说明了 Toolkit 与最低驱动之间的约束；新驱动对旧 Toolkit 的兼容，也不能反过来证明旧驱动支持新 CUDA。

专用镜像与依赖加载

日志出现架构未识别或算子缺失时，先不要改模型参数。

先确认是否使用了官方 Kimi K3 镜像，以及镜像标签是否真实存在：

docker images --digests | grep vllm
docker image inspect vllm/vllm-openai:kimi-k3
python -m vllm --version

以下症状通常属于依赖层，而不是显存层：

• Model architecture ... is not supported：当前 vLLM 或镜像可能没有包含 K3 架构支持。
• No module named ...：容器内依赖不完整，或宿主机 Python 包被错误带入。
• undefined symbol、CUDA 算子缺失：重点检查 PyTorch、CUDA runtime 和预编译扩展是否来自同一组合。
• manifest unknown：镜像标签不存在，不能自行把其他 CUDA 标签改名当作 K3 镜像。
• 使用通用 vLLM 镜像、旧 nightly wheel 或 CUDA 12.9 索引：只能当作待验证实验，不能视为官方等价方案。

修复后要重新运行完整启动命令。只执行 import vllm 并不能证明模型架构、权重加载格式、FlashInfer 等专用组件都已经正常。

prefix caching 的启用与命中

参数已经写进启动命令，缓存仍然没有复用，通常要从 3 个条件分开确认。

第一，检查启动参数是否实际传递给引擎：

--enable-prefix-caching

Kimi K3 当前支持 prefix caching，但官方快速启动示例需要显式加入该参数，默认状态不能按“自动开启”处理。启动后还要查看 engine 配置和初始化日志，确认部署系统没有覆盖或过滤参数。

第二，确认请求前缀真的一致。系统提示词、工具定义、消息顺序、空格、序列化方式，甚至图片输入的处理方式发生变化，都可能导致两个请求无法复用同一段前缀。

建议固定一份测试请求，并保存：

• 完整请求 JSON；
• tokenizer 后的 token 数；
• 请求实际到达的 worker；
• prefix hit / miss 指标；
• 首次请求与后续请求的 prefill 日志。

第三，检查 KDA 状态的保留策略。vLLM 发布说明提到，KDA recurrent state 不会在每个 token 位置都保存，而是结合 prompt-end、间隔 checkpoint 或选择性 retention 控制缓存成本。文档中的 32K tokens 是策略示例，不是所有工作负载都必须采用的固定值。(vLLM K3 缓存说明)

因此，单看首轮延迟没有下降，不能直接判定缓存失效。你需要同时比对启动配置、请求 token 前缀和缓存指标。

启动 OOM 与推理 OOM

同样是 CUDA out of memory，发生阶段不同，处理顺序也不同。

启动阶段 OOM，先核对：

• GPU 数量是否满足官方前置条件；
• GPU 是否处于正确节点和拓扑；
• tensor parallel、expert parallel、pipeline parallel 是否与设备布局匹配；
• 权重加载方式是否正确；
• 启动前是否有其他进程占用显存；
• 容器是否看到了全部 GPU。

官方 recipe 当前列出 NVIDIA 路径至少使用 8 张 GB300，并说明生产流量需要多节点；vLLM 发布文章还给出 8 张 NVIDIA B300 或 8 张 AMD MI355X 的启动示例。这里的硬件要求必须作为容量判断基线，不能用普通小模型的单卡经验推算 Kimi K3。

推理阶段 OOM，再检查：

• max-model-len；
• 并发请求数；
• batch token 上限；
• KV cache 占用；
• prefix caching 保留策略；
• 图片输入、工具调用或其他额外推理配置。

建议按以下顺序复测：

1. 在空闲节点上启动服务，不先修改模型参数。
2. 发送短文本基础请求。
3. 发送完全一致的长前缀请求，检查缓存。
4. 逐级增加并发，记录 OOM 和超时位置。
5. 最后再调整上下文长度、batch 或缓存策略。

如果第 1 步就失败，优先怀疑硬件、拓扑或加载配置；如果短请求稳定、并发提高后才失败，才更像是运行期显存参数问题。

NCCL、RDMA 与节点拓扑

多节点排障不能把 NVLink 参数和 RDMA 参数混在一起。官方 recipe 建议：RDMA 使用 deepep_v2，NVLink 使用 flashinfer_nvlink_one_sided；跨节点 NVLink 的 DEP 路径还涉及 deep_gemm_mega_moe，并不等同于跨节点 RDMA 配置。

先确认设备与网络：

nvidia-smi topo -m
ibdev2netdev
ip link
lsmod | grep -E 'mlx5|nvidia_peermem'

然后逐项检查：

• all-to-all backend 是否符合实际互连方式；
• 所有节点的 RDMA 网卡接口是否一致；
• UCX_TLS 是否包含官方要求的 rc,cuda_copy；
• 驱动、NCCL 和 RDMA 用户态库是否来自兼容环境；
• 每个节点是否加载了所需内核模块。

官方 recipe 还记录了 NCCL unhandled system error 与 mlx5dv_reg_dmabuf_mr、errno 524 同时出现的情况，可能与 mlx5 dmabuf 注册能力有关。可以按官方说明尝试：

NCCL_DMABUF_ENABLE=0

但这不是孤立的万能开关。回退配置要求节点具备对应的 nvidia_peermem 条件，必须重新检查模块、网络接口和 NCCL 初始化日志。

从恢复启动到稳定验收

修复后不要只记录“容器没有退出”。按下面顺序形成可复跑的验收闭环：

1. 服务启动：所有 rank 注册完成，没有 CUDA、算子或 NCCL 初始化错误。
2. 基础请求：短文本能够完整返回，流式输出和工具调用格式正常。
3. 长前缀复用：固定系统提示词、工具定义和输入前缀，检查缓存指标。
4. 并发请求：逐步增加并发，记录显存峰值、超时和 worker 重启。
5. 多节点稳定性：持续运行固定测试流量，观察 NCCL、RDMA、网卡错误。
6. 环境留档：保存镜像摘要、vLLM 版本、驱动版本、GPU 拓扑、启动参数和关键日志。

你可以把排障记录整理到MacHTML 帮助页面，并将驱动、镜像和拓扑作为同一份验收单管理。

如果现有方案依赖旧驱动节点、通用 vLLM 镜像或临时拼装的 CUDA 环境，主要缺点是启动原因难以复现、节点版本不一致、显存与通信问题互相掩盖，升级后还要重复验证。对于临时算力、版本验证或项目周期内的多节点推理测试，继续在不兼容集群上试错，往往比使用已经完成环境验收的算力更慢。

若你的集群正卡在驱动升级、硬件拓扑或交付周期，可以进一步查看MacHTML 的方案页面，按项目周期评估租赁已验收的 AI Agent 推理环境。长期稳定重负载、必须持有物理设备或依赖特殊 PCIe／网络接口时，自建集群更合适；但需要快速复跑 Kimi K3、验证 prefix caching 或完成多节点故障定位时，按周期租用经过验收的环境，通常比继续维护混装节点更容易控制变量。