BAAI/bge-small-zh-v1.5 昇腾 NPU 适配

1. 模型简介

项	值
模型名称	BAAI/bge-small-zh-v1.5
原始链接	https://huggingface.co/BAAI/bge-small-zh-v1.5
任务	自然语言处理（中文文本嵌入 / feature extraction）
架构	BERT（4 层，hidden 512，8 头，vocab 21128）
参数量	24.0M（float32，model.safetensors 95.8MB）
输出	512 维归一化嵌入向量

2. 环境依赖

软件	版本
Python	3.11
CANN	8.5.1
torch	2.9.0
torch_npu	2.9.0.post1+gitee7ba04
transformers	4.57.6
numpy / safetensors	见 requirements.txt

安装命令：

pip install -r requirements.txt

说明：标准 transformers BERT 架构，无需 remote code；AutoModel.from_pretrained 直接加载。

3. 推理步骤

环境准备：

npu-smi info          # 查看 NPU 设备

运行推理（生成文本嵌入）：

python3 inference.py --device npu --text "今天天气怎么样？"

参数说明：

参数	说明	默认值
--device	npu（Ascend 910）或 cpu（基准/回退）	npu
--text	待嵌入的中文文本	今天天气怎么样？
--model-dir	权重目录	./weights

首次推理含算子图编译（约几秒），评测以第二次为准。

4. 测试样例及输出

样例：中文文本嵌入（NPU）

输入：今天天气怎么样？
输出：512 维归一化向量
  head = [-0.0065, -0.0088, -0.0151, 0.0576, 0.0114, -0.0344, 0.0594, 0.0735, ...]
  norm = 1.000000

时延：0.170 s（单句，warm-up 后）

5. Agent 适配截图

截图	内容
assets/agent_workflow.png	Model-Agent 适配工作流（7 步）
assets/npu_device_call.png	NPU 设备/环境/版本信息
assets/model_result.png	精度对比与性能结果

6. 精度对比（CPU baseline vs NPU）

验证方式：同一中文文本，CPU 与 NPU 各推理一次，取 [CLS] 归一化嵌入向量对比。

指标	数值	阈值	状态
cosine_similarity	0.999999	> 0.999	PASS
L2_relative_error	0.001533	< 1%	PASS

结论：PASS —— CPU 与 NPU 嵌入向量余弦相似度 0.999999，L2 相对误差 0.15%，满足精度底线。

复现命令：

python3 verify.py --device cpu   # 生成 assets/emb_cpu.npz
python3 verify.py --device npu   # 生成 assets/emb_npu.npz
python3 verify.py --compare      # 输出对比报告

7. 注意事项与目录结构

• 模型为 float32 标准 BERT，NPU 直接加载即可，无特殊适配。
• 嵌入向量按 bge 惯例做了 L2 归一化（检索/相似度直接用）。

BAAI/bge-small-zh-v1.5/
├── inference.py          # NPU 推理脚本（--device npu/cpu）
├── verify.py             # 精度验证脚本（CPU vs NPU + --compare）
├── generate_assets.py    # 三张交付截图 PIL 渲染
├── readme.md
├── requirements.txt
├── assets/               # agent_workflow / npu_device_call / model_result 截图 + emb npz
└── weights/              # 模型权重（.gitignore 排除，不推仓库）