BERT-ONNX-CPU 方案

BERT 分类模型导出为 ONNX 后，直接用 ONNX Runtime 在 CPU 上推理，不需要转 RKNN，不需要 GPU/NPU。

BERT 分类模型 ONNX 转 RKNN 全流程实录

一句话总结

训练好的 BERT 模型导出为 ONNX 后，直接用 ONNX Runtime CPU 推理即可，不需要转 RKNN。 RKNN NPU 无法正确处理 BERT embedding 层（整数 token ID 查表），经过 6 轮调试后放弃 NPU 方案。最终在香橙派 ARM CPU 上实现：置信度 92.26%，推理耗时 111ms，已集成到 HXXedge v1.0.1。

整体流程概览

Colab 训练 (bert-base-chinese)
    ↓ HF 格式（PyTorch）
Colab 导出 ONNX
    ↓ 检查 IsNaN（仅报告，不修改）→ ONNX Runtime 验证 → 记录基准 logits
    ↓ ✅ 验证通过后才下载
下载 ONNX + tokenizer + categories
    ↓
龘思 Docker 转 RKNN（rknn-toolkit2 == 2.3.2）
    ↓ 无 mean/std 预处理、optimization_level=0、disable_rules
    ↓ .rknn 文件
上传香橙派
    ↓
rknn-toolkit-lite2 推理验证 → 对比 logits 是否接近基准

第 1 步：Colab 训练（已完成）

• 模型：bert-base-chinese（110M 参数）
• 任务：17 类文本分类（海小星预设知识问答）
• 训练数据：680 条训练 + 170 条验证（DeepSeek 生成问法变体）
• 训练结果：97.06% 验证准确率，推理测试 6/6 正确
• 输出：HF 格式模型保存在 Colab output/ 目录

详见 colab_train.py

第 2 步：Colab 导出 ONNX（关键步骤）

为什么要强调"在 Colab 上先验证"

教训：ONNX 导出后如果不验证就下载，到了 Docker / 香橙派上才发现模型有问题，每次排查都要走完整链路（Colab → 下载 → Docker 转换 → 上传香橙派 → 测试），极其耗时。

正确做法：在 Colab 中完成以下全部验证，并记录原始 logits 作为基准，确认无误后再下载：

1. ✅ 导出 ONNX（不做任何图修改）
2. ✅ ONNX Runtime 推理验证（结果正确）
3. ✅ 记录原始 logits 值和置信度（用于与 RKNN 对比）

IsNaN 算子问题（核心坑点与策略反转）

现象：PyTorch 导出 BERT 时，ONNX 图中包含 12 个 IsNaN 算子。RKNN 加载后输出警告 Unsupport CPU op: IsNaN in this librknnrt.so。

根因：PyTorch 2.x 的 ONNX 导出器对 BERT 的 LayerNormalization 分解时，额外生成了 NaN 安全检查：

计算结果 x → IsNaN(x) → Where(is_nan, default_val, x) → 最终输出

RKNN 运行时（librknnrt 2.3.2）不支持 IsNaN 算子。

改 opset_version 有用吗？

结论：改 opset_version 无效，IsNaN 是 PyTorch 导出器固定生成的。

❌ 失败方案：IsNaN + Where 替换为 Identity

曾尝试的方案：将 Where(IsNaN(x), default, x) 替换为 Identity(x)，跳过 NaN 检查。

为什么失败：替换严重破坏了模型精度！

诊断过程： 1. 全零输入 vs 正常输入 → 输出不同 ✅ 说明模型在读数据 2. 不同问题 → 输出不同 ✅ 但 logits 太平坦 3. 对比 Colab 基准 logits → 差距巨大，说明 IsNaN→Identity 替换破坏了计算图

根因分析：IsNaN+Where 虽然理论上是"防御性检查"（正常输入不会产生 NaN），但替换后 onnxsim 简化会进一步重组图结构，导致计算精度严重退化。

✅ 最终方案：不修改 ONNX 图

策略：保留 IsNaN 算子，不做任何替换，不做 onnxsim 简化
RKNN 转换时：IsNaN 在 CPU 上执行（有警告但不影响结果）

关键认识：RKNN 的 "Unsupport CPU op: IsNaN" 是警告，不是错误。RKNN 运行时可以在 CPU 上执行这些不支持的算子，只是速度稍慢。模型精度不受影响。

Colab 验证通过标准

运行导出脚本后，确认以下全部通过：

⚠️ 检测到 12 个 IsNaN 算子（不做替换）
✅ ONNX 模型结构正确
✅ ONNX 推理验证通过（预测结果正确）
📊 softmax 置信度: 92.26%（足够尖锐）

重要：必须记录原始 logits 值，后续与 RKNN 推理结果对比。如果 RKNN logits 与 ONNX 基准接近，说明转换成功；如果差距大，说明转换有问题。

完整脚本：export_onnx.py

第 3 步：龘思 Docker 转 RKNN

环境准备

conda activate rkllm
cd /Daas/data/models/rkllm/BERT

目录结构

BERT/
├── export_rknn.py              # 转换脚本
├── bert_classifier_inference.py # 推理脚本（副本）
├── output_onnx/                # ONNX 模型（从 Colab 下载）
│   ├── model.onnx              # ~93 KB（图结构）
│   ├── model.onnx.data         # ~390 MB（权重数据）
│   ├── categories.json
│   ├── tokenizer.json
│   └── tokenizer_config.json
└── output_rknn/                # RKNN 输出
    ├── bert_classifier_w8a8_rk3588.rknn
    └── categories.json

转换配置要点

rknn.config(
    # ⚠️ BERT 文本模型不做均值/标准差预处理！
    # 整数 token ID 不能被归一化（否则破坏 embedding 查表）
    target_platform='rk3588',
    optimization_level=0,        # 0=基础（对 BERT 更安全）
    quantized_dtype='w8a8',
    disable_rules=['fuse_mul_into_sdpa'],  # 该规则与 BERT attention 不兼容
)

踩坑记录

完整脚本：export_rknn.py（Docker 端）

第 4 步：香橙派 NPU 推理

环境

• 设备：香橙派 Orange Pi 5 Plus（RK3588）
• 推理包：rknn-toolkit-lite2（轻量推理版，不是完整的 rknn-toolkit2）
• NPU 驱动：0.9.6

关键区别

部署文件

/home/orangepi/rkllm/rknn-toolkit2/2.3.2/bert_classifier/
├── bert_classifier_w8a8_rk3588.rknn   # RKNN 模型
├── categories.json                     # 类别定义
├── tokenizer.json                      # 分词器
├── tokenizer_config.json               # 分词器配置
└── bert_classifier_inference.py        # 推理脚本

推理脚本核心逻辑

from rknnlite.api import RKNNLite
from tokenizers import Tokenizer

# 加载
rknn = RKNNLite()
rknn.load_rknn('bert_classifier_w8a8_rk3588.rknn')
rknn.init_runtime()

# 推理
encoding = tokenizer.encode("你们老板是谁")
input_ids = np.array([encoding.ids], dtype=np.int32)
attention_mask = np.array([encoding.attention_mask], dtype=np.int32)
outputs = rknn.inference(inputs=[input_ids, attention_mask])

# 解析
pred_label = outputs[0][0].argmax()
answer = categories[str(pred_label)]['answer']

完整脚本：bert_classifier_inference.py

调试迭代记录（5 轮）

从 ONNX 导出到香橙派推理成功，经历了 5 轮完整的「Colab 导出 → 下载 → Docker 转换 → 上传香橙派 → 测试」循环。每轮至少 10-15 分钟，教训深刻。

关键诊断手段：

1. 基准 logits 对比法：在 Colab 用 ONNX Runtime 记录原始 logits，与 RKNN 推理结果对比
2. ONNX 基准：[5.28, -0.15, 0.89, ...]，置信度 92.26%

3. RKNN 退化：[-0.47, 0.90, -0.59, ...]，置信度 13.62%（≈随机）

4. 输入敏感性测试：传入全零输入 vs 正常输入 vs 不同输入，确认模型是否真正读取数据

5. 结果：三种输入产生不同输出 ✅ 说明模型在计算，但精度退化

6. 控制变量法：逐步排除 mean/std、optimization_level、IsNaN 替换、onnxsim 等因素

踩坑总结与经验

1. 一定要在 Colab 端完成 ONNX 验证 + 记录基准 logits

不要：导出 ONNX → 下载 → Docker 转 RKNN → 上传香橙派 → 发现不行 → 重来

要：导出 ONNX → ONNX Runtime 验证 → 记录原始 logits → 确认结果正确 → 再下载

每次"重来"的成本是：下载（几分钟）+ Docker 转换（几分钟）+ 上传 + 测试，至少 10-15 分钟。5 轮下来超过 2 小时。

基准 logits 对比法：如果 RKNN 推理结果异常，先对比 RKNN logits 与 Colab 基准 logits。差距大说明转换有问题，差距小说明是后处理问题。

2. IsNaN 必须替换，但绝不能做 onnxsim

PyTorch 2.x 的 ONNX 导出器对 BERT 固定会生成 12 个 IsNaN 算子，无论 opset 14/17/18 都一样。

RKNN 运行时不支持 IsNaN：不是警告后忽略，而是直接 Segfault。必须替换。

3. BERT 文本模型不需要 mean/std 预处理

RKNN 的 mean_values / std_values 是为图像模型设计的（像素值归一化）。BERT 的输入是整数 token ID，直接传入 embedding 层查表。设置 mean/std 可能导致 RKNN 对输入做浮点归一化，破坏 embedding 查表。

✅ 正确做法：不设置 mean_values 和 std_values。

4. rknn.config() 的 disable_rules

RKNN 编译器有图优化规则，某些规则与 BERT 的 attention 结构不兼容：

disable_rules=['fuse_mul_into_sdpa']  # 必须禁用，否则 build 时 TypeError

5. rknn-toolkit2 vs rknn-toolkit-lite2

文件索引

当前状态

• ✅ Colab 训练完成（97.06% 验证准确率）
• ✅ ONNX 导出成功，基准 logits 已记录（置信度 92.26%）
• ✅ 经过 6 轮调试，确认 RKNN NPU 无法正确处理 BERT embedding 层
• ✅ 最终方案：ONNX Runtime CPU 推理（不需要 RKNN，不需要 NPU）
• 香橙派 ARM CPU 推理，置信度 92.26%，耗时 111ms
• 精度与 Colab 基准完全一致
• ✅ 已集成到 HXXedge v1.0.1 纯 BERT 版
• 二级流水线：BERT 分类（~110ms）→ 置信度 ≥70% 返回答案 → 否则分级拒答
• 部署路径：/home/orangepi/hqxbotEdge/hd001e_HXXedge_1.0.1/
• ONNX 模型路径：/home/orangepi/rkllm/rknn-toolkit2/2.3.2/bert_classifier/output_onnx/

最终方案：ONNX Runtime CPU（不需要 RKNN）

为什么放弃 RKNN NPU

ONNX Runtime CPU 推理效果

跨平台验证

BERT-ONNX-CPU 方案在两个平台均验证通过：

本地 Windows 测试用例：

结论： ONNX Runtime CPU 方案跨平台通用，ARM/x86 都能跑，不需要 GPU/NPU。x86 PC 性能更强，响应更快。

BERT 语义分类 vs 关键词匹配

keywords 字段的作用

categories.json 中的 keywords 字段仅用于训练数据生成，推理时完全不用：

实例对比

用户问："你们电话是多少啊"（比 keywords 里的"电话"、"联系方式"都长）

多问法测试

核心优势

BERT vs 大模型（GPT/DeepSeek/Qwen）

在大模型火爆的当下，BERT 仍有独特优势：

BERT 仍有优势的场景

大模型不可替代的场景

最佳实践：组合使用

用户提问
  ↓
BERT 快速分类（100ms）
  ├─ 命中预设 → 直接返回（快、稳、免费）
  └─ 未命中 → 调用大模型（灵活、但慢/贵）

总结： BERT 是"专精快"，大模型是"广慢贵"。固定场景 BERT 更优，开放场景大模型更强，组合使用才是最佳方案。

HXXedge v1.0.1 集成架构

用户提问
  ↓
① BERT 分类（ONNX Runtime CPU，~110ms）
  ↓ 置信度 ≥ 70%？
  ├─ 是 → 返回对应答案
  └─ 否 → ② 分级拒答
           ├─ 含公司关键词 → 礼貌拒答（领域内）
           └─ 不含关键词 → 超范围拒答

部署文件

/home/orangepi/hqxbotEdge/hd001e_HXXedge_1.0.1/
├── app.py                    # Flask 入口（只加载 BERT）
├── config.py                 # 配置（BERT 模型路径等）
├── bert_classifier.py        # BERT 分类器模块（ONNX Runtime CPU）
├── routes/main.py            # 二级流水线
└── restart.sh                # 重启脚本

/home/orangepi/rkllm/rknn-toolkit2/2.3.2/bert_classifier/output_onnx/
├── model.onnx                # ~390MB（ONNX 模型）
├── model.onnx.data           # 权重数据
├── categories.json           # 17 类定义
├── tokenizer.json            # 分词器
└── tokenizer_config.json     # 分词器配置