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配置里写成inputhb_mapper 会直接报找不到节点。2.2 TaoToken 通道准备工具链侧的 AI 辅助配置需要一个稳定的模型调用入口。TaoToken 提供统一的 Key 和 API 通道把不同模型的调用收敛到一套鉴权上省去在多个平台之间切换 Key 的麻烦。先去控制台创建 API Key# 控制台地址创建 Key https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentconsole创建后把 Key 写进环境变量避免硬编码进脚本export TAOTOKEN_API_KEYsk-你的key export TAOTOKEN_BASE_URLhttps://taotoken.net/apiAPI 基础地址不带 UTM直接用于请求# API 基础地址 https://taotoken.net/api如果你更习惯在对话界面里先验证配置语义可以打开模型对话页把 config 片段贴进去让它帮你核对字段# 模型对话 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmodel_chat长期做模型转换和 Agent 辅助的可以看 Coding Plan额度模型更适合反复调试# Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcoding_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_typeonnx 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 为 featuremapinput_shape 为 1x8x1200x800calibration_type 为 kl。指出可能不匹配的项。} ] }返回里如果提示input_shape与模型实际输入不一致就回去用 Netron 再确认一遍。这一步只是辅助最终以 hb_mapper 实际报错为准。4. 编译与验证从 ONNX 到板端 bin4.1 编译脚本新建02_build.sh#!/bin/bash cd $(dirname $0) || exit set -e config_file./hjw_demo_config.yaml model_typeonnx 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_size1 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_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdocKey 管理在 API Keys 页面建议按项目分 Key方便排查和回收# API Keys https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapi_keys如果你用 Claude Code 做工具链侧的脚本辅助Anthropic 兼容通道可以直接接# ClaudeCodeAnthropic https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentclaudecode最后提醒一句config 里的input_shape和input_name是转换失败的两大高频原因每次换模型先花两分钟用 Netron 确认比事后翻日志省事得多。 地平线 AI 芯片工具链 - 03 自定义模型转换：ONNX 到板端部署的 TaoToken 配置骨架
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配置里写成inputhb_mapper 会直接报找不到节点。2.2 TaoToken 通道准备工具链侧的 AI 辅助配置需要一个稳定的模型调用入口。TaoToken 提供统一的 Key 和 API 通道把不同模型的调用收敛到一套鉴权上省去在多个平台之间切换 Key 的麻烦。先去控制台创建 API Key# 控制台地址创建 Key https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentconsole创建后把 Key 写进环境变量避免硬编码进脚本export TAOTOKEN_API_KEYsk-你的key export TAOTOKEN_BASE_URLhttps://taotoken.net/apiAPI 基础地址不带 UTM直接用于请求# API 基础地址 https://taotoken.net/api如果你更习惯在对话界面里先验证配置语义可以打开模型对话页把 config 片段贴进去让它帮你核对字段# 模型对话 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmodel_chat长期做模型转换和 Agent 辅助的可以看 Coding Plan额度模型更适合反复调试# Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcoding_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_typeonnx 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 为 featuremapinput_shape 为 1x8x1200x800calibration_type 为 kl。指出可能不匹配的项。} ] }返回里如果提示input_shape与模型实际输入不一致就回去用 Netron 再确认一遍。这一步只是辅助最终以 hb_mapper 实际报错为准。4. 编译与验证从 ONNX 到板端 bin4.1 编译脚本新建02_build.sh#!/bin/bash cd $(dirname $0) || exit set -e config_file./hjw_demo_config.yaml model_typeonnx 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_size1 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_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdocKey 管理在 API Keys 页面建议按项目分 Key方便排查和回收# API Keys https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapi_keys如果你用 Claude Code 做工具链侧的脚本辅助Anthropic 兼容通道可以直接接# ClaudeCodeAnthropic https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentclaudecode最后提醒一句config 里的input_shape和input_name是转换失败的两大高频原因每次换模型先花两分钟用 Netron 确认比事后翻日志省事得多。