Kimi K3 本地部署完全指南：1560GB 权重、8 卡起步与真实硬件门槛

数据来源：Hugging Face 仓库实测数据、vLLM ** recipe YAML、SGLang cookbook、** config.json

Kimi K3 本地部署的第一个现实是权重体积：Hugging Face 仓库的 96 个 safetensors 分片实测合计 1,560,936,091,448 字节，即约 1560.9 GB（1453.7 GiB），vLLM ** recipe 标注最小显存需求为 1680 GB。这意味着单卡、单机 8×80GB 配置均无法承载完整权重——vLLM **前置条件明确写的是"至少 8× GB300，生产流量需多机"。**已验证的硬件为 H200、B300、GB300、MI355X 四种，并行策略上 TP 与 TEP 最低 8 卡、DEP 最低 16 卡。技术上值得注意的是这个 MXFP4 检查点并非全量 4bit：config.json 的 quantization_config 设有 ignore 列表，注意力层、共享专家、mlp 投影、lm_head 与视觉塔均保持高精度，group_size 为 32。对绝大多数团队而言，务实路径是** API 或社区 GGUF 量化版本（已有 unsloth、GrEarl 等多个版本，含 IQ1_S 极限量化），而非自建集群。本文给出四条部署路线的完整命令、参数与适用判断。

一、先看清硬件门槛，避免无效投入

1. 权重体积的实测数据

这是所有部署决策的起点。 我直接从 Hugging Face API 统计了全部 safetensors 分片：

项目	实测值
safetensors 分片数	96 个
权重总体积	1,560,936,091,448 字节
换算	约 1560.9 GB / 1453.7 GiB
vLLM **标注最小显存	1680 GB（含 1.2 倍余量）

注意 1680 GB 这个数字的来源——vLLM recipe YAML 的注释写明这是预发布估算：2.8T params × 0.5 byte/param × 1.2 headroom，并注明"权重发布后应替换为真实 safetensors 体积"。实测 1560.9 GB 与该估算基本吻合。

2. **验证过的硬件

据 vLLM recipe YAML 的 hardware 字段，已标记为 verified 的有四种：

硬件	状态	备注
GB300	verified	**前置条件推荐，`default_hardware` 为 b300
B300	verified	Blackwell 架构，有专属优化参数
H200	verified	Hopper 架构，需特殊 MoE backend
MI355X	verified	AMD ROCm，CDNA4 gfx950

**前置条件原文："At least 8x GB300. Multi-node for real production traffic."（至少 8× GB300，真实生产流量需多机）

ROCm 路线原文："Use vllm/vllm-openai_rocm:kimi-k3 docker and at least 8x MI355X/MI350X hardware."

3. 并行策略的最低卡数

据 YAML 的 strategy_min_gpus 字段：

策略	最低 GPU 数	说明
`single_node_tp`	8	默认策略
`multi_node_tp`	8	跨机张量并行
`multi_node_tep`	8	张量+专家并行
`multi_node_dep`	16	数据+专家并行，卡数要求翻倍

KV Cache 分布式存储全部不支持——YAML 的 kv_cache_strategy_hardware 字段显示 Mooncake 的分布式与集中式方案在 H100、H200、B200、GB200、B300、GB300、MI300X、MI325X、MI355X 上均标记为 unsupported。

二、MXFP4 不是全量 4bit：一个容易误判的细节

很多人看到"MXFP4 量化"就按 0.5 byte/param 估算显存，但实际检查点保留了大量高精度模块。

据** config.json 的 quantization_config：

{
  "format": "mxfp4-pack-quantized",
  "quant_method": "compressed-tensors",
  "quantization_status": "compressed",
  "config_groups": {
    "group_0": {
      "targets": ["Linear"],
      "weights": {
        "num_bits": 4,
        "group_size": 32,
        "strategy": "group",
        "symmetric": true,
        "type": "float",
        "observer": "minmax"
      }
    }
  },
  "ignore": [
    "re:.*self_attn.*",
    "re:.*shared_experts.*",
    "re:.*mlp\\.(gate|up|gate_up|down)_proj.*",
    "re:.*lm_head.*",
    "re:.*vision_tower.*",
    "re:.*mm_projector.*"
  ]
}

保持高精度的模块（不参与 4bit 量化）：

self_attn — 全部注意力层
shared_experts — 2 个共享专家
mlp.gate/up/gate_up/down_proj — 稠密 MLP 投影
lm_head — 输出头
vision_tower / mm_projector — 视觉编码器与投影层

这解释了为什么实测 1560.9 GB 高于纯 4bit 理论值（2.8T × 0.5 byte = 1400 GB）。

三、架构参数：部署前需要知道的关键配置

据** config.json 实测提取：

参数	值
`num_hidden_layers`	93
`hidden_size`	7168
`intermediate_size`	33792
`moe_intermediate_size`	3072
`vocab_size`	163840
`max_position_embeddings`	1048576
`num_attention_heads`	96
`kv_lora_rank`	512
`q_lora_rank`	1536
`first_k_dense_replace`	1
`attn_res_block_size`	12
`hidden_act`	situ（SiTU-GLU）
`dtype`	bfloat16

KDA 与全注意力层的精确分布

config.json 的 linear_attn_config 给出了确切的层号分布，这比"69 KDA + 24 Gated MLA"的概括更有用：

full_attn_layers: [4, 8, 12, 16, 20, 24, 28, 32, 36, 40, 44, 48,
                   52, 56, 60, 64, 68, 72, 76, 80, 84, 88, 92, 93]
kda_layers:       [1,2,3, 5,6,7, 9,10,11, 13,14,15, ...]  共 69 层

规律是每 4 层里有 3 层 KDA、1 层全注意力（第 4、8、12… 为全注意力），末尾第 92、93 层连续为全注意力。KDA 配置：num_heads: 96、head_dim: 128、short_conv_kernel_size: 4、use_full_rank_gate: true、gate_lower_bound: -5.0。

四、路线一：vLLM 部署（**推荐，文档最全）

1. 前置要求

项目	要求
vLLM 版本	≥ 0.27.0（`min_vllm_version`）
镜像（NVIDIA）	`vllm/vllm-openai:kimi-k3`
镜像（AMD）	`vllm/vllm-openai-rocm:kimi-k3`
nightly	必需（`nightly_required: true`）
难度标注	hard

2. 基础参数（所有硬件通用）

据 YAML 的 base_args：

--trust-remote-code \
--load-format fastsafetensors \
--moe-backend auto \
--gpu-memory-utilization 0.95

fastsafetensors 是**推荐的加载格式，YAML 注释说明它能显著加快权重加载（考虑到 1560 GB 的体积，这个优化很关键）。

3. Blackwell（B300 / GB300）优化参数

--max-model-len 1000000 \
--kv-cache-dtype fp8 \
--attention-config '{"mla_prefill_backend":"TRTLLM_RAGGED","use_prefill_query_quantization":true}' \
--max-num-batched-tokens 32768 \
--enable-prefix-caching

配套环境变量：

export VLLM_ENABLE_K3_LATENT_MOE_TAIL_FUSION=1
export VLLM_ALLREDUCE_USE_FLASHINFER=1
export VLLM_ENGINE_READY_TIMEOUT_S=3600
export VLLM_USE_V2_MODEL_RUNNER=1
export VLLM_USE_RUST_FRONTEND=1

VLLM_ENGINE_READY_TIMEOUT_S=3600 不是可选项——1560 GB 权重的加载时间远超默认超时。

4. Hopper（H200）专属参数

H200 需要不同的 MoE backend：

--no-enable-flashinfer-autotune \
--moe-backend marlin \
--disable-custom-all-reduce

export VLLM_ENABLE_K3_LATENT_MOE_TAIL_FUSION=1

5. AMD（MI355X / MI350X）参数

--load-format auto \
--gpu-memory-utilization 0.95 \
--mm-encoder-tp-mode data \
--max-num-seqs 128 \
--reasoning-parser kimi_k3 \
--max-num-batched-tokens 4096

export VLLM_ROCM_USE_AITER=1
export SAFETENSORS_FAST_GPU=1
export AITER_SITUV2_A8W4=1        # 0 = a16w4 MoE 路径，1 = a8w4
export AITER_BF16_FP8_MOE_BOUND=0
export VLLM_USE_BREAKABLE_CUDAGRAPH=0   # ROCm 上必须设为 0，构建会自动置 1

⚠️ VLLM_USE_BREAKABLE_CUDAGRAPH=0 在 ROCm 上是强制要求——YAML 注释原文标注 "REQUIRED on ROCm: the build auto-enables =1"。

6. 功能开关

工具调用：

--enable-auto-tool-choice --tool-call-parser kimi_k3

推理内容解析（把思考与最终答案分开）：

--reasoning-parser kimi_k3

投机解码（需额外显存，故须限制并发）：

--max-num-seqs 32 \
--speculative-config '{"model":"Inferact/Kimi-K3-DSpark","num_speculative_tokens":7,"method":"dspark","attention_backend":"FLASHINFER_MLA","draft_sample_method":"probabilistic","rejection_sample_method":"block"}'

纯文本模式（跳过视觉编码器，与 encoder_parallel 互斥）：

--language-model-only

7. 客户端调用（**示例）

import time
from openai import OpenAI

client = OpenAI(
    api_key="EMPTY",
    base_url="http://localhost:8000/v1",
    timeout=3600          # 注意超时设为 3600 秒
)

messages = [{
    "role": "user",
    "content": [
        {"type": "image_url", "image_url": {"url": "https://example.com/receipt.png"}},
        {"type": "text", "text": "Read all the text in the image."}
    ]
}]

start = time.time()
response = client.chat.completions.create(
    model="moonshotai/Kimi-K3",
    messages=messages,
    max_tokens=2048
)
print(f"Response costs: {time.time() - start:.2f}s")
print(f"Generated text: {response.choices[0].message.content}")

五、路线二：PD 分离集群（生产级配置）

Prefill / Decode 分离是**给出的生产方案，两侧用完全不同的并行策略。

Prefill 侧（TEP，TP=8）

--enforce-eager \
--max-num-batched-tokens 16384 \
--no-disable-hybrid-kv-cache-manager \
--no-enable-flashinfer-autotune

Decode 侧（DEP，TP=1）

--data-parallel-hybrid-lb \
--moe-backend deep_gemm_mega_moe \
--no-enable-prefix-caching \
--max-num-seqs 32 \
--max-num-batched-tokens 32 \
--no-disable-hybrid-kv-cache-manager \
--compilation-config '{"cudagraph_mode":"FULL_DECODE_ONLY"}' \
--all2all-backend flashinfer_nvlink_one_sided

集群环境变量

export NCCL_CUMEM_ENABLE=1
export NCCL_MNNVL_ENABLE=1
export NCCL_NVLS_ENABLE=0
export VLLM_SSM_CONV_STATE_LAYOUT=DS
# Blackwell 且启用 RDMA 时追加
export UCX_TLS="rc,cuda_copy"
export VLLM_ENABLE_K3_LATENT_MOE_TAIL_FUSION=1

通信后端选择

据** Notes：

场景	参数
RDMA 跨机	`--all2all-backend deepep_v2`
NVLink	`--all2all-backend flashinfer_nvlink_one_sided`
DEP 环境 MoE	`--moe-backend deep_gemm_mega_moe`
TP > 1 MoE	`--moe-backend flashinfer_trtllm`

⚠️ RDMA 必须显式设置 UCX_TLS="rc,cuda_copy"，否则 KV Cache 传输可能不走 RDMA 通路。

六、路线三：SGLang 部署

SGLang 支持的硬件列表更宽：b300、gb300、b200、gb200、h200、h100、mi350x、mi355x。

Docker 启动骨架：

docker run --gpus all --shm-size 32g --ipc=host \
  lmsysorg/sglang:dev \
  sglang serve ...

并行参数别名：--tp-size/--tp/--tensor-parallel-size、--ep-size/--ep、--dp、--enable-dp-attention、--attn-cp-size、--dcp-size、--pp-size。多机追加 --nnodes、--node-rank、--dist-init-addr。PD 分离端口固定：prefill 30000、decode 30100。

SGLang 的五个已知限制（** cookbook）

MTP 开启且未设 --max-running-requests 时，SGLang 会强制重置为 48
interleave 型 prefill-CP 与 DP-Attention 不能同时用——当前版本 assert dp_size == 1，冲突会在启动时直接失败
prefill-CP 尺寸是推导值：attn_cp_size = TP / DP-Attention
DSPARK 与长上下文方案冲突——后者用流水并行，而 DSPARK 要求 pp_size == 1
DFLASH 已禁用——**说明"No K3 DFLASH draft checkpoint published yet"

PD 模式下客户端流量应打路由器，而非直连角色服务器。

七、路线四：量化版本（消费级硬件的**现实选项）

社区已产出多个量化版本，这是没有 8 卡集群时的实际路径。

据 Hugging Face 搜索结果，当前可见的主要量化仓库：

仓库	类型	likes
`unsloth/Kimi-K3-GGUF`	GGUF	44
`GrEarl/Kimi-K3-GGUF`	GGUF	19
`GrEarl/Kimi-K3-GGUF-IQ1_S`	IQ1_S 极限量化	7
`RedHatAI/Kimi-K3-FP8-BLOCK`	FP8 分块	2
`pipenetwork/Kimi-K3-REAP80-MLX-mxfp4-q8`	MLX（Apple Silicon）	1
`Inferact/Kimi-K3-DSpark`	投机解码草稿模型	15

适用工具：llama.cpp、Ollama、LM Studio、Jan。

** Docker Model Runner 路径：

docker model run hf.co/moonshotai/Kimi-K3

⚠️ 量化档位与质量的权衡必须清楚：IQ1_S 这类 1bit 级量化能大幅降低显存，但与**评测成绩（reasoning_effort=max 下取得）的差距会显著扩大。不要用量化版本的表现去评判 K3 的真实能力。

八、部署路线决策表

你的条件	推荐路线	说明
8× GB300 / B300 及以上	vLLM `single_node_tp`	默认策略，文档最全
8× H200	vLLM + Hopper 覆写参数	需 `--moe-backend marlin`
8× MI355X / MI350X	vLLM ROCm 镜像	注意 `VLLM_USE_BREAKABLE_CUDAGRAPH=0`
16 卡以上，追求吞吐	vLLM `multi_node_dep` 或 PD 分离	DEP 最低 16 卡
需要 H100	SGLang	SGLang 硬件列表含 h100，vLLM 未标 verified
单机多卡但不足 8 卡	❌ 无可行方案	走 API 或量化版本
消费级硬件 / Mac	GGUF / MLX 量化版本	接受明显的质量损失
只想稳定用上 K3	** API	`platform.kimi.ai` 选 `kimi-k3`

九、六个部署避坑要点

1. 超时必须调大

1560 GB 权重加载远超默认超时，vLLM 需设 VLLM_ENGINE_READY_TIMEOUT_S=3600，客户端 timeout 也建议 3600 秒。

2. 用 fastsafetensors 加载

** base_args 指定 --load-format fastsafetensors，注释明确说明"much faster weight load"。但 AMD 路线覆写为 --load-format auto，不要照搬。

3. 工具调用需要校验重试

** Notes 原文："K3 occasionally emit a tool-call format its own parser doesn't expect. Suggest to run do schema validation and retry." 必须做 schema 校验加重试，不能假定输出格式稳定。

4. 投机解码要限并发

spec_decoding 配置里 YAML 注释写明"Speculative decoding needs additional VRAM, so cap concurrent sequences"，故须配 --max-num-seqs 32。

5. 分布式 KV 存储不可用

Mooncake 的分布式与集中式 KV 存储在所有列出硬件上均为 unsupported，不要按这个方向设计架构。

6. 这仍是预发布配方

vLLM recipe 的 description 标注 "Pre-release"，nightly_required: true。参数和行为可能变动，生产前需自行验证。

十、FAQ

Q：我有 8×H100，能跑 Kimi K3 吗？
A：vLLM ** recipe 未把 h100 标为 verified（仅 h200、b300、gb300、mi355x 为 verified），但 SGLang 的 supportedHardware 列表包含 h100。8×80GB = 640GB 显存远低于 1560GB 权重体积，单机 8×H100 无法承载完整权重，需多机或走量化版本。

Q：1560GB 和**说的 1680GB 哪个准？
A：1560.9 GB 是我从 HF API 统计 96 个分片得到的实际权重体积；1680 GB 是 vLLM recipe 的 vram_minimum_gb，包含约 1.2 倍余量（YAML 注释注明这是权重发布前的估算）。规划显存按 1680 GB 起算更安全，因为还需 KV Cache 和激活空间。

Q：为什么 MXFP4 量化后还有 1560GB？
A：因为它不是全量 4bit。quantization_config 的 ignore 列表把注意力层、共享专家、mlp 投影、lm_head、视觉塔全部排除在量化之外，这些模块保持高精度。纯 4bit 理论值为 1400 GB，实测高出 160 GB。

Q：Mac 能跑吗？
A：有 pipenetwork/Kimi-K3-REAP80-MLX-mxfp4-q8 这类 MLX 版本，但那是经过大幅裁剪和量化的版本。Apple Silicon 无法运行完整 2.8T 模型。

Q：GGUF 的 IQ1_S 版本值得用吗？
A：IQ1_S 是接近 1bit 的极限量化，能让模型在小得多的显存里跑起来，但质量损失显著。适合体验和实验，不适合据此评估 K3 能力或用于生产。

Q：PD 分离和普通 TP 该选哪个？
A：单节点 8 卡且流量不大用 single_node_tp（**默认）。真实生产流量**建议多机，PD 分离能让 prefill（TEP，TP=8）和 decode（DEP，TP=1）各自优化，但复杂度和最低卡数要求显著更高。

Q：为什么 decode 侧的 max-num-batched-tokens 只有 32？
A：这是 PD 分离架构的特性——decode 阶段每步只生成少量 token，配合 --compilation-config '{"cudagraph_mode":"FULL_DECODE_ONLY"}' 做全图捕获优化，小 batch 反而延迟更低。

十一、总结

Kimi K3 本地部署的核心结论是一句话：这不是个人或小团队能自建的模型。 1560.9 GB 权重、1680 GB 最小显存、8× GB300 起步、DEP 需 16 卡——这些数字划定了明确的门槛。

三条务实路径按成本递增：** API（platform.kimi.ai 选 kimi-k3，门槛最低）→ 社区量化版本（GGUF / MLX，接受质量损失）→ 自建集群（8 卡起步，需 vLLM ≥ 0.27.0 nightly）。

若确定要自建，六个技术要点务必记住：VLLM_ENGINE_READY_TIMEOUT_S=3600、--load-format fastsafetensors（AMD 例外）、H200 需 --moe-backend marlin、ROCm 需 VLLM_USE_BREAKABLE_CUDAGRAPH=0、工具调用需 schema 校验重试、分布式 KV 存储不可用。

延伸资源

Kimi K3 Hugging Face 仓库：https://huggingface.co/moonshotai/Kimi-K3
vLLM **部署配方：https://recipes.vllm.ai/moonshotai/Kimi-K3
vLLM recipe 源 YAML（含全部参数）：https://github.com/vllm-project/recipes/blob/main/models/moonshotai/Kimi-K3.yaml
SGLang 部署 cookbook：https://docs.sglang.io/cookbook/autoregressive/Moonshotai/Kimi-K3
Kimi K3 GitHub 仓库：https://github.com/MoonshotAI/Kimi-K3
KimiK3企业版：https://www.qiniu.com/ai/plan

posted @ 2026-08-07 19:02 vibecoding患者阅读(35) 评论(0) 收藏举报

刷新页面返回顶部