1. 自定义模型转换到底卡在哪
地平线 AI 芯片工具链里，ONNX 到板端部署这一段是很多人第一次真正踩坑的地方。模型能导出不代表能编译，能编译不代表精度够，精度够不代表板端跑得起来。我自己在 X3 上跑自定义模型时，最耗时间的不是写代码，而是反复确认三件事：输入节点名对不对、量化校准数据够不够典型、编译出来的 bin 里 BPU 和 CPU 算子分布是否合理。
这篇聚焦自定义模型转换环节，以 ONNX 为输入，把模型检查、转换参数、板端部署这条链路串起来。适合已经装好工具链 Docker 环境、手头有一个待转换 ONNX 模型、想独立跑通一次完整转换的开发者。文中会给出一份可复制的 config.toml 与 settings.json 骨架，并演示如何通过 TaoToken 统一 Key/API 通道完成工具链侧的 AI 辅助配置验证，让配置检查这一步不再靠人肉翻文档。
需要提前说明的是，TaoToken 在这里的角色是统一的模型调用通道，用来辅助生成和校验配置骨架、排查报错语义，不替代工具链本身的编译能力。工具链该跑的 hb_mapper 一步都不能少。
2. 前置准备：目录、模型与 TaoToken 通道
2.1 目录结构与模型就位
在 Docker 挂载目录下新建工作目录，我习惯用08_hjw_demo，你可以自定义。目录里放三样东西：ONNX 模型、检查脚本、编译配置。
mkdir -p 08_hjw_demo/mapper cd 08_hjw_demo/mapper # 放入 hjw_demo.onnx ls -lh hjw_demo.onnx模型建议先用 Netron 打开看一眼，确认输入名、输入 shape、opset 版本。很多转换失败根源就在输入名写错，比如模型里叫data，配置里写成input，hb_mapper 会直接报找不到节点。
2.2 TaoToken 通道准备
工具链侧的 AI 辅助配置需要一个稳定的模型调用入口。TaoToken 提供统一的 Key 和 API 通道，把不同模型的调用收敛到一套鉴权上，省去在多个平台之间切换 Key 的麻烦。
先去控制台创建 API Key：
# 控制台地址（创建 Key） https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=console创建后把 Key 写进环境变量，避免硬编码进脚本：
export TAOTOKEN_API_KEY="sk-你的key" export TAOTOKEN_BASE_URL="https://taotoken.net/api"API 基础地址不带 UTM，直接用于请求：
# API 基础地址 https://taotoken.net/api如果你更习惯在对话界面里先验证配置语义，可以打开模型对话页，把 config 片段贴进去让它帮你核对字段：
# 模型对话 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=model_chat长期做模型转换和 Agent 辅助的，可以看 Coding Plan，额度模型更适合反复调试：
# Coding Plan https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=coding_plan2.3 工具链版本确认
进入 Docker 后先确认版本，不同版本参数名有差异：
hb_mapper --version # 期望输出类似 hb_mapper version 1.1.63. 可复制配置：config.toml 与 settings.json 骨架
3.1 模型检查脚本
先跑检查，确认模型能被解析、算子分布合理。新建01_check.sh：
#!/usr/bin/env sh cd $(dirname $0) || exit set -e model_type="onnx" proto="./hjw_demo.onnx" caffe_model="./hjw_demo.onnx" output="./hjw_demo_checker.log" hb_mapper checker --model-type ${model_type} \ --proto ${proto} --model ${caffe_model} \ --output ${output}执行：
sh 01_check.sh检查日志里重点看三行：The onnx model was parsed successfully、Model input names、以及最后的节点信息表。如果 BPU 节点占绝大多数，说明模型对硬件友好；如果大量节点落在 CPU，后面编译出来推理会慢。
3.2 config.toml 骨架
工具链新版本支持 toml 风格的配置组织，下面这份骨架把模型参数、输入参数、校准参数、编译参数分开，便于维护：
# config.toml - 自定义模型转换配置骨架 [model_parameters] onnx_model = "hjw_demo.onnx" layer_out_dump = false log_level = "debug" working_dir = "model_output" output_model_file_prefix = "hjw_demo" [[input_parameters]] input_name = "data" input_type_rt = "featuremap" input_type_train = "featuremap" norm_type = "no_preprocess" input_shape = "1x8x1200x800" [calibration_parameters] calibration_type = "kl" preprocess_on = false promoter_level = -1 [[calibration_parameters.cal_data]] input_name = "data" dir = "../calibration_data_feature" [compiler_parameters] compile_mode = "latency" debug = true # core_num = 2几个字段的取舍逻辑：input_type_rt和input_type_train都设featuremap是因为这个模型输入不是图像而是特征图；如果你的模型吃 RGB 图像，训练侧写rgbp，运行侧按实际输入写nv12或rgbp。calibration_type用kl是通用起点，精度不够再试max或promoter。
3.3 settings.json 骨架
有些流程用 json 管理运行时设置，下面这份对应上面的 toml，字段语义一致：
{ "model_parameters": { "onnx_model": "hjw_demo.onnx", "working_dir": "model_output", "output_model_file_prefix": "hjw_demo", "log_level": "debug" }, "input_parameters": [ { "input_name": "data", "input_type_rt": "featuremap", "input_type_train": "featuremap", "norm_type": "no_preprocess", "input_shape": "1x8x1200x800" } ], "calibration_parameters": { "calibration_type": "kl", "preprocess_on": false, "cal_data": [ { "input_name": "data", "dir": "../calibration_data_feature" } ] }, "compiler_parameters": { "compile_mode": "latency", "debug": true } }3.4 用 TaoToken 校验配置语义
配置字段多，容易写错。可以把 config.toml 片段发给 TaoToken 的模型对话，让它逐字段核对是否与工具链版本匹配。请求示例：
curl -s https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer ${TAOTOKEN_API_KEY}" \ -H "Content-Type: application/json" \ -d '{ "model": "claude-sonnet", "messages": [ {"role": "user", "content": "帮我核对这份地平线工具链 config.toml 的字段：input_type_rt 为 featuremap，input_shape 为 1x8x1200x800，calibration_type 为 kl。指出可能不匹配的项。"} ] }'返回里如果提示input_shape与模型实际输入不一致，就回去用 Netron 再确认一遍。这一步只是辅助，最终以 hb_mapper 实际报错为准。
4. 编译与验证：从 ONNX 到板端 bin
4.1 编译脚本
新建02_build.sh：
#!/bin/bash cd $(dirname $0) || exit set -e config_file="./hjw_demo_config.yaml" model_type="onnx" hb_mapper makertbin --config ${config_file} \ --model-type ${model_type}如果你用的是 toml 骨架，把--config指向 toml 文件即可，工具链会按扩展名解析。
4.2 编译过程关键日志
执行sh 02_build.sh，日志里几个节点值得盯：
INFO Start to parse the onnx model. INFO The onnx model was parsed successfully. INFO Saving the original float model: hjw_demo_original_float_model.onnx. INFO Start to optimize the model. INFO Saving the optimized model: hjw_demo_optimized_float_model.onnx. INFO Run calibration model with kl method. INFO number of calibration data samples: 48 INFO The model was quantized successfully. INFO Saving the quantized model: hjw_demo_quantized_model.onnx. INFO Start to compile the model with march: bernoulli2. INFO The model was compiled successfully. INFO Convert to runtime bin file sucessfully!看到Convert to runtime bin file sucessfully就说明 bin 出来了。产物在model_output目录：
ls -lh model_output/ # hjw_demo.bin hjw_demo_quantized_model.onnx ...4.3 板端部署验证
把 bin 推到板端，用工具链自带的推理示例加载。板端侧确认模型能加载、输入输出 shape 与预期一致：
# 板端加载示例（路径按实际调整） ./run_model --model hjw_demo.bin --input data如果板端报 shape 不匹配，回到 config 里核对input_shape是否与模型训练时一致。这一步的报错信息通常很直白，比编译期好排查。
4.4 用 TaoToken 辅助解读报错
编译或板端报错时，把日志片段发给 TaoToken，让它帮你定位是配置问题还是模型问题。比如校准阶段出现 reshape 失败：
[E:onnxruntime] Non-zero status code returned while running Reshape node. Input shape:{8,75,50,14}, requested shape:{1,7500,7,1}这类报错往往是 batch 维度在动态 reshape 时对不上。工具链会自动把 batch_size 重置为 1 再试一次，日志里会看到Reset batch_size=1 and execute calibration again。如果重置后仍失败，就需要检查模型里是否有硬编码的 reshape 维度。
5. 本篇常见错排查
5.1 输入节点名不匹配
报错特征：input names []为空，或提示找不到指定节点。原因基本是 config 里的input_name与 ONNX 模型里的实际输入名不一致。用 Netron 打开模型，点输入节点看 name 字段，原样抄进配置。
5.2 校准数据不足或场景偏差
报错特征：量化后精度掉得厉害，或校准阶段直接失败。校准数据建议 20 到 50 张，覆盖典型场景，别用过曝、纯黑、模糊的图。特征图输入的模型，校准数据要按同样 shape 准备。
5.3 算子落在 CPU 过多
检查日志里如果 CPU 节点占比高，推理会慢。常见原因是模型里有工具链不支持的算子，或者 reshape、concat 这类操作放在了不合适的位置。可以尝试在导出 ONNX 时简化图结构，或调整算子顺序。
5.4 编译模式选错
compile_mode设latency优化推理时间，设bandwidth优化 DDR 带宽。板端算力紧张选 latency，内存带宽紧张选 bandwidth。选错不会报错，但性能不符合预期。
5.5 TaoToken 请求返回鉴权失败
如果 curl 返回 401，检查TAOTOKEN_API_KEY是否导出成功，以及请求头里 Bearer 后面有没有多余空格。Key 在控制台重新生成后旧 Key 会失效，记得同步更新环境变量。
6. 继续往下走
跑通一次自定义模型转换后，下一步通常是接板端推理示例、做精度对齐、再上真实业务数据。工具链侧的 AI 辅助配置可以继续用 TaoToken 的通道来做，把配置核对、报错解读这些重复动作收敛到一个入口。
接入文档里有完整的 API 说明和字段定义，配置骨架对不上时优先查这里：
# 接入文档 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=docKey 管理在 API Keys 页面，建议按项目分 Key，方便排查和回收：
# API Keys https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=api_keys如果你用 Claude Code 做工具链侧的脚本辅助，Anthropic 兼容通道可以直接接：
# ClaudeCodeAnthropic https://taotoken.net/claude-code-anthropic?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=claudecode最后提醒一句：config 里的input_shape和input_name是转换失败的两大高频原因，每次换模型先花两分钟用 Netron 确认，比事后翻日志省事得多。
