Laya AX650 / NPU3 适配工程

本仓库提供 Laya 三套 typed-decision 模型在 AX650 / NPU3 上的完整转换流程，包括上游源码与权重准备、静态 ONNX 导出、任务相关量化校准、Pulsar2 编译和板端结果验证。

仓库只维护复现流程所需的脚本和说明。上游权重、ONNX、校准张量、Pulsar2 配置、AXModel、manifest 和推理结果均由脚本生成，不纳入 Git。可直接运行的 AXModel 与示例程序发布在 AXERA-TECH/Laya。

Laya 做什么

Laya 是非生成式的快速决策模型。输入由一份文本或 JSON state 和一个 typed question 组成，一次模型前向输出一个结构化判断：

问题类型	用途	输出解释
choice	分类或路由	候选标签概率及最高概率标签
score	紧急度、严重程度等有序评分	各等级概率及加权期望分数
noul	是/否命题	P(true) 与 P(false)

它适合客服分流、退款与流失判断、安全事件处置、RAG 片段过滤和 Agent trace 检查。模型不生成自然语言，也不提供生成式聊天接口。

三套 checkpoint

三套权重都支持 choice、score 和 noul，区别在语言能力和训练数据：

Variant	上游权重目录	编码器	参数量	推荐场景
english	仓库根目录	ModernBERT-large	421M	英文分类、客服与 guardrail
multilingual	multilingual/	mmBERT-base	322M	中文及其他多语言输入
typed-decisions	typed-decisions/	ModernBERT-large	421M	发票、安全事件、客服流程和 Agent trace

中文业务优先选择 multilingual；纯英文通用判断使用 english；输入属于四类专项流程时再选择 typed-decisions。

固定图接口

当前图规格固定为 batch=1、sequence=256、options=4，所有输入均为 S32：

名称	类型	Shape	说明
input_ids	S32	[1, 256]	tokenizer 输出
attention_mask	S32	[1, 256]	有效 token 标记
marker_pos	S32	[1, 4]	各候选项 [MASK] 的位置
marker_mask	S32	[1, 4]	有效候选项标记
qtype	S32	[1]	choice=0、score=1、noul=2

模型输出为 logits: FP32 [1,4] 和 act_logits: FP32 [1,2]。温度校准、标签映射、score 加权和 noul 概率解释在 CPU 侧完成。

仓库结构

laya.axera/
├── model_convert/
│   ├── prepare_upstream.py          # 下载固定版本的上游源码与三套权重
│   ├── export_onnx.py               # 导出并校验 ONNX
│   ├── generate_calibration_cases.py
│   ├── prepare_calibration.py       # 生成五组 Numpy 校准 tar
│   ├── generate_pulsar2_config.py
│   ├── build_ax650.sh
│   ├── record_build.py              # 生成本地构建 manifest
│   └── {english,multilingual,typed-decisions}/README.md
└── python/
    ├── generate_reference_results.py
    ├── ax_run_model_session.py
    ├── infer_axmodel.py
    └── README.md

环境准备

转换环境需要 Linux、Python 3.10 或更高版本、Git，以及可执行的 pulsar2。建议在虚拟环境中安装依赖：

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r model_convert/requirements.txt

下载经过验证的上游版本：

python model_convert/prepare_upstream.py

脚本会准备：

• python/laya-src/：固定 Git revision 的 Laya 源码；
• python/checkpoints/{english,multilingual,typed-decisions}/：固定 Hugging Face revision 的模型配置、tokenizer 和权重。

这些目录体积较大且可以重新下载，因此已被 Git 忽略。

完整转换流程

以下示例转换多语言权重；将 VARIANT 改为 english 或 typed-decisions 即可处理另外两套权重。

VARIANT=multilingual

python model_convert/generate_calibration_cases.py --variant "$VARIANT"
python model_convert/export_onnx.py --variant "$VARIANT" --verify-ort
python model_convert/prepare_calibration.py --variant "$VARIANT"
python model_convert/generate_pulsar2_config.py --variant "$VARIANT"
bash model_convert/build_ax650.sh "$VARIANT"

编译成功后，可以生成仅供本地追溯的构建记录：

python model_convert/record_build.py \
  --variant "$VARIANT" \
  --toolchain-revision "<pulsar2-revision>"

校准数据

每套权重生成 64 条任务相关校准记录，位于允许的 32–128 组范围内：

• english：16 个英文客服状态，每个状态包含四类问题，共 64 组；
• multilingual：16 个中文客服状态，每个状态包含四类问题，共 64 组；
• typed-decisions：发票、安全、客服和 Agent trace 各 16 组。

prepare_calibration.py 会为五个输入分别生成 tar，并验证样本编号、数量、S32 类型和固定 shape。同一序号的五个 .npy 构成一条完整校准样本。校准集用于覆盖量化输入分布，不作为准确率测试集。

生成目录

以下内容都由脚本生成并已加入 .gitignore：

model_convert/<variant>/calibration_cases.jsonl
model_convert/<variant>/calibration/
model_convert/<variant>/calibration_manifest.json
model_convert/<variant>/onnx/
model_convert/<variant>/export_manifest_*.json
model_convert/<variant>/pulsar2_config.json
model_convert/<variant>/compiled_ax650_npu3/
model_convert/<variant>/build_manifest.json
python/board_cases.json
python/reference_results/
python/board_results/

板端验证

将目标 .axmodel、对应 checkpoint 目录和本仓库复制到 AX650 / NPU3 设备。安装轻量依赖并生成可读案例：

python3 -m venv .venv-ax650
source .venv-ax650/bin/activate
python -m pip install -r python/requirements-ax650.txt
python model_convert/generate_board_cases.py

使用多语言权重运行全部板端案例：

python python/infer_axmodel.py \
  --variant multilingual \
  --model model_convert/multilingual/compiled_ax650_npu3/compiled.axmodel

只运行指定案例：

python python/infer_axmodel.py \
  --variant multilingual \
  --model model_convert/multilingual/compiled_ax650_npu3/compiled.axmodel \
  --case multilingual-01 \
  --case multilingual-no-refund

脚本优先使用 PyAXEngine；没有 Python 绑定时会调用板载 /opt/bin/ax_run_model。输出包含原始输入、语义预期、各候选概率、置信度、PyTorch 参考误差和耗时。详情见 python/README.md。

已验证结果

下表为固定图在 AX650 / NPU3 上的 NPU 内核耗时。一次业务请求包含多少个问题，就会执行多少次模型前向。

Checkpoint	AXModel 大小	单次决策 NPU 延迟	代表案例最大概率误差
English	504,503,011 bytes	70.039–70.173 ms	0.0062
Multilingual	533,311,117 bytes	27.735–27.807 ms	0.0185
Typed Decisions	504,501,955 bytes	69.973–70.100 ms	0.0164

Multilingual 虽然 AXModel 文件更大，但其编码器结构和算子执行路径不同，因此单次 NPU 延迟更低；文件大小不能直接用于推断运行时间。

限制

• 输入固定为 B1/S256/K4；超过 256 token 的内容会被截断。
• 当前图最多处理四个候选项，上游包含六个候选项的预设不能直接使用。
• ONNX Runtime 对齐只证明导出一致；Pulsar2 编译和板端任务效果需要分别验证。
• 模型概率不能直接作为生产阈值，应使用目标业务数据校准。
• 已观察到部分否定表达的语义错误，例如“无需退款”仍可能得到较高退款概率；这属于模型能力边界，应通过微调或业务校准处理。

License

本仓库遵循 Apache License 2.0。上游源码与模型权重遵循各自发布页面中的许可条款。