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（64GB × 16）节点	ModelScope \| Hugging Face

建议将模型权重下载到共享目录，例如 /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.23.0-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 {% raw %}{{.Names}}\t{{.Status}}{% endraw %}"

预期状态：

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

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

npu-smi info

预期状态：

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

4.2 源代码安装¶

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

# Install vLLM.
git clone --depth 1 --branch v0.23.0 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.23.0 https://github.com/vllm-project/vllm-ascend.git
cd vllm-ascend
pip install -e .

To verify the source installation, run:

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（64GB × 16）节点，tensor-parallel-size 应至少为 16。

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

:block_name: kimi_k2_thinking_single_node
:converter_tag: single_node
:test_case_path: tests/e2e/nightly/single_node/models/configs/Kimi-K2-Thinking.yaml

参数和环境变量说明：

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

参数	已验证值	类别	说明和调优建议
`moonshotai/Kimi-K2-Thinking`	模型路径	模型特定	指定传递给 `vllm serve` 的模型权重路径。由于脚本中未设置 `--served-model-name`，除非你添加显式的 served-model-name 覆盖，否则 API 请求必须使用 `moonshotai/Kimi-K2-Thinking` 作为模型名称；参见第 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 cache 预留。本文档验证了 `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 cache 规划的 NPU HBM 比例。本文档验证了 `0.9`；其他值需要单独验证启动、OOM 和运行时稳定性。
`--trust-remote-code`	已启用	模型特定	由于模型包包含模型特定的配置、建模、tokenizer 和 chat-template 文件，因此需要启用。只有在将远程代码依赖替换为经过验证的原生实现后，才可禁用它。
`--enable-expert-parallel`	已启用	模型特定 / 性能	为 Kimi-K2-Thinking MoE 层启用专家并行，以便专家可以分布在多个 NPU 上。本文档验证其处于启用状态；本教程未验证禁用该选项。
`--no-enable-prefix-caching`	已启用	性能	为已验证的基线和随机 prompt 基准测试禁用前缀缓存。本教程未验证前缀缓存。

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

服务验证：

服务启动后，你应该看到类似以下日志：

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

预期状态：

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

6 功能验证¶

服务启动后，可以通过发送 prompt 来调用模型：

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 精度评估¶

7.1 使用 AISBench¶

有关详细信息，请参阅使用 AISBench。

7.2 使用 lm-eval¶

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

有关 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）、最大 2048 个输出 token、批处理大小 1。

以下是由 vllm-ascend:v0.20.2rc1 驱动的 Kimi-K2-Thinking 在单个 Atlas 800 A3 节点（64GB × 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 性能评估¶

8.1 使用 vLLM 基准测试¶

有关更多详细信息，请参阅 vllm benchmark。

测试命令示例：

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。

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

随机输入长度	随机输出长度	成功	持续时间（秒）	请求吞吐量（req/s）	输出吞吐量（tok/s）	总吞吐量（tok/s）	平均 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 的参考结果如下：

最大并发	prompt 数	成功	持续时间（秒）	请求吞吐量（req/s）	输出吞吐量（tok/s）	总吞吐量（tok/s）	平均 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 常见问题¶

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

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

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

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