BitCPM4-0.5B (MiniCPM4-0.5B) on vLLM-Ascend 0.18.0rc1

1. 简介

本文档记录 OpenBMB/BitCPM4-0.5B（即 MiniCPM4-0.5B）在 vLLM-Ascend 0.18.0rc1 环境的快速部署与验证结果。

该模型架构为 MiniCPMForCausalLM，vLLM 与 vllm-ascend 均已原生支持，无需任何代码改动即可直接部署。适配过程仅需关注昇腾 NPU 内存约束下的启动参数调优。

模型关键特性：

Attention：GQA（num_attention_heads=16，num_key_value_heads=2）
RoPE：longrope（max_position_embeddings=32768）
特殊缩放参数：scale_emb=12、dim_model_base=256、scale_depth=1.4
权重精度：bfloat16，无量化配置

2. 验证环境

组件	版本
`vllm-ascend`	`0.18.0rc1`
`vllm`	`0.18.0+empty`
`transformers`	`4.57.6`
`torch-npu`	`2.9.0.post1+gitee7ba04`

NPU：1 逻辑卡（Ascend910）
模型路径：/opt/atomgit/models/OpenBMB/BitCPM4-0___5B
服务端口：8000

3. 服务启动

启动前可先检查端口：

ss -lntp | grep ':8000 ' || true

已验证通过的启动命令（单卡，低显存占用）：

export VLLM_USE_MODELSCOPE=true
export PYTORCH_NPU_ALLOC_CONF=expandable_segments:True
export OMP_PROC_BIND=false
export OMP_NUM_THREADS=1
export TASK_QUEUE_ENABLE=1

vllm serve /opt/atomgit/models/OpenBMB/BitCPM4-0___5B \
  --host 0.0.0.0 \
  --port 8000 \
  --seed 1024 \
  --served-model-name bitcpm4-0.5b \
  --max-num-seqs 16 \
  --max-model-len 512 \
  --trust-remote-code \
  --dtype bfloat16 \
  --gpu-memory-utilization 0.08

参数说明：

--trust-remote-code：模型仓库包含自定义 modeling_minicpm.py，必须开启
--gpu-memory-utilization 0.08：该模型参数量仅 0.5B，但昇腾 NPU 在启动时会预留大量内存用于 ACL Graph 编译与 KV Cache；在显存受限环境下需显式调低此值（实测 0.08 可稳定启动）
--max-model-len 512：验证阶段限制序列长度以降低内存开销，生产环境可按需上调

Fallback 启动命令（若 Graph 捕获失败，可切换 eager 模式）：

vllm serve /opt/atomgit/models/OpenBMB/BitCPM4-0___5B \
  --host 0.0.0.0 \
  --port 8000 \
  --seed 1024 \
  --served-model-name bitcpm4-0.5b \
  --max-num-seqs 16 \
  --max-model-len 512 \
  --trust-remote-code \
  --dtype bfloat16 \
  --gpu-memory-utilization 0.08 \
  --enforce-eager

4. 适配验证

Stage A — Dummy Fast Gate

使用 dummy 权重快速验证建模链路无 import/operator 错误：

vllm serve /opt/atomgit/models/OpenBMB/BitCPM4-0___5B \
  --load-format dummy \
  --dtype bfloat16 \
  --max-model-len 512 \
  --max-num-seqs 16 \
  --trust-remote-code \
  --port 8000

验证结果：服务正常启动，/v1/models 返回 200。

Stage B — Real-Weight Mandatory Gate

使用真实权重验证加载与推理：

vllm serve /opt/atomgit/models/OpenBMB/BitCPM4-0___5B \
  --dtype bfloat16 \
  --max-model-len 512 \
  --max-num-seqs 16 \
  --trust-remote-code \
  --gpu-memory-utilization 0.08 \
  --port 8000

验证结果：权重加载无报错，模型正常就绪，KV Cache 分配约 3.98 GiB。

Smoke 验证

基础检查：

curl -sf http://127.0.0.1:8000/v1/models

推理验证：

curl -s http://127.0.0.1:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bitcpm4-0.5b",
    "messages": [
      {"role": "user", "content": "你好"}
    ],
    "temperature": 0,
    "max_tokens": 32
  }'

验证结果：

/v1/models 返回 200
/v1/chat/completions 返回 200，生成结果符合预期
ACL Graph 编译正常，无 operator 不兼容报错

5. 精度评测

5.1 前向传播 logits 精度（核心量化证明）

自回归文本生成对 bfloat16 数值漂移极为敏感（蝴蝶效应），因此采用单步前向 logits 对比作为核心量化指标，排除自回归累积误差干扰。

对比方法：对同一输入文本，分别提取 transformers（参考）与 vLLM-Ascend（目标）在最后一个位置的 log_softmax 输出（top-20），计算分布差异。

指标	数值
参考框架	`transformers 4.57.6`（bfloat16, NPU）
目标框架	`vLLM-Ascend 0.18.0rc1`（bfloat16, eager, NPU）
Top-1 token 一致性	100%（完全一致）
Top-5 token 一致性	100%（5/5）
Top-20 重叠率	100%（20/20）
最大相对误差	0.9301%
平均相对误差	0.3289%
KL 散度	4e-8（趋近于 0）

结论：前向传播数值精度与参考基准高度一致，最大相对误差 < 1%，满足部署精度要求。

5.2 贪婪解码文本一致性对比

在 logits 精度已验证一致的基础上，进一步进行端到端贪婪解码（temperature=0, do_sample=False）文本生成对比，每组 prompt 固定生成长度为 32 tokens。文本级分歧属于 bfloat16 自回归累积误差的正常表现。

指标	数值
参考框架	`transformers 4.57.6`（bfloat16, greedy, CPU）
目标框架	`vLLM-Ascend 0.18.0rc1`（bfloat16, greedy, eager, NPU）
测试 prompt 数	`3`
精确匹配率	`66.7%`（2 / 3）
平均 Token 准确率	`87.5%`

详细结果：

Prompt	精确匹配	Token 准确率	参考输出（前 32 token）	vLLM-Ascend 输出（前 32 token）
`你好`	✅	`100.00%`	你好，我是MiniCPM系列模型，由面壁智能和OpenBMB开源社区开发。详细信息请访问 https://github.com/OpenB	你好，我是MiniCPM系列模型，由面壁智能和OpenBMB开源社区开发。详细信息请访问 https://github.com/OpenB
`1+1等于几`	❌	`62.50%`	当我们看到数字1+1时，实际上是在进行加法运算。根据数学中的基本原则，任何数与1相加，其值都不会发生任何变化	当我们看到数字1+1时，实际上是在进行加法运算。根据数学中的基本原则，当我们把两个相同的数相加时，我们实际上是在计算
`北京是中国的首都`	✅	`100.00%`	北京是中国的首都，这是国际社会普遍承认的事实。中国是一个拥有五千年文明历史的国家，北京作为中国的首都，承载着国家的政治、经济	北京是中国的首都，这是国际社会普遍承认的事实。中国是一个拥有五千年文明历史的国家，北京作为中国的首都，承载着国家的政治、经济

说明：

Prompt 1+1等于几 在第 20 个 token 处发生分歧，属于 bfloat16 低精度浮点在自回归过程中因算子调度路径不同导致的正常累积漂移。
补充验证：transformers 在 NPU 上直接运行同样存在与 CPU 参考输出的分歧，进一步说明该差异属于硬件/框架层面的数值精度波动，而非 vLLM-Ascend 的建模错误。

6. 功能支持矩阵

特性	支持状态	说明
ACL Graph 编译	✅ 支持	已验证图捕获与解码正常
文本推理	✅ 支持	Chat Completions API 已验证
GQA	✅ 支持	vLLM `minicpm.py` 原生实现
LongRoPE	✅ 支持	已加载 `longrope` 缩放因子
`scale_emb` / `scale_depth`	✅ 支持	vLLM 已覆盖
MoE / EP	N/A	该模型非 MoE 架构
MTP	N/A	该模型无 MTP 结构
VL 多模态	N/A	纯文本模型

7. 代码改动清单

本次适配无需任何代码改动。

vLLM 侧 registry.py 已注册 "MiniCPMForCausalLM": ("minicpm", "MiniCPMForCausalLM")，且 minicpm.py 已完整支持 scale_emb、dim_model_base、scale_depth、longrope 等特性。vllm-ascend 测试套件也已包含 OpenBMB/MiniCPM4-0.5B 的 E2E 测试用例。

8. 注意事项

必须开启 --trust-remote-code 模型仓库包含 modeling_minicpm.py 自定义代码，不开启将导致 ValidationError。
NPU 显存占用预估与实际差异 虽然模型仅 0.5B 参数，但昇腾 NPU 在 vLLM 启动时会为 ACL Graph 编译、KV Cache、通信缓冲区等预留内存。若遇到 Free memory on device is less than desired GPU memory utilization 错误，请逐步下调 --gpu-memory-utilization（如 0.15 → 0.08）。
Eager 模式 Fallback 若在某些批次下出现 Graph 捕获异常，可追加 --enforce-eager 隔离问题，确认是否为算子本身错误后再决定是否关闭图模式。
权重来源 本验证所用权重与配置文件仅从 ModelScope 下载，未使用 HuggingFace 或 GitHub 来源。