Kimi-K3 部署手册（运维版）

面向运维的一键部署手册：按顺序复制粘贴命令即可完成 Kimi-K3 在 4 节点 RTX 6000D 集群上的部署。不需要理解 SGLang 引擎参数。 部署配置统一在 deploy/profiles/pro6000/kimi3_pro6000_sglang_tp32ep32.env，压测统一走 python -m sskj.bench（见 ops/README.md）。

0. 概述

项	值
模型	Kimi-K3（Moonshot AI，2.8T 参数 MXFP4 量化，~1.5TB）
节点	6000D-5~~8 = 174.1.60.5~~8（每节点 8× RTX 6000D 85GB，共 32 卡）
镜像	`lmsysorg/sglang:kimi-k3`（专用镜像，普通 sglang 镜像不识别该模型架构）
并行	TP=32 × EP=32（跨 4 节点）
服务地址	`http://174.1.60.5:30000`（OpenAI 兼容）
模型 ID	`kimi-k3`
部署方式	`python -m sskj.deploy start --profile pro6000/kimi3_pro6000_sglang_tp32ep32`

1. 前置检查（每步都过再继续）

# 1.1 4 节点 8 卡全部空闲（应全部显示 0 MiB / 0%）
for i in 5 6 7 8; do echo "== 174.1.60.$i"; ssh 174.1.60.$i 'nvidia-smi --query-gpu=index,memory.used --format=csv,noheader'; done
# 注意：如显示被占用，联系模型团队确认（其他用户的作业需先让出）

# 1.2 磁盘空间（模型 1.5TB + 运行余量，/data 需 ≥ 2TB 可用）
ssh 174.1.60.5 'df -h /data'

# 1.3 RoCE 网卡就绪（应输出 4 个 ACTIVE 且 link_layer=Ethernet）
ssh 174.1.60.5 'cat /sys/class/infiniband/mlx5_*/ports/1/link_layer; cat /sys/class/infiniband/mlx5_*/ports/1/state'

# 1.4 节点互信（174.1.60.5 免密登录其余节点；若失败执行步骤 1.5）
ssh 174.1.60.5 'for i in 6 7 8; do ssh -o StrictHostKeyChecking=no 174.1.60.$i hostname; done'

# 1.5 若 1.4 失败，在 174.1.60.5 上执行（把 .5 的 root 公钥发到各节点）
ssh 174.1.60.5 'for i in 6 7 8; do ssh-copy-id -o StrictHostKeyChecking=no root@174.1.60.$i; done'

2. 模型下载（仅首次，~1.5TB，需数小时）

模型权重放 /data/hf_models/Kimi-K3（4 节点同一路径，本集群已就绪则跳过本节）。

# 在 174.1.60.5 上执行（国内走 ModelScope 最快；modelscope CLI 需先 pip install modelscope）
pip3 install -q modelscope
mkdir -p /data/hf_models
nohup modelscope download --model moonshotai/Kimi-K3 \
  --local_dir /data/hf_models/Kimi-K3 > /data/hf_models/download_k3.log 2>&1 &
# 查看进度
tail -f /data/hf_models/download_k3.log

下载完成后校验（96 个分片，共约 1.5TB）：

ssh 174.1.60.5 'ls /data/hf_models/Kimi-K3/*.safetensors | wc -l; du -sh /data/hf_models/Kimi-K3'
# 期望：96（safetensors 数量）、1.5T（总大小）

分发到其余 3 台（.5 上执行；源盘 NVMe 读是瓶颈，聚合约 3.5GB/s）：

ssh 174.1.60.5 'for i in 6 7 8; do rsync -aH --partial /data/hf_models/Kimi-K3/ 174.1.60.$i:/data/hf_models/Kimi-K3/ & done; wait'

每节点需约 1.5T 空闲磁盘（df -h /data 确认）。

3. 镜像准备（已拉取则跳过）

# 4 节点并行拉取（约 9.6GB；如 Docker Hub 直连失败，各机 daemon.json 需配镜像加速：
#   "registry-mirrors": ["https://docker.m.daocloud.io", "https://docker.xuanyuan.me"]）
for i in 5 6 7 8; do ssh 174.1.60.$i 'docker pull lmsysorg/sglang:kimi-k3' & done; wait

# 验证镜像存在
ssh 174.1.60.5 'docker images lmsysorg/sglang:kimi-k3 --format "{{.Repository}}:{{.Tag}} {{.Size}}"'

4. 补丁与依赖分发

Kimi-K3 镜像在消费级 Blackwell（sm_120，RTX 6000D）上有一个内核不兼容点，需要打补丁（补丁源文件在本仓库 platforms/patches/pro6000/kimi_k3/patch_k3_sm120.py，修复 attn_res 融合内核误用数据中心 Blackwell 专属的 tcgen05 指令问题）。

# 在 174.1.60.5 上，把补丁分发到 4 节点 /tmp（部署时容器自动挂载并执行）
ssh 174.1.60.5 '
  for i in 5 6 7 8; do
    scp /data/yy/sskj/platforms/patches/pro6000/kimi_k3/patch_k3_sm120.py 174.1.60.$i:/tmp/patch_k3_sm120.py
  done
  for i in 5 6 7 8; do ssh 174.1.60.$i "sha256sum /tmp/patch_k3_sm120.py"; done
'
# 4 台输出的 sha256 必须一致（内容校验）

5. 一键部署

cd /data/yy/sskj

# 5.1 先预览要执行的命令（不实际启动）
PYTHONPATH=src python3 -m sskj.deploy start \
  --profile pro6000/kimi3_pro6000_sglang_tp32ep32 --dry-run

# 5.2 正式启动（4 节点同时拉起，耗时 8~12 分钟：模型加载 + CUDA graph 捕获）
PYTHONPATH=src python3 -m sskj.deploy start \
  --profile pro6000/kimi3_pro6000_sglang_tp32ep32

# 5.3 查看状态
PYTHONPATH=src python3 -m sskj.deploy status \
  --profile pro6000/kimi3_pro6000_sglang_tp32ep32

就绪判定（满足其一）：

步骤 5.3 status 显示容器 Up 且健康检查通过
或手动验证：curl -s http://174.1.60.5:30000/health 返回 {"status":"ok"}

6. 验证服务

# 6.1 模型列表
curl -s http://174.1.60.5:30000/v1/models | head -c 300
# 应包含 "id": "kimi-k3"

# 6.2 推理冒烟（正确性：23×47 应算得 1081，输出可能带思考标签属正常）
curl -s -m 300 http://174.1.60.5:30000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "kimi-k3", "messages": [{"role": "user", "content": "What is 23*47? Answer briefly."}], "max_tokens": 128, "temperature": 0.1}'

# 6.3 服务日志（确认无 ERROR）
ssh 174.1.60.5 'docker logs kimi3_pro6000_sglang_tp32ep32_node0 2>&1 | tail -20'

⚠️ 首次请求很慢（TTFT 可达 100+ 秒）是正常现象：Triton/FlashKDA 内核首次 JIT 编译。发一个任意请求预热后，后续请求恢复正常（16K 输入 TTFT ~6s）。

7. 停止 / 重启

cd /data/yy/sskj

# 停止（4 节点容器全部移除）
PYTHONPATH=src python3 -m sskj.deploy stop \
  --profile pro6000/kimi3_pro6000_sglang_tp32ep32

# 重启 = 再次执行 5.2 的 start 命令（幂等，会先清旧容器）

# 手动兜底（start/stop 异常时）：4 节点各执行
for i in 5 6 7 8; do ssh 174.1.60.$i 'docker rm -f kimi3_pro6000_sglang_tp32ep32_node*'; done

8. 性能自检（可选）

# 稳态基准：16K 输入 TTFT / prefill 吞吐 / TPOT（先跑一次丢弃 JIT 冷启动）
cd /data/yy/sskj
scp -o ConnectTimeout=10 /data/flashkda_deploy/bench_16k_steady.py 174.1.60.5:/tmp/ 2>/dev/null || true
ssh 174.1.60.5 'python3 /tmp/bench_16k_steady.py 3'
# 参考值（稳态）：TTFT ~6s / prefill ~2700 tok/s / TPOT ~39ms / decode ~26 tok/s

正式压测（矩阵 + 自适应并发搜索）走 bench 层：

cd /data/yy/sskj/experiments/pro6000/kimi3_pro6000_sglang_tp32ep32
DRY_RUN=1 bash run_adaptive_concurrency_add16.sh        # 先看计划
bash run_adaptive_concurrency_add16.sh                  # 正式跑（放 tmux）

9. 故障排查速查

现象	原因	处理
首次请求 TTFT 100+ 秒	Triton/FlashKDA 内核首次 JIT 编译	正常现象，预热一次即可
`Not enough GPU memory for hybrid mamba state cache`	某节点显存被其他作业占用	检查 4 节点 `nvidia-smi`，确认 8 卡全空闲后重启部署
`ibv_create_cq failed: Cannot allocate memory`	容器 memlock 限制	部署配置已带 `--ulimit memlock=-1`，检查 profile 未被改动
`NCCL error: invalid usage`（graph 捕获时）	误设了 `NCCL_ALGO=TREE`	确认环境变量里没有 NCCL_ALGO
启动后 `/health` 一直不通	分布式初始化失败/节点未就绪	看 master 日志；确认 4 节点 GPU 全空闲后 `stop` + 重新 `start`
推理结果带 `<\|open\|>think` 标签	K3 思考型模型正常输出格式	非故障；如需精简可调 chat template（联系模型团队）
并发压测时部分请求失败	flashkda 后端已知问题（未修复）	当前默认 triton 后端无此问题；如误用 flashkda 见附录

附录 A：flashkda 可选后端（默认不启用）

FlashKDA（MoonshotAI CUTLASS KDA 内核，支持 sm_120）可作为 KDA prefill 的备选后端。实测与默认 triton prefill 性能等价（16K prefill 2693 vs 2695 tok/s），仅作备份用途。

启用方式（需模型团队协助）：

构建 wheel（脚本见 /data/flashkda_deploy/01_build_flashkda.sh，产物 flash_kda-0.0.1-cp312-cp312-linux_x86_64.whl 分发到 4 节点 /tmp/）
profile 增加 wheel 挂载与安装步骤，并在 LAUNCH_ARGS 加 --linear-attn-prefill-backend flashkda

已知问题：flashkda 后端在 4/8 并发压测下服务异常（纯 triton 无此问题），修复前不建议生产使用。

8.4 KiB Raw Blame History Unescape Escape