XiYanSQL-QwenCoder-3B-2502 on Ascend NPU

#+NPU

1. 简介

本文档记录 XiYanSQL-QwenCoder-3B-2502 在华为昇腾 NPU（Ascend 910B）上的原生 PyTorch 适配、精度验证与性能评测结果。

XiYanSQL-QwenCoder-3B-2502 是 XGenerationLab 开源的 Text-to-SQL 专用模型，基于 Qwen2ForCausalLM 架构微调，在多个 SQL 生成 benchmark 上表现优异。本验证证明该模型可在昇腾 NPU 上通过 torch_npu 直接加载与推理，无需修改模型权重或结构。

相关获取地址：

• 权重下载地址（ModelScope）：https://modelscope.cn/models/XGenerationLab/XiYanSQL-QwenCoder-3B-2502
• 权重下载地址（HuggingFace）：https://huggingface.co/XGenerationLab/XiYanSQL-QwenCoder-3B-2502

参考文档：

• https://www.hiascend.com/document/detail/zh/Pytorch/600/ptmoddevg/trainingmigrguide/performance_tuning_0027.html
• https://gitee.com/ascend/pytorch

2. 验证环境

• NPU：1 x Ascend 910B4（32 GB HBM）
• 模型路径：./model_cache/XGenerationLab/XiYanSQL-QwenCoder-3B-2502

3. 快速开始

3.1 安装依赖

pip install torch==2.9.0 transformers>=4.42.0 torch-npu

注意：torch-npu 需与当前 CANN 版本匹配，请参考昇腾官方安装指南。

3.2 推理示例

python inference.py \
  --model_path ./model_cache/XGenerationLab/XiYanSQL-QwenCoder-3B-2502 \
  --device npu \
  --dtype bfloat16 \
  --prompt "-- 查询所有年龄大于30岁的用户\nSELECT" \
  --max_new_tokens 128

示例输出：

[INFO] Using device: npu
[INFO] Generated:  * FROM users WHERE age > 30;

3.3 设备无关性

inference.py 内置自动设备选择逻辑（npu > cuda > cpu），并可通过 --device 显式指定：

# CPU 推理
python inference.py --model_path <path> --device cpu --dtype float32

# CUDA GPU 推理
python inference.py --model_path <path> --device cuda --dtype bfloat16

# NPU 推理（默认自动选择）
python inference.py --model_path <path> --device npu --dtype bfloat16

4. 精度评测

使用 accuracy_run.py 对 NPU 推理结果与 CPU 基线进行逐 logits 对比。

4.1 评测方法

• 基线：CPU float32 前向 logits
• 目标：NPU float32 前向 logits
• 指标：Mean Relative Error、Top-1 Token Accuracy、Cosine Similarity
• 阈值：Mean Relative Error < 1%，Top-1 Token Accuracy ≥ 99%

4.2 评测结果

结论：NPU 推理精度满足 相对误差 < 1% 的严格要求，生成结果与 CPU 基线完全一致。

运行评测：

python accuracy_run.py \
  --model_path ./model_cache/XGenerationLab/XiYanSQL-QwenCoder-3B-2502 \
  --device npu \
  --dtype float32 \
  --max_new_tokens 32 \
  --output run_log.txt \
  --json accuracy_result.json

5. 性能参考

测试条件：单卡 Ascend 910B4，max_new_tokens=128，do_sample=False，预热 2 轮，正式测试 5 轮取平均。

5.1 bfloat16（推荐生产配置）

5.2 float32（精度验证配置）

说明：本模型配置为 bfloat16，推荐生产环境使用 bfloat16 以获得更优的吞吐与显存占用。

运行性能测试：

python inference.py \
  --model_path ./model_cache/XGenerationLab/XiYanSQL-QwenCoder-3B-2502 \
  --device npu \
  --dtype bfloat16 \
  --benchmark \
  --max_new_tokens 128

6. 项目结构

.
├── inference.py          # NPU 适配推理脚本（支持 npu/cuda/cpu 自动选择）
├── accuracy_run.py       # 精度与性能评测脚本
├── run_log.txt           # 评测运行日志（含 PASS/FAIL 结论）
├── accuracy_result.json  # 结构化评测结果
├── readme.md             # 本文档
└── model_cache/
    └── XGenerationLab/
        └── XiYanSQL-QwenCoder-3B-2502/

7. 注意事项

1. 设备选择：脚本默认优先选择 NPU；若 NPU 不可用，自动回退到 CUDA 或 CPU。可通过 --device 强制指定。
2. dtype 建议：模型原生 bfloat16，在 NPU 上可直接使用；如需严格精度对齐验证，可使用 float32。
3. 内存占用：3B 模型在 bfloat16 下约占用 6~7 GB HBM，请确保 NPU 显存充足。
4. 温度与采样：Text-to-SQL 任务建议设置较低温度（如 0.1）以保持生成 SQL 的确定性。

8. 免责声明

本验证基于公开模型与开源工具链完成，仅供社区参考。实际部署效果受 CANN 版本、驱动版本、硬件批次等因素影响，请以实际环境测试为准。