Kimi-K2-Thinking

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.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 {{.Names}}\t{{.Status}}"

预期状态：

容器名称为 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 .

要验证源码安装，请运行：

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`	版本敏感 / 性能	在昇腾上启用任务队列调度。本文档验证了 `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`	已启用	性能	为验证的基线和随机提示基准测试禁用前缀缓存。本教程未验证前缀缓存。

常见问题提示： 部署过程中遇到常见的环境、安装和通用参数问题，请参阅公共FAQ。如果服务在高并发下运行，请在提高请求速率前检查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）、最大2048个输出token、批大小1。

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

任务	版本	过滤器	样本数	指标	值	标准误差
`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：

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

最大并发数	提示词	成功	持续时间（秒）	请求吞吐量（请求/秒）	输出吞吐量（token/秒）	总吞吐量（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 启动服务器以启用短名称。