Kimi-K3¶

1 简介¶

Kimi-K3 是一种多模态混合专家模型，结合了 Kimi Delta Attention（KDA）、门控多头潜在注意力（MLA）、注意力残差、SiTU 激活函数和潜在 MoE 层。

本教程涵盖在 Atlas A3 上针对完整 W4A8 检查点的模型准备、安装、在线服务以及精度和性能评估。本教程基于 vLLM-Ascend main 与 vLLM 0.27.1。请使用支持 Kimi-K3 的主分支构建及其匹配的 vLLM 版本。

2 支持的功能¶

有关模型支持矩阵，请参阅支持的模型；有关功能配置，请参阅功能指南。

本指南涵盖 A3 W4A8 文本和多模态服务、TP/DP/EP、Prefix Cache、FULL_DECODE_ONLY ACL Graph，以及使用匹配草稿检查点的 DSpark。

3 前提条件¶

3.1 模型权重和硬件¶

模型	下载	用途	要求
Eco-Tech/Kimi-K3-w4a8	ModelScope	完整 93 层、896 专家 W4A8 目标模型	约 1.49 TB 权重存储；参考部署使用四个 Atlas 800 A3 节点，每个节点 16 个逻辑 NPU（DP4/TP16/EP64）
RadixArk/Kimi-K3-DSpark	ModelScope / Hugging Face	可选 GQA 草稿模型	将 `num_speculative_tokens` 设置为 `7`
Inferact/Kimi-K3-DSpark	ModelScope / Hugging Face	可选 MLA 草稿模型	将 `num_speculative_tokens` 设置为 `7`
Inferact/Kimi-K3-DSpark-Block5	ModelScope / Hugging Face	可选带五 token 块的 MLA 草稿模型	将 `num_speculative_tokens` 设置为 `5`

在启动服务之前，请下载权重、tokenizer 和 processor 文件。在每个节点上以相同路径挂载这些文件，例如位于 /path/to/models 下。权重大小是存储要求，而不是运行时 NPU 内存的估计值；KV 缓存、激活值、通信缓冲区以及可选草稿模型也需要内存。

路径说明：将模型权重下载到您选择的目录并记录该目录。确保后续部署命令中的模型路径与该目录一致。

3.2 验证多节点通信¶

在启动四节点服务之前，请按照验证多节点通信操作。在每个节点上使用可达地址和正确的通信接口。所有节点必须使用相同的模型版本和兼容的软件栈。

4 安装¶

本教程中的 Kimi-K3 安装和部署说明仅适用于 Atlas A3 系列。

4.1 Docker 镜像安装¶

请按照安装要求配置主机驱动和固件。在每个节点上启动下面的 A3 容器。

示例使用基于 vLLM 0.27 技术栈的主分支 nightly 镜像。请检查镜像包含 Kimi-K3 支持以及匹配的 vLLM 版本。固定其 digest 以实现可复现部署。要从所选源代码版本构建镜像，请遵循第 4.2 节。

export IMAGE=quay.io/ascend/vllm-ascend:nightly-main-a3
export MODEL_ROOT="/path/to/models"

docker run --rm -it \
  --name vllm-kimi-k3 \
  --net=host \
  --shm-size=1g \
  --device /dev/davinci0 \
  --device /dev/davinci1 \
  --device /dev/davinci2 \
  --device /dev/davinci3 \
  --device /dev/davinci4 \
  --device /dev/davinci5 \
  --device /dev/davinci6 \
  --device /dev/davinci7 \
  --device /dev/davinci8 \
  --device /dev/davinci9 \
  --device /dev/davinci10 \
  --device /dev/davinci11 \
  --device /dev/davinci12 \
  --device /dev/davinci13 \
  --device /dev/davinci14 \
  --device /dev/davinci15 \
  --device /dev/davinci_manager \
  --device /dev/devmm_svm \
  --device /dev/hisi_hdc \
  -v /usr/local/dcmi:/usr/local/dcmi \
  -v /usr/local/Ascend/driver:/usr/local/Ascend/driver \
  -v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \
  -v /etc/ascend_install.info:/etc/ascend_install.info \
  -v "$MODEL_ROOT:$MODEL_ROOT" \
  "$IMAGE" bash

在启动服务之前，验证已安装的版本：

python -m pip show vllm vllm-ascend

4.2 源代码安装¶

要从源代码构建 A3 镜像，请在 A3 构建主机上运行以下命令。Dockerfile 会安装匹配的 CANN/PyTorch/TorchNPU 技术栈并编译 Ascend 算子；VLLM_COMMIT 用于选择为所选 vLLM-Ascend 检出验证过的上游版本。

git clone --branch main https://github.com/vllm-project/vllm-ascend.git
cd vllm-ascend
git submodule update --init --recursive
docker build -f Dockerfile.a3 \
  --build-arg VLLM_COMMIT="$(cat .github/vllm-main-verified.commit)" \
  -t vllm-ascend-kimi-k3:main .
export IMAGE=vllm-ascend-kimi-k3:main

在每个节点上使用第 4.1 节中的容器命令使用该生成的镜像，并替换其中的 IMAGE 值。记录源代码版本和镜像 digest。对于 Docker 之外的安装，请遵循源代码安装指南，使用所选 main 检出及其已验证的 vLLM commit，而不是通用示例中的旧发布版本。

5 在线服务部署¶

5.1 四节点在线部署¶

完整检查点使用四个 Atlas 800 A3 节点进行 DP4/TP16/EP64 混合部署。首先启动 Node 0。每个 worker 拥有一个全局 DP rank，并通过 DP RPC 地址加入 Node 0。

在每个节点上设置以下变量：

# Ensure the model path matches the directory recorded during download
export MODEL_PATH="<KIMI_K3_FULL_W4A8_PATH>"
export TOKENIZER_PATH="<KIMI_K3_TOKENIZER_PATH>"
export LOCAL_IP="<CURRENT_NODE_IP>"
export NODE0_IP="<NODE0_IP>"
export NIC_NAME="<CURRENT_NODE_NIC>"
export SERVICE_PORT=8000
export RPC_PORT=13345
export DP_SIZE=4
export TP_SIZE=16

export HCCL_IF_IP=$LOCAL_IP
export GLOO_SOCKET_IFNAME=$NIC_NAME
export TP_SOCKET_IFNAME=$NIC_NAME
export HCCL_SOCKET_IFNAME=$NIC_NAME
export VLLM_ENGINE_READY_TIMEOUT_S=7200
export VLLM_EXECUTE_MODEL_TIMEOUT_SECONDS=3000
export PYTORCH_NPU_ALLOC_CONF=expandable_segments:True
export HCCL_BUFFSIZE=1024
export HCCL_BUFFSIZE_EP=2048
export HCCL_INTRA_PCIE_ENABLE=1
export HCCL_INTRA_ROCE_ENABLE=0
export HCCL_OP_EXPANSION_MODE=AIV
export OMP_PROC_BIND=false
export OPENBLAS_NUM_THREADS=1
export ASCEND_RT_VISIBLE_DEVICES=0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15

在节点 0 上运行：

vllm serve "$MODEL_PATH" \
  --host 0.0.0.0 \
  --port $SERVICE_PORT \
  --served-model-name kimi-k3 \
  --tokenizer "$TOKENIZER_PATH" \
  --tokenizer-mode kimi_k3 \
  --quantization ascend \
  --safetensors-load-strategy lazy \
  --tensor-parallel-size $TP_SIZE \
  --data-parallel-size $DP_SIZE \
  --data-parallel-size-local 1 \
  --data-parallel-address $LOCAL_IP \
  --data-parallel-rpc-port $RPC_PORT \
  --enable-expert-parallel \
  --enable-prefix-caching \
  --max-model-len 133120 \
  --max-num-seqs 16 \
  --max-num-batched-tokens 8192 \
  --gpu-memory-utilization 0.85 \
  --reasoning-parser kimi_k3 \
  --tool-call-parser kimi_k3 \
  --enable-auto-tool-choice \
  --compilation-config '{"cudagraph_mode":"FULL_DECODE_ONLY"}'

在节点 1 到 3 上运行。分别将 DP_START_RANK 设置为 1、2 或 3：

export DP_START_RANK="<1_OR_2_OR_3>"

vllm serve "$MODEL_PATH" \
  --headless \
  --host 0.0.0.0 \
  --port $SERVICE_PORT \
  --served-model-name kimi-k3 \
  --tokenizer "$TOKENIZER_PATH" \
  --tokenizer-mode kimi_k3 \
  --quantization ascend \
  --safetensors-load-strategy lazy \
  --tensor-parallel-size $TP_SIZE \
  --data-parallel-size $DP_SIZE \
  --data-parallel-size-local 1 \
  --data-parallel-start-rank $DP_START_RANK \
  --data-parallel-address $NODE0_IP \
  --data-parallel-rpc-port $RPC_PORT \
  --enable-expert-parallel \
  --enable-prefix-caching \
  --max-model-len 133120 \
  --max-num-seqs 16 \
  --max-num-batched-tokens 8192 \
  --gpu-memory-utilization 0.85 \
  --reasoning-parser kimi_k3 \
  --tool-call-parser kimi_k3 \
  --enable-auto-tool-choice \
  --compilation-config '{"cudagraph_mode":"FULL_DECODE_ONLY"}'

关键参数说明：

--data-parallel-size 4 和 --data-parallel-size-local 1 为每个节点创建一个 DP rank。--tensor-parallel-size 16 使用全部 16 个本地逻辑 NPU；--enable-expert-parallel 将专家分布到 64-rank EP 组中。
--data-parallel-start-rank 标识每个 worker 的全局 DP rank。--headless worker 加入节点 0，而不提供单独的 HTTP 端点。
--max-model-len 限制输入加输出 token 数；--max-num-batched-tokens 限制每次迭代调度的 token 数，--max-num-seqs 限制每个引擎的并发序列数。
--gpu-memory-utilization 控制模型执行器的设备内存预算。在增加序列长度、并发数或添加 draft 之前，请使用实际 checkpoint 检查容量。
--tokenizer-mode kimi_k3、--reasoning-parser kimi_k3 和 --tool-call-parser kimi_k3 选择 Kimi-K3 请求/响应格式。--enable-auto-tool-choice 启用自动工具选择。
FULL_DECODE_ONLY 捕获 decode 执行；--enable-prefix-caching 启用缓存前缀的复用。

在运行第 6 节中的请求之前，请等待所有 rank 完成权重加载和图编译。有关常见启动问题，请参阅公开 FAQ。

5.2 使用 DSpark 的推测解码¶

从第 3.1 节列出的模型权重中选择一个 GQA 或 MLA draft，并将其下载到每个节点的相同路径。以下配置对 RadixArk/Kimi-K3-DSpark 或 Inferact/Kimi-K3-DSpark 使用七个推测 token。对于 Inferact/Kimi-K3-DSpark-Block5，请选择该 checkpoint 的路径，并将 num_speculative_tokens 更改为 5。

将相同的推测配置添加到节点 0 和 headless worker 命令中：

--speculative-config \
'{
  "method": "dspark",
  "model": "<DSPARK_DRAFT_PATH>",
  "num_speculative_tokens": 7,
  "draft_tensor_parallel_size": 16,
  "max_model_len": 4096,
  "draft_sample_method": "greedy",
  "enforce_eager": true
}'

该示例在一个 query block 中提出七个 draft token，随后由目标模型进行验证。将 draft_tensor_parallel_size 设置为用于分片 draft 模型的拓扑。

6 功能验证¶

当所有四个节点都完成模型加载和图编译后，从服务网络中的主机向节点 0 服务发送请求。

curl "http://$NODE0_IP:8000/v1/chat/completions" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "kimi-k3",
    "messages": [
      {"role": "user", "content": "Explain why prefix caching helps repeated long prompts."}
    ],
    "temperature": 0,
    "max_tokens": 128
  }'

预期结果：HTTP 200，并返回包含非空 choice 和生成文本的 JSON 响应。当遇到停止 token 时，生成可能在 max_tokens 之前停止。

对于多模态冒烟测试，请将消息内容替换为图像和文本指令：

{
  "role": "user",
  "content": [
    {"type": "image_url", "image_url": {"url": "<IMAGE_URL_OR_DATA_URL>"}},
    {"type": "text", "text": "Describe the image."}
  ]
}

对于自动工具选择，请在启动命令中保留 --enable-auto-tool-choice 和 --tool-call-parser kimi_k3，并在聊天请求中包含 tools 和 tool_choice: "auto"。

7 精度评估¶

使用完整的 93 层、896 专家 checkpoint，配合第 5.1 节中的四节点服务。

7.1 使用 AISBench¶

按照使用 AISBench配置 kimi-k3 chat-completions 端点并运行 GPQA。在比较结果时，请固定模型和 tokenizer 版本、聊天渲染、推理模式、采样参数、数据集以及评估器版本。除分数外，请记录已完成、失败、缺失和未解析的样本。

7.2 使用 Language Model Evaluation Harness¶

请参阅使用 lm_eval了解评估器配置。在跨后端比较结果时，请使用相同的完整 checkpoint 和服务配置。

8 性能评估¶

8.1 使用 AISBench¶

有关配置和执行说明，请参阅AISBench 性能评估。

8.2 使用 vLLM 基准测试¶

在第 5.1 节中的服务就绪后，从服务网络中的负载生成器运行以下命令，该负载生成器需使用相同版本的 vLLM 和分词器文件。将 NODE0_IP 和 TOKENIZER_PATH 设置为服务地址和本地分词器路径。

export NODE0_IP="<NODE0_IP>"
export TOKENIZER_PATH="<KIMI_K3_TOKENIZER_PATH>"

vllm bench serve \
  --backend openai-chat \
  --base-url "http://$NODE0_IP:8000" \
  --endpoint /v1/chat/completions \
  --model kimi-k3 \
  --tokenizer "$TOKENIZER_PATH" \
  --tokenizer-mode kimi_k3 \
  --dataset-name random \
  --random-input-len 1024 \
  --random-output-len 128 \
  --random-range-ratio 0.0 \
  --num-prompts 100 \
  --max-concurrency 4 \
  --request-rate inf \
  --ignore-eos \
  --save-result \
  --result-dir ./benchmark-results

此示例测量 100 个请求，最多四个请求同时在途，使用随机 1024 token 输入和 128 token 输出。聊天格式可能会增加输入 token；--ignore-eos 可防止过早的 EOS 缩短请求的输出长度。--request-rate inf 会在并发槽位可用时立即发送请求。请确认所有 100 个受测请求均成功，并在控制台和保存的 JSON 结果中检查吞吐量、TTFT 和 TPOT。根据目标工作负载调整长度和并发；此示例并非峰值性能配置。有关更多选项，请参阅 vLLM 基准测试工具。

记录检查点修订版本、拓扑结构、图模式、Prefix Cache 设置、输入/输出长度、并发数、已完成请求数和错误数，并同时记录吞吐量和延迟。分别报告冷前缀和前缀命中工作负载。使用 DSpark 时，还需记录草稿检查点和投机 token 数。

9 性能调优¶

9.1 参考配置¶

以下是上述完整检查点命令所使用的配置，并非声称对所有工作负载都具有最优吞吐量或延迟。

部署	节点	总逻辑 NPU 数	每个 DP rank 的 TP	全局 DP / EP	每个引擎最大序列数	最大批处理 token 数	最大模型长度	图模式
完整 W4A8，混合 prefill/decode	4 A3	64	16	4 / 64	16	8192	133120	`FULL_DECODE_ONLY`

可选的 DSpark 使用草稿 TP16 和草稿 max_model_len=4096，如第 5.2 节所示。对于 RadixArk GQA 草稿或 Inferact 七 token MLA 草稿，使用七个投机 token；对于 Inferact/Kimi-K3-DSpark-Block5，使用五个。启用前请考虑其额外内存占用。

9.2 调优指南¶

目标	待评估参数	采用更改前需检查
更高吞吐量	逐步增加 `--max-num-seqs` 或 `--max-num-batched-tokens`	内存余量、已完成请求数和尾部延迟
更低延迟	将基线与匹配的 DSpark 草稿进行比较	同一工作负载下的端到端延迟、草稿接受率和准确率
更长上下文	同时调整 `--max-model-len`、并发数和 token 预算	目标/草稿兼容性和可用的混合 KV-cache 容量
重复 Prompt	启用 Prefix Cache，并分别比较冷请求和缓存请求	缓存命中指标和输出正确性

有关通用调优方法，请参阅公开性能调优指南和功能矩阵。

10 常见问题解答¶

对于常见的环境、安装和通用参数问题，请参阅公开常见问题解答。本节涵盖 Kimi-K3 特定问题。

使用 DSpark 时应选择哪个检查点？¶

使用与目标架构、分词器和量化变体匹配的草稿。第 3.1 节列出了 RadixArk GQA 草稿和两个 Inferact MLA 草稿，以及它们的 num_speculative_tokens 值。对于 QuaRot 检查点，请在每个节点上保留检查点的量化元数据和捆绑的旋转张量。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 vl/vllm-ascend