Kimi-K3

1 简介

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

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

2 支持的特性

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

本指南涵盖 A3 W4A8 文本和多模态服务、TP/DP/EP、前缀缓存、FULL_DECODE_ONLY ACL 图，以及使用匹配草稿检查点的 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	可选的 MLA 草稿，使用五 token 块	将 num_speculative_tokens 设置为 5

在启动服务前，请下载权重、分词器和处理器文件。将它们挂载到每个节点的相同路径下，例如 /path/to/models。权重大小是存储需求，而非运行时 NPU 内存的估算值；KV 缓存、激活、通信缓冲区以及可选的草稿模型也需要内存。

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

3.2 验证多节点通信

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

4 安装

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

4.1 Docker 镜像安装

请遵循安装要求中的 主机驱动和固件要求。在每个节点上启动下面的A3容器。

该示例使用 main 分支的 nightly 镜像，适用于基于 vLLM 0.27 的软件栈。请确认镜像包含 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 构建主机上从源码构建镜像，请运行以下命令。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值。记录源码修订版本和镜像摘要。 对于Docker之外的安装，请遵循 源码安装指南，使用 所选的主分支检出及其已验证的vLLM提交，而不是通用示例中的较旧 发布版本。

5 在线服务部署

5.1 四节点在线部署

完整检查点使用四个 Atlas 800 A3 节点，采用 DP4/TP16/EP64 混合部署。首先启动节点 0。每个 worker 拥有一个全局 DP rank，并通过 DP RPC 地址加入节点 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 等级。--tensor-parallel-size 16 使用全部16个本地逻辑NPU； --enable-expert-parallel 将专家分布到64等级的EP组中。
• --data-parallel-start-rank 标识每个工作进程的全局DP等级。 --headless 工作进程加入节点0，而不提供单独的HTTP端点。
• --max-model-len 限制输入加输出令牌数； --max-num-batched-tokens 限制每次迭代调度的令牌数， --max-num-seqs 限制每个引擎的并发序列数。
• --gpu-memory-utilization 控制模型执行器的设备内存 预算。在增加序列长度、并发性或添加草稿之前，请使用实际检查点检查容量。
• --tokenizer-mode kimi_k3、--reasoning-parser kimi_k3 和 --tool-call-parser kimi_k3 选择Kimi-K3请求/响应格式。 --enable-auto-tool-choice 启用自动工具选择。
• FULL_DECODE_ONLY 捕获解码执行；--enable-prefix-caching 启用缓存前缀的复用。

等待所有等级完成权重加载和图编译，然后再运行第6节中的请求。对于一般的启动问题，请参阅 公共FAQ。

5.2 使用DSpark进行推测解码

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

将相同的推测配置添加到节点0和无头工作进程命令中：

--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
}'

该示例在一个查询块中提出七个草稿令牌，随后进行 目标模型验证。 将draft_tensor_parallel_size设置为用于分片草稿模型的拓扑。

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，JSON响应包含非空的choice和 生成的文本。当达到停止令牌时，生成可能会在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 精度评估

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

7.1 使用 AISBench

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

7.2 使用 Language Model Evaluation Harness

有关评估器设置，请参阅使用lm_eval。 在跨后端比较结果时，使用相同的完整检查点和服务配置。

8 性能评估

8.1 使用 AISBench

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

8.2 使用 vLLM Benchmark

在第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令牌输入和128令牌输出。聊天格式可以增加输入令牌； --ignore-eos防止早期EOS缩短请求的输出长度。 --request-rate inf在并发槽可用时立即发送请求。 检查所有100个测量的请求是否成功，并在控制台和保存的JSON结果中查看吞吐量、TTFT和 TPOT。根据预期工作负载调整长度和并发性；此示例不是峰值性能配置。 有关其他选项，请参阅vLLM基准测试工具。

记录检查点修订版、拓扑、图模式、前缀缓存设置、 输入/输出长度、并发性、完成的请求和错误计数，以及 吞吐量和延迟。分别报告冷前缀和前缀命中工作负载。 使用DSpark时，还要记录草稿检查点和推测令牌 计数。

9 性能调优

9.1 参考配置

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

部署	节点	逻辑NPU总数	每个DP等级的TP	全局DP / EP	每个引擎的最大序列数	最大批量令牌数	最大模型长度	图模式
Full W4A8, mixed 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七令牌MLA草稿使用七个推测令牌，对Inferact/Kimi-K3-DSpark-Block5使用五个。 在启用之前考虑其额外内存。

9.2 调优指南

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

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

10 常见问题

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

我应该使用哪个检查点与 DSpark 搭配？

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