granite-4.1-3b on vLLM-Ascend 0.18.0rc1

1. 简介

本文档记录 granite-4.1-3b 在 vLLM-Ascend 0.18.0rc1 环境的快速部署与验证结果。

granite-4.1-3b 是 IBM Granite 发布的 3.4B 参数文本生成模型，基于 GraniteForCausalLM 架构，支持 128K 上下文长度。该模型采用独特的缩放机制（attention_multiplier、embedding_multiplier、logits_scaling、residual_multiplier），在推理和代码任务上表现优异。

相关获取地址：

• HuggingFace 权重：https://huggingface.co/ibm-granite/granite-4.1-3b
• ModelScope 权重：https://modelscope.cn/models/ibm-granite/granite-4.1-3b
• Docker Image（vLLM-Ascend 0.18.0rc1）：quay.io/ascend/vllm-ascend:v0.18.0rc1

参考文档：

• https://docs.vllm.ai/projects/ascend/zh-cn/v0.18.0/tutorials/models/Qwen3-Dense.html
• https://docs.vllm.ai/projects/ascend/zh-cn/v0.18.0/user_guide/support_matrix/supported_models.html

2. 验证环境

• NPU：2 逻辑卡（Ascend 910）
• 模型路径：/opt/atomgit/weights/granite-4.1-3b
• 服务端口：8000

3. 服务启动

启动前可先检查端口：

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

已验证通过的启动命令：

export ASCEND_RT_VISIBLE_DEVICES=0,1
export VLLM_USE_MODELSCOPE=true
export PYTORCH_NPU_ALLOC_CONF=expandable_segments:True
export HCCL_BUFFSIZE=512
export OMP_PROC_BIND=false
export OMP_NUM_THREADS=1
export TASK_QUEUE_ENABLE=1

vllm serve /opt/atomgit/weights/granite-4.1-3b \
  --host 0.0.0.0 \
  --port 8000 \
  --tensor-parallel-size 1 \
  --seed 1024 \
  --served-model-name granite-4.1-3b \
  --max-num-seqs 32 \
  --max-model-len 8192 \
  --trust-remote-code \
  --gpu-memory-utilization 0.85 \
  --no-enable-prefix-caching \
  --compilation-config '{"cudagraph_mode":"FULL_DECODE_ONLY"}'

关键参数说明：

• --trust-remote-code：建议携带，兼容 Granite 自定义配置
• --tensor-parallel-size 1：3.4B 模型单卡可运行（约占用 7GB HBM）
• --max-model-len 8192：默认上下文长度，可按需调整（最大 131072）
• --gpu-memory-utilization 0.85：HBM 利用率
• --compilation-config FULL_DECODE_ONLY：ACL Graph 加速编译

4. Smoke 验证

基础检查：

curl -sf http://127.0.0.1:8000/v1/models
curl -sf http://127.0.0.1:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "granite-4.1-3b",
    "messages": [
      {"role": "user", "content": "What is the capital of France?"}
    ],
    "temperature": 0,
    "max_tokens": 128
  }'

验证结果：

• /v1/models 返回 200
• /v1/chat/completions 返回 200
• 文本生成正常，回答准确："The capital of France is Paris."

5. 性能参考

测试条件：128 input / 128 output，API 级基准测试。

注：3.4B 模型在单卡 Ascend 910 上运行，延迟受模型规模影响。实际性能受输入长度、并发度及编译参数影响，以上数据仅供参考。

压测命令：

python scripts/bench_perf.py \
  --url http://localhost:8000/v1/chat/completions \
  --model granite-4.1-3b \
  --max-tokens 128 \
  --latency-iters 5 \
  --throughput-requests 10 \
  --throughput-concurrency 2

6. 精度评测

6.1 验证方法

采用 NPU 与 CPU 基线对比的方式，对模型输出的 Logits 和 Hidden States 进行精度评估。验证指标包括：

• max_abs_error: 最大绝对误差
• mean_abs_error: 平均绝对误差
• relative_error: 相对误差
• cosine_similarity: 余弦相似度
• threshold: 通过阈值

注：Granite 4.x 采用独特的缩放机制（attention_multiplier=0.015625, embedding_multiplier=12.0, logits_scaling=10.0, residual_multiplier=0.22），会放大 bfloat16 精度差异，Hidden States 阈值设为 2.0。

6.2 验证结果

结论：NPU 与 CPU 基线高度一致，cosine_similarity > 0.9998，验证通过。

说明：

• 绝对误差满足通过标准（max_abs_error < 2.0）。
• 余弦相似度 > 0.9998，方向一致性极好。
• 相对误差受 bfloat16 近零值和 Granite 缩放机制影响偏大，仅作参考。

运行精度评测：

python scripts/eval_accuracy.py \
  --model /opt/atomgit/weights/granite-4.1-3b \
  --output accuracy_result.json

7. 推理脚本

项目提供 inference.py 一键推理脚本，支持本地 LLM 与 API 服务两种模式：

# 本地 LLM 模式（直接调用 vllm.LLM）
python inference.py --mode local \
  --model /opt/atomgit/weights/granite-4.1-3b \
  --prompt "Explain quantum computing in simple terms."

# API 服务模式（调用已部署的 vLLM 服务）
python inference.py --mode api \
  --url http://localhost:8000/v1/chat/completions \
  --model-name granite-4.1-3b \
  --prompt "Hello, how are you?"

8. 注意事项

1. vLLM 原生支持

   • GraniteForCausalLM 已在 vLLM 0.18.0 中注册，无需额外适配代码
   • 建议携带 --trust-remote-code，以兼容潜在自定义配置

2. 模型特点

   • 3.4B 参数，BF16 精度下约占用 7 GB HBM
   • 支持 128K 上下文（max_position_embeddings=131072）
   • 采用 GQA（Grouped Query Attention）：40 heads / 8 KV heads
   • 独特缩放机制：attention_multiplier、embedding_multiplier、logits_scaling、residual_multiplier

3. 显存占用

   • 3.4B 参数模型 BF16 精度下约占用 7 GB HBM
   • 单卡 64 GB Atlas 910 可轻松承载

4. Chat 模板

   • 使用 <|start_of_role|>system<|end_of_role|> 等角色标记
   • 支持 tool calling 和 document-based QA

9. 参考信息