Kimi-K2-Thinking¶

1 简介¶

Kimi-K2-Thinking 是 Moonshot AI 开发的大规模混合专家（MoE）模型。它采用混合思考架构，在复杂推理和问题求解任务中表现出色。

本文档将展示该模型的主要验证步骤和参考，包括支持的特性、环境准备、安装、在线服务部署、功能验证、精度评估、性能评估、性能调优以及常见问题解答。

本文档基于 vLLM-Ascend v0.9.0rc1 进行验证和编写。当前模型（Kimi-K2-Thinking）在该版本中首次得到支持，v0.9.0rc1 及更高版本 可以稳定运行。建议在使用本文档时，采用最新的候选版本或稳定版本。

2 支持的特性¶

请参阅支持的特性矩阵获取模型支持的特性列表。

请参阅特性指南获取特性的配置方法。

3 前提条件¶

3.1 模型权重¶

Kimi-K2-Thinking（bfloat16）：需要 1 个 Atlas 800 A3（64G × 16）节点。下载模型权重。

建议将模型权重下载到共享目录，例如 /mnt/sfs_turbo/.cache/。

下载模型权重后，请将原始模型的 config.json 中 "quantization_config.config_groups.group_0.targets" 的值从 ["Linear"] 修改为 ["MoE"]，以使用量化模型。

{
  "quantization_config": {
    "config_groups": {
      "group_0": {
        "targets": [
          "MoE"
        ]
      }
    }
  }
}

您的模型文件结构如下所示：

.
|-- chat_template.jinja
|-- config.json
|-- configuration_deepseek.py
|-- configuration.json
|-- generation_config.json
|-- model-00001-of-000062.safetensors
|-- ...
|-- model-00062-of-000062.safetensors
|-- model.safetensors.index.json
|-- modeling_deepseek.py
|-- tiktoken.model
|-- tokenization_kimi.py
|-- tokenizer_config.json

4 安装¶

4.1 Docker 镜像安装¶

您可以使用官方 Docker 镜像直接运行 Kimi-K2-Thinking。

根据您的机器类型选择镜像，并在节点上启动 Docker 镜像，请参考使用 Docker 安装。

   # Update the vllm-ascend image according to your environment.
   export IMAGE=quay.io/ascend/vllm-ascend:v0.22.1rc1-a3

# Run the container using the defined variables
# Note: If you are running bridge network with docker, please expose available ports for multiple nodes communication in advance
docker run --rm \
--name $NAME \
--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/tools/hccn_tool:/usr/local/Ascend/driver/tools/hccn_tool \
-v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \
-v /usr/local/Ascend/driver/lib64/:/usr/local/Ascend/driver/lib64/ \
-v /usr/local/Ascend/driver/version.info:/usr/local/Ascend/driver/version.info \
-v /etc/ascend_install.info:/etc/ascend_install.info \
-v /mnt/sfs_turbo/.cache:/home/cache \
-it $IMAGE bash

参数说明：

IMAGE：指定 vllm-ascend 镜像。-a3 后缀选择 Atlas A3 镜像。
NAME：指定容器名称。
--net=host：使用主机网络，因此 vLLM 服务端口直接暴露在主机上。
--shm-size=1g：配置容器共享内存。
--device /dev/davinci[0-15]：向容器暴露 16 个 Ascend NPU 设备。
--device /dev/davinci_manager、--device /dev/devmm_svm 和 --device /dev/hisi_hdc：暴露所需的 Ascend 运行时设备文件。
-v /usr/local/dcmi:/usr/local/dcmi：挂载 DCMI 工具以进行设备管理。
-v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi：挂载 NPU 监控命令。
-v /usr/local/Ascend/driver/*：挂载 Ascend 驱动库和版本文件。
-v /etc/ascend_install.info:/etc/ascend_install.info：挂载 Ascend 安装元数据。
-v /mnt/sfs_turbo/.cache:/home/cache：挂载共享模型缓存目录。如果模型权重存储在其他位置，请更新此路径。

容器启动后，在主机上运行以下命令验证容器状态：

docker ps --filter name=vllm-ascend --format "table {{.Names}}\t{{.Status}}"

预期状态：

容器名称为 vllm-ascend。
状态为 Up ...。
容器不会立即退出。

在容器中运行以下命令验证 Ascend 设备是否可见：

npu-smi info

预期状态：

命令成功退出。
输出列出了预期的 NPU 设备。
设备健康状态正常。

4.2 源码安装¶

如果不想使用 Docker 镜像，也可以从源码构建：

# Install vLLM.
git clone --depth 1 --branch v0.22.1 https://github.com/vllm-project/vllm
cd vllm
VLLM_TARGET_DEVICE=empty pip install -e .
cd ..

# Install vLLM Ascend.
git clone --depth 1 --branch v0.22.1rc1 https://github.com/vllm-project/vllm-ascend.git
cd vllm-ascend
pip install -e .

验证源码安装，请运行：

python -c "import vllm; import vllm_ascend; print('vllm and vllm_ascend import ok')"

预期状态：

命令成功退出。
打印 vllm and vllm_ascend import ok。

5 在线服务部署¶

5.1 单节点在线部署¶

单节点部署在同一节点内完成 Prefill 和 Decode，适用于中等并发需求的在线推理场景。

对于 Atlas 800 A3（64G × 16）节点，tensor-parallel-size 至少应为 16。

运行以下脚本启动 vLLM 服务器：

export HCCL_BUFFSIZE=1024
export TASK_QUEUE_ENABLE=1
export OMP_PROC_BIND=false
export HCCL_OP_EXPANSION_MODE=AIV
export PYTORCH_NPU_ALLOC_CONF=expandable_segments:True
export SERVER_PORT=8000

vllm serve moonshotai/Kimi-K2-Thinking \
  --tensor-parallel-size 16 \
  --port $SERVER_PORT \
  --max-model-len 8192 \
  --max-num-batched-tokens 8192 \
  --max-num-seqs 12 \
  --gpu-memory-utilization 0.9 \
  --trust-remote-code \
  --enable-expert-parallel \
  --no-enable-prefix-caching

参数和环境变量说明：

下表涵盖了生成的 model、所有 envs 和所有 server_cmd 条目。参数按审查优先级分类：版本敏感参数、性能参数和 Kimi-K2-Thinking 特定参数。

参数	已验证值	类别	描述与调优指南
`moonshotai/Kimi-K2-Thinking`	模型路径	模型特定	指定传递给 `vllm serve` 的模型权重路径。由于脚本中未设置 `--served-model-name`，API 请求必须使用 `moonshotai/Kimi-K2-Thinking` 作为模型名称，除非您添加了显式的 served-model-name 覆盖；请参阅第 10 章的常见问题解答。
`HCCL_BUFFSIZE`	`1024`	性能	配置分布式 NPU 通信使用的 HCCL 通信缓冲区。本文档验证了 `1024`；其他值需要单独验证吞吐量、TTFT、TPOT 和 HCCL 稳定性。
`TASK_QUEUE_ENABLE`	`1`	版本敏感 / 性能	在 Ascend 上启用任务队列调度。本文档验证了 `1`；其他值或版本变更需要验证启动和首次请求。
`OMP_PROC_BIND`	`false`	性能	避免过于严格的 OpenMP CPU 绑定。本文档验证了 `false`；其他值需要单独验证 CPU 亲和性、NPU 健康和 HCCL 稳定性。
`HCCL_OP_EXPANSION_MODE`	`AIV`	性能	启用 AIV 通信路径。本文档验证了 `AIV`；其他值需要单独验证吞吐量和延迟。
`PYTORCH_NPU_ALLOC_CONF`	`expandable_segments:True`	内存 / 性能	减少 NPU 内存碎片。本文档验证了 `expandable_segments:True`；其他分配器设置需要单独验证启动、内存和运行时稳定性。
`SERVER_PORT` 和 `--port`	`8000`	服务	设置 OpenAI 兼容的服务端口。文档生成器将 YAML 中的 `DEFAULT_PORT` 映射为 `8000`；如果更改此值，请更新 curl 示例。
`--tensor-parallel-size`	`16`	模型特定 / 性能	使用一个 Atlas 800 A3 节点上的全部 16 个 NPU。本文档验证了 `tp16`；其他拓扑需要单独验证内存、精度和通信。
`--max-model-len`	`8192`	性能	设置单个请求的最大输入加输出 token 数，并决定 KV 缓存预留。本文档验证了 `8192`；更大的值需要单独验证 NPU 内存、精度和性能。请使其接近您工作负载的实际最大输入和输出长度。
`--max-num-batched-tokens`	`8192`	性能	限制单个调度步骤中处理的 token 数。本文档验证了 `8192`；其他值需要单独验证内存、TTFT、TPOT 和吞吐量。
`--max-num-seqs`	`12`	性能	限制同时调度的活动序列数。本文档验证了 `12`；更高的值需要单独验证尾延迟和吞吐量。第 8 章的参考扫描显示并发 16 会导致 TTFT 严重增长；在生产环境中提高该值之前，请验证尾延迟。
`--gpu-memory-utilization`	`0.9`	内存 / 性能	控制 vLLM 用于 KV 缓存规划的 NPU HBM 比例。本文档验证了 `0.9`；其他值需要单独验证启动、OOM 和运行时稳定性。
`--trust-remote-code`	启用	模型特定	必需，因为模型包包含模型特定的配置、建模、分词器和聊天模板文件。仅在用经过验证的原生实现替换远程代码依赖后才能禁用它。
`--enable-expert-parallel`	启用	模型特定 / 性能	为 Kimi-K2-Thinking MoE 层启用专家并行，使专家可以分布到多个 NPU 上。本文档验证了启用状态；本教程未验证禁用状态。
`--no-enable-prefix-caching`	启用	性能	为已验证的基线和随机提示基准禁用前缀缓存。本教程未验证前缀缓存。

常见问题提示： 有关部署过程中的常见环境、安装和一般参数问题，请参阅公共常见问题解答。如果服务在高并发下运行，请在提高请求速率之前验证 NPU 健康和 HCCL 状态。

服务验证：

服务启动后，您应看到类似如下的日志：

INFO:     Started server process [...]
INFO:     Waiting for application startup.
INFO:     Application startup complete.

预期状态：

服务器进程成功启动。
没有与 HCCL 或 NPU 初始化相关的错误日志。
容器不会立即退出。

6 功能验证¶

服务启动后，可通过发送提示词来调用模型：

curl http://localhost:8000/v1/chat/completions -H "Content-Type: application/json" -d '{
  "model": "moonshotai/Kimi-K2-Thinking",
  "messages": [
    {"role": "user", "content": "Who are you?"}
  ],
  "temperature": 1.0
}'

预期结果：

HTTP 状态码为 200。
choices[0].message.content 包含生成的助手回复。

7 精度评估¶

使用 AISBench¶

详细信息请参考使用AISBench。

使用 lm-eval¶

您可以使用lm-eval通过OpenAI兼容API评估模型精度。

关于lm_eval的安装，请参考使用lm_eval。

运行lm_eval执行精度评估：

lm_eval \
  --model local-completions \
  --model_args model=moonshotai/Kimi-K2-Thinking,base_url=http://127.0.0.1:8000/v1/completions,tokenized_requests=False,trust_remote_code=True \
  --tasks gsm8k \
  --output_path ./

参考配置：gsm8k（5-shot）、--apply_chat_template、--fewshot_as_multiturn、贪心解码（temperature=0.0、top_p=1.0）、最大输出token数2048、批大小1。

以下为基于vllm-ascend:v0.20.2rc1的Kimi-K2-Thinking在单个Atlas 800 A3节点（64G × 16）上评估的参考gsm8k结果。

任务	版本	过滤器	n-shot	指标	值	标准误差
`gsm8k`	3	`flexible-extract`	5	`exact_match`	0.8992	0.0083
`gsm8k`	3	`strict-match`	5	`exact_match`	0.8453	0.0100

8 性能评估¶

更多详情请参考vllm基准测试。

测试命令示例：

vllm bench serve \
  --backend openai-chat \
  --model moonshotai/Kimi-K2-Thinking \
  --endpoint /v1/chat/completions \
  --dataset-name random \
  --random-input-len 1024 \
  --random-output-len 1024 \
  --num-prompts 10 \
  --request-rate 1

基准测试完成后，您将获得性能结果，包括请求吞吐量、输出token吞吐量、TTFT、TPOT和ITL。

以下参考结果基于vllm-ascend:v0.20.2rc1在单个Atlas 800 A3节点（64G × 16）上获得，使用OpenAI聊天服务、随机输入/输出长度、10个提示词和--request-rate 1：

随机输入长度	随机输出长度	成功	持续时间 (秒)	请求吞吐量 (请求/秒)	输出吞吐量 (令牌/秒)	总吞吐量 (令牌/秒)	平均 TTFT (毫秒)	平均 TPOT (毫秒)	平均 ITL (毫秒)
512	512	10 / 10	111.00	0.09	46.12	94.38	507.60	200.47	200.08
1024	1024	10 / 10	221.52	0.05	46.23	93.48	566.39	208.20	208.00
2048	2048	10 / 10	479.72	0.02	42.69	85.78	722.32	230.26	230.15

对于并发扫描，保持输入和输出长度固定，并改变--max-concurrency：

MODEL_NAME=moonshotai/Kimi-K2-Thinking
INPUT_LEN=1024
OUTPUT_LEN=1024

for CONCURRENCY in 1 2 4 8 16 32; do
  NUM_PROMPTS=$((CONCURRENCY * 10))
  vllm bench serve \
    --backend openai-chat \
    --model "$MODEL_NAME" \
    --endpoint /v1/chat/completions \
    --dataset-name random \
    --random-input-len "$INPUT_LEN" \
    --random-output-len "$OUTPUT_LEN" \
    --num-prompts "$NUM_PROMPTS" \
    --request-rate inf \
    --max-concurrency "$CONCURRENCY"
done

1024个输入token和1024个输出token的参考结果如下：

最大并发数	提示数	成功	持续时间 (秒)	请求吞吐量 (请求/秒)	输出吞吐量 (令牌/秒)	总吞吐量 (令牌/秒)	平均 TTFT (毫秒)	P99 TTFT (毫秒)	平均 TPOT (毫秒)
1	10	10 / 10	595.07	0.02	17.21	34.80	473.71	712.49	57.71
2	20	20 / 20	623.88	0.03	32.83	66.35	708.16	996.59	60.29
4	40	40 / 40	725.38	0.06	56.47	114.13	956.11	1137.55	69.97
8	80	80 / 80	907.44	0.09	90.28	182.43	1361.85	1900.15	87.37
16	160	160 / 160	3093.07	0.05	52.97	107.04	76766.84	251245.22	222.07

注意： 在并发级别为 16 时，平均 TTFT 显著增加（76.7 秒），表明存在严重的排队延迟。对于生产部署，建议根据延迟要求限制并发，或者在 NPU 内存允许的情况下增加 --max-num-seqs 和 --max-num-batched-tokens。

9 性能调优¶

9.1 推荐配置¶

注意： 以下配置在特定测试环境中验证，仅供参考。最佳配置取决于最大输入/输出长度、前缀缓存命中率、精度要求和部署机器比例等因素。建议参考第 9.2 节根据实际情况进行调优。

表1：场景概览¶

场景	部署模式	NPU总数	权重版本	关键考量
长上下文	单节点	16 (A3)	bfloat16	保持 `--max-model-len` 接近实际最大输入和输出长度，并在内存压力高时首先减少 `--max-num-seqs`。此单节点基线的已验证范围涵盖第 8 章中最多 2K 输入 / 2K 输出。
低延迟	单节点	16 (A3)	bfloat16	从已验证基线（`12` 和 `8192`）减少 `--max-num-seqs` 和 `--max-num-batched-tokens` 以降低排队延迟。在第 8 章的并发扫描中，并发 1-4 将平均 TTFT 保持在 1 秒以下；请根据目标延迟 SLO 验证 TTFT、TPOT 和尾延迟。
高吞吐量	单节点	16 (A3)	bfloat16	逐步增加 `--max-num-seqs`，并使用接近实际工作负载的请求速率进行基准测试。在第 8 章的 1K/1K 并发扫描中，并发 8 提供了最佳输出吞吐量；在生产环境中使用更高并发之前，请验证尾延迟。

9.2 调优指南¶

9.2.1 通用调优参考¶

通用调优方法请参考优化与调优。

详细特性描述请参考特性指南。

10 常见问题¶

关于常见环境、安装和通用参数问题，请参考公共FAQ；本章仅涵盖模型特定问题。

问：使用 model: "Kimi-K2-Thinking" 请求时，API返回 {"error":"Model not found"} 或 404？

答：服务器默认使用完整路径moonshotai/Kimi-K2-Thinking注册模型。当请求使用短名称Kimi-K2-Thinking且未覆盖--served-model-name时，服务器无法解析模型ID。请在请求中使用"model": "moonshotai/Kimi-K2-Thinking"，或使用--served-model-name Kimi-K2-Thinking启动服务器以启用短名称。