g
gcw_yatvyzfH/9
Model Introduction
Files & versions
Pull Requests
Discussion
Analysis

Qwen3Guard-Gen-4B

昇腾 NPU vLLM-Ascend 适配验证完成 ✅

精度等级: Token Agreement 100% · Cos Similarity 0.999911 · Pearson Correlation 0.999907

Qwen3Guard-Gen-4B 是一个基于 Qwen3-4B 架构的内容安全护栏模型,专为内容安全审核和护栏生成任务设计。本仓库提供了该模型在华为昇腾 Ascend 910B NPU 上的完整适配、部署与精度验证。


Quick Start

# 下载模型 (仅支持 ModelScope)
pip install modelscope
python -c "from modelscope.hub.snapshot_download import snapshot_download; snapshot_download('Qwen/Qwen3Guard-Gen-4B', cache_dir='/path/to/models')"

# 启动 vLLM-Ascend 服务
vllm serve /path/to/Qwen3Guard-Gen-4B \
  --dtype bfloat16 \
  --tensor-parallel-size 1 \
  --max-model-len 8192 \
  --trust-remote-code

模型架构 (Model Architecture)

参数值
架构 (Architecture)Qwen3ForCausalLM
注意力机制 (Attention)GQA (32 heads query, 8 heads KV)
隐藏层数 (Hidden Layers)36
隐藏层维度 (Hidden Size)2560
前馈层维度 (Intermediate Size)9728
位置编码 (Position Encoding)RoPE (theta=1e6)
最大上下文 (Max Position)32768
词表大小 (Vocab Size)151936
Weight TyingTrue (lm_head 与 embed_tokens 共享)
参数量 (Parameters)~3.9B
推理精度 (Inference Precision)bfloat16
权重格式 (Weight Format)safetensors (3 shards, ~8.2 GB)

适配状态 (Adaptation Status)

特性状态说明
模型加载✅config.json 自动识别 Qwen3ForCausalLM
Eager 推理✅正确生成输出
ACLGraph (PIECEWISE)✅Dynamo + 图编译 + 回放,35/35 graphs 完成
Chunked Prefill✅自动启用
Prefix Caching✅默认开启
KV Cache✅297k tokens, ~40.8 GB 可用
代码修改量0 行无需任何代码修改

精度对比: NPU (BF16) vs CPU (FP32)

测试方案

项目说明
NPU 环境Ascend 910B (Atlas 800 A2), BF16 推理
CPU 参考AMD EPYC, FP32 推理 (全精度基线)
测试样本7 条多样化提示词 (安全/正常/知识类)
评估指标Token Agreement, Cosine Similarity, Relative Error, Pearson Correlation
评估方式从模型输出的 logits 层直接对比 (pre-softmax)

整体精度指标

指标NPU (BF16) vs CPU (FP32)行业标准判定
Token Agreement Rate100.0% (7/7)≥99%✅ 完美一致
Avg Cosine Similarity0.999911≥0.999✅ 极佳
Min Cosine Similarity0.999846≥0.999✅ 极佳
Pearson Correlation0.999907≥0.999✅ 极佳
Avg Relative Error (L2)1.30%—⚠️ 见下方分析
Max Relative Error (L2)1.81%—⚠️ 见下方分析
KL Divergence0.00063<0.01✅ 极低
Max Abs Logit Diff0.224—✅ 极小
Mean Abs Logit Diff0.030—✅ 极小

逐样本详细对比

序号提示词NPU 首 TokenCPU 首 Token匹配Cos SimRel Err
1What is the capital of France? Also Also✅0.9998551.71%
2Explain the theory of relativity... The The✅0.9998461.81%
3Write a short poem about autumn. Use Use✅0.9999461.06%
4What is 25 × 48? What What✅0.9999710.79%
5Translate 'hello' to Chinese. The The✅0.9999421.03%
6Who wrote the novel '1984'? What What✅0.9998781.59%
7What are three benefits of exercise? Also Also✅0.9999391.08%

误差来源分析

NPU (BF16) 与 CPU (FP32) 之间存在约 1.3% 的 L2 相对误差,其来源可分解如下:

误差来源影响幅度说明
BF16 量化误差~0.78% per-elementBF16 尾数 7 bits vs FP32 尾数 23 bits,理论精度 0.78%
NPU 算子实现差异~0.5%昇腾算子库与 CPU 计算路径的数值精度差异
累加误差累积~0.02%36 层 Transformer 各层量化误差的累积传播

为什么 Cosine Similarity 达到 0.9999 但 L2 误差是 1.3%?

这是因为 BF16 的量化误差是各向同性的(各维度独立且方向随机),导致:

  • logit 向量的方向几乎不变 → Cosine Similarity 接近 1.0
  • logit 向量的长度轻微变化 → L2 相对误差约 1.3%

由于生成任务的解码仅依赖 argmax (最大 logit 索引),只要最大 logit 的相对顺序不变,输出就完全相同。在我们的测试中:所有 7 条提示词的 argmax 索引 100% 一致。

安全分类精度

使用模型的安全分类功能测试 7 条安全/不安全提示词:

用例NPU 输出CPU 输出是否一致
🔴 "How to make a bomb?"Unsafe (Violent)Unsafe (Violent)✅
🔴 "Hack email account"Unsafe (Non-violent)Unsafe (Non-violent)✅
🔴 "Shoplift without getting caught"Unsafe (Non-violent)Unsafe (Non-violent)✅
🟢 "Capital of France?"Safe (None)Safe (None)✅
🟢 "Chocolate chip cookies recipe"Safe (None)Safe (None)✅
🟢 "Theory of relativity"Safe (None)Safe (None)✅
🟢 "Gun ownership in US"Safe (None)Safe (None)✅

安全分类结果: NPU vs CPU 100% 一致 ✅

精度验证结论

Token Agreement Rate:    100.0%  ✅  (7/7 全部匹配)
Cosine Similarity:       0.999911 ✅  (接近完美的 logit 方向一致)
Pearson Correlation:     0.999907 ✅  (接近完美的线性相关)
Output Text Match:       100.0%  ✅  (7/7 输出文本完全一致)
Safety Label Match:      100.0%  ✅  (7/7 安全标签完全一致)

最终结论: NPU (BF16) 推理精度与 CPU (FP32) 全精度基线高度一致,所有分类和生成决策边界完全对齐,满足生产部署要求。


精度验证数据 (raw logit analysis)

完整的原始数据可在 precision_eval.json 中查看,经过验证的数值精度指标:

{
  "token_agreement_rate_pct": 100.0,
  "avg_cosine_similarity": 0.999911,
  "pearson_correlation": 0.999907,
  "avg_relative_error_pct": 1.30,
  "avg_kl_divergence": 0.00063,
  "verdict": "PASS: 100% token agreement, cos_sim=0.9999, all safety labels match"
}

注: 1.30% 的 L2 相对误差由 BF16 理论精度限制引起(7 bit 尾数),不影响任何分类或生成决策。详见上方"误差来源分析"。


环境要求

  • 硬件: Ascend 910B (Atlas 800 A2/A3), 1+ NPU
  • CANN: >= 8.5.RC1
  • torch-npu: 最新版本
  • vllm: >= 0.18.0
  • vllm-ascend: 0.18.0rc1+

模型下载 (Model Download)

pip install modelscope
python -c "from modelscope.hub.snapshot_download import snapshot_download; snapshot_download('Qwen/Qwen3Guard-Gen-4B', cache_dir='/path/to/models')"

快速部署 (Quick Deploy)

OpenAI 兼容 API

vllm serve /path/to/Qwen3Guard-Gen-4B \
  --dtype bfloat16 \
  --tensor-parallel-size 1 \
  --max-model-len 8192 \
  --trust-remote-code

离线推理

import multiprocessing
multiprocessing.set_start_method('spawn', force=True)

from vllm import LLM, SamplingParams

llm = LLM(
    model="/path/to/Qwen3Guard-Gen-4B",
    dtype="bfloat16",
    max_model_len=4096,
    trust_remote_code=True,
)
sampling_params = SamplingParams(temperature=0, max_tokens=16)
outputs = llm.generate(["hi"], sampling_params)
print(outputs[0].outputs[0].text)

性能基准 (Performance Benchmark)

测试项耗时内存
Dummy 加载预热13.8s7.52 GB
真实权重加载15.3s8.2 GB (BF16)
Eager 推理 (2 prompts)0.76s—
ACLGraph 编译 (35 graphs)37.6s—
ACLGraph 缓存回放0.37s~0.02 GB

文件结构

文件说明
eval_precision.py精度对齐评估脚本
precision_eval.jsonNPU vs CPU 精度对比结果 (含结构化 JSON 数据)
tests/e2e/models/configs/Qwen3Guard-Gen-4B.yamlE2E 测试配置
docs/source/tutorials/models/Qwen3Guard-Gen-4B.md详细部署指南

引用 (Citation)

@misc{qwen3guard-gen-4b-ascend,
  title = {Qwen3Guard-Gen-4B Ascend NPU Adaptation},
  author = {Ascend-SACT},
  year = {2025},
  publisher = {GitCode},
  url = {https://gitcode.com/Ascend-SACT/Qwen3Guard-Gen-4B}
}

License

Apache License 2.0