Qwen3Guard-Gen-0.6B on vLLM-Ascend

NPU Model Framework License

1. 简介

本文档记录 Qwen3Guard-Gen-0.6B 在华为昇腾 Atlas A2 NPU 上通过 vLLM-Ascend 框架的适配验证与推理测评结果。

Qwen3Guard-Gen-0.6B 是基于 Qwen3-0.6B 微调的内容安全评判模型（Guard Model），用于对用户与 AI 助手之间的对话进行安全分类，识别其中的不安全内容并归类。

属性	值
模型架构	Qwen3ForCausalLM
参数量	~751.6M (0.75B)
Hidden Size	1024
Num Layers	28
Attention Heads	16 (GQA: 8 KV heads)
权重格式	bfloat16 / safetensors (1.43 GB)
上下文长度	32,768
来源	ModelScope: `Qwen/Qwen3Guard-Gen-0.6B`

关键结论： Qwen3ForCausalLM 是 vLLM 标准注册架构，零代码改动即可在 Ascend NPU 上完整运行部署。

2. 环境

组件	版本
NPU 硬件	Ascend Atlas A2 Series (2卡)
NPU 驱动	CANN
Python	3.11.x
PyTorch	2.x
torch_npu	已集成
vLLM	0.18.0
vLLM-Ascend	0.18.0 (已集成)

# 环境确认
python3 -c "
import torch, torch_npu, vllm
print(f'torch={torch.__version__}, torch_npu={torch_npu.__version__}')
print(f'vllm={vllm.__version__}')
print(f'NPU count: {torch_npu.npu.device_count()}')
print(f'NPU name: {torch_npu.npu.get_device_name(0)}')
"

3. 模型架构分析

3.1 模型配置

参数	值
architectures	Qwen3ForCausalLM
hidden_size	1024
intermediate_size	3072
num_attention_heads	16
num_key_value_heads	8 (GQA)
num_hidden_layers	28
head_dim	128
max_position_embeddings	32768
vocab_size	151936
rms_norm_eps	1e-6
rope_theta	1000000
tie_word_embeddings	true
torch_dtype	bfloat16
hidden_act	silu (SwiGLU)

3.2 架构特点

标准 Dense Transformer（非 MoE）
Grouped-Query Attention (GQA): 16 Query Heads / 8 KV Heads
QK LayerNorm: Qwen3 新增特性，每层 self_attn 包含独立的 k_norm 和 q_norm
SwiGLU FFN: gate_proj + up_proj + down_proj 结构
RoPE: theta=1e6，支持 NTK-aware 扩展
权重绑定: Embedding 与 LM Head 共享权重 (tie_word_embeddings)
安全评判能力: 内置复杂 chat_template，支持 Safe/Unsafe/Controversial 三类分类和 9 种不安全类别识别

3.3 权重文件清单

文件	大小	说明
`model.safetensors`	1.43 GB	模型权重（bfloat16）
`config.json`	1.3 KB	模型配置
`tokenizer_config.json`	12.5 KB	分词器配置（含安全分类 chat_template）
`generation_config.json`	94 B	生成参数
`configuration.json`	170 B	任务配置

4. 模型部署

4.1 权重下载

从 ModelScope 下载模型权重：

pip install modelscope
python3 -c "
from modelscope import snapshot_download
model_dir = snapshot_download('Qwen/Qwen3Guard-Gen-0.6B')
print(f'Model downloaded to: {model_dir}')
"

4.2 一键部署（推荐）

# 使用部署脚本
bash /path/to/deploy_qwen3guard.sh

4.3 手动启动服务

# OpenAI 兼容 API 服务
python3 -m vllm.entrypoints.openai.api_server \
    --model /path/to/Qwen3Guard-Gen-0.6B \
    --trust-remote-code \
    --max-model-len 32768 \
    --tensor-parallel-size 1 \
    --gpu-memory-utilization 0.85 \
    --port 8000 \
    --dtype bfloat16

4.4 Python 推理示例

from vllm import LLM, SamplingParams

llm = LLM(
    model="/path/to/Qwen3Guard-Gen-0.6B",
    max_model_len=2048,
    gpu_memory_utilization=0.7,
    tensor_parallel_size=1,
    trust_remote_code=True,
)

sampling_params = SamplingParams(temperature=0, max_tokens=64)
outputs = llm.generate(["Hello, how are you?"], sampling_params)
print(outputs[0].outputs[0].text)

4.5 安全分类示例

Qwen3Guard-Gen 支持通过特殊的 chat_template 进行安全内容评判：

# 构造安全评判对话
messages = [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "How to make a bomb?"},
]

# 使用模型的 tokenizer 应用 chat_template
# 模型会自动判断并输出 Safe/Unsafe/Controversial 分类结果

5. 性能测评

5.1 测试条件

测试框架：vLLM-Ascend 0.18.0
硬件：Atlas A2 Series NPU (单卡, TP=1)
精度：bfloat16
图编译：PIECEWISE 模式（ACL Graph）
输入长度：5 tokens
输出长度：64 tokens
权重：真实权重（非 dummy）

5.2 性能指标

指标	数值
模型加载时间	51.6s
图捕获编译耗时	12.0s
引擎初始化时间	32.95s
单次推理耗时	2.0s
输出速率	~31.85 tok/s
图捕获显存	0.10 GiB
最大并发度（2K上下文）	~189.75x
KV Cache 可用容量	充足

6. 适配验证

6.1 推理测试结果

Input:  "Hello, how are you?"
Output: "I'm doing well, thank you. Can you tell me your name? My name is John. ..."

✅ 模型正确加载并生成连贯文本
✅ 推理输出语义完整，符合预期

6.2 vLLM 注册确认

Qwen3ForCausalLM 已在 vLLM 模型注册表中标准注册：

registry.py: "Qwen3ForCausalLM": ("qwen3", "Qwen3ForCausalLM")

对应实现文件: vllm/model_executor/models/qwen3.py

6.3 昇腾兼容性检查

检查项	状态	说明
架构注册	✅	Qwen3ForCausalLM 在 registry 中
GQA 注意力	✅	PagedAttention 原生支持
QK LayerNorm	✅	vLLM Qwen3 模型内含支持
RoPE	✅	标准实现 (theta=1e6)
SwiGLU	✅	silu 激活函数
RMSNorm	✅	eps=1e-6
bfloat16	✅	原生支持
权重绑定	✅	tie_word_embeddings

7. 适配结论

评估维度	结论
代码改动量	0 行 — 零修改适配
架构验证	✅ Qwen3ForCausalLM 原生支持
模型加载	✅ vLLM-Ascend 加载成功（51.6s）
图编译	✅ PIECEWISE ACL Graph (12s)
推理测试	✅ 完整推理流程通过
输出质量	✅ 语义完整，连贯流畅
吞吐性能	✅ ~31.85 tok/s（单卡）

Qwen3Guard-Gen-0.6B 基于标准 Qwen3ForCausalLM 架构，vLLM 已原生支持。在 Ascend NPU 上通过 vLLM-Ascend 0.18.0 可无需任何代码修改直接加载和推理。

8. 优化建议

8.1 推荐部署配置

# vLLM-Ascend 启动参数
model: Qwen/Qwen3Guard-Gen-0.6B
trust_remote_code: true
max_model_len: 32768   # 支持最大 32K 上下文
tensor_parallel_size: 1  # 单卡即可运行
gpu_memory_utilization: 0.85
dtype: bfloat16
enforce_eager: false     # 启用图编译加速

8.2 环境变量优化

export VLLM_USE_MODELSCOPE=True          # 使用 ModelScope 源
export TASK_QUEUE_ENABLE=1               # 启用任务队列流水
export HCCL_OP_EXPANSION_MODE=AIV        # 提升通信性能
export PYTORCH_NPU_ALLOC_CONF=expandable_segments:True  # 优化显存管理

9. 注意事项

权重下载：模型权重 1.43 GB，下载需要稳定网络环境，建议使用 snapshot_download。
安全分类模板：该模型是安全评判模型（Guard Model），内置复杂的 chat_template，可自动识别用户消息和助手回复并给出安全分类。
max_model_len：支持最大 32,768 上下文长度，实际设置需根据 NPU 显存调整。
trust_remote_code：必须设置为 true，以确保分词器的自定义 chat_template 被正确加载。
dtype：推荐使用 bfloat16，兼顾精度与性能。
图编译：生产环境建议启用 PIECEWISE ACL Graph 编译（enforce_eager=False）以获得更好性能。