问题描述
电赛备赛现场，大家可能都经历过这样的剧情：
摄像头架好了，图片拍完了，数据标完了。Ultralytics 一跑，best.pt 有了；再敲一条命令，ONNX 也顺利导出来了。
你正准备向队友宣布“视觉部分马上搞定”，下一秒却发现——
ONNX 怎么变成 KModel？
环境怎么配置？
nncase 环境到底该装哪个版本？
校准集选多少张？参数怎么填？
为什么昨天还能转换，今天换台电脑就开始报错？
模型训练只用了半天，环境配置却像一个隐藏 Boss，眼看着比赛倒计时一格一格往下掉。
这也是我们推出 YOLO KModel 转换器 1.0.0 的原因：让 ONNX→KModel 不再是一段需要反复“考古”的命令行冒险，而是几个清楚、可重复的图形化步骤。
下载链接：
一、先把故事从头说起：约 100 张图片，能做出一个 YOLO 模型吗？
如果比赛场景相对固定、类别不多、拍摄条件可控，先采集约 100 张有代表性的图片，完成标注和训练/验证集划分，通常就能在 Ultralytics 官方训练环境中快速跑出一个可验证方案的 YOLO 原型。
训练完成后，导出 ONNX 也很直接：
yolo detect train data=your_data.yaml model=yolo11n.pt epochs=100 imgsz=320
yolo export model=runs/detect/train/weights/best.pt format=onnx imgsz=320
不过，“约 100 张”只是一个适合快速起步的数字，不是精度保证书。比赛效果仍然取决于类别难度、标注质量、光照变化、目标尺度和样本覆盖情况。
换句话说：100 张精心设计、覆盖真实赛场情况的图片，往往比 100 张在同一位置连拍的图片更有价值。
模型导出 ONNX 后，新的问题才刚刚登场。
K230官方链路是：在电脑端通过 nncase 把 ONNX 等模型编译成可由 KPU 加速的 .kmodel，然后在 K230 上通过 KPU Runtime 加载模型、设置输入、执行推理并读取输出。
原理并不绕，但版本、量化、输入尺寸和校准数据一股脑儿叠在一起，就很容易让人进入“缺一个库、补一个库，又冒出三个新报错”的循环。
所以，我们把中间最容易卡人的一段封装成了图形化工具。
二、YOLO KModel 转换器到底负责哪一段？
一句话概括：
它负责把已经训练并导出的 YOLO ONNX 模型，量化、编译为 K230 可加载的 .kmodel。
边界也要提前说清楚：软件只提供 ONNX→KModel 转换，不包含图片标注、YOLO 训练、PT→ONNX 导出，也不替代 K230 板端的预处理、后处理和业务代码。
它不是“一键包办整个视觉系统”，而是把训练与板端部署之间最容易让人掉头发的一段路修平。
三、为什么它更适合电赛备赛？
01 不写转换脚本，也能完成 ONNX→KModel
打开软件后，选择 ONNX 模型、校准图片目录和输出位置，再确认模型版本、任务类型、输入尺寸与量化选项，点击“开始转换”即可。
转换过程中：
- 界面会显示进度和关键编译信息；
- 普通第三方 warning 默认过滤，日志不会瞬间变成“红字瀑布”；
- 真正的错误信息和 Traceback 会完整保留；
- 成功后可以直接打开输出目录。
02 支持常用 YOLO 系列和多种视觉任务
当前版本的支持范围如下
| YOLO系列 | 检测 detect | 分类 classify | 分割 segment | 姿态 pose | 旋转框 OBB |
|---|---|---|---|---|---|
| YOLOv5 | ✓ | ✓ | ✓ | - | - |
| YOLOv8 | ✓ | ✓ | ✓ | ✓ | ✓ |
| YOLO11 | ✓ | ✓ | ✓ | ✓ | ✓ |
| YOLO26 | ✓ | ✓ | ✓ | ✓ | ✓ |
注意：任务类型必须和训练任务一致。检测模型请选择 detect，分类模型请选择 classify，不要让检测模型从分割入口“跨专业参赛”。
03 自动读取常见模型输入尺寸
选择 ONNX 后，软件会尝试读取模型输入名称、维度和布局，识别常见的固定输入：
NCHW：[1, 3, 高度, 宽度]
NHWC：[1, 高度, 宽度, 3]
识别成功后，软件会自动填写输入宽高，并把输出路径设置成同名 .kmodel。
如果模型使用动态高度或宽度，软件会提示手动填写。这里不能凭感觉猜，填写值必须与模型实际部署尺寸一致。
官方转换脚本会将输入宽高向上调整为 32 的整数倍。为了减少后续的不确定性，建议导出时直接使用 320×320、640×640 这类尺寸。
04 内置 6 种 PTQ 量化配置
| 选项 | 校准算法 | 数据类型 | 权重类型 |
|---|---|---|---|
| 0 | NoClip | uint8 | uint8 |
| 1 | NoClip | uint8 | int16 |
| 2 | NoClip | int16 | uint8 |
| 3 | Kld | uint8 | uint8 |
| 4 | Kld | uint8 | int16 |
| 5 | Kld | int16 | uint8 |
第一次转换建议从选项 0 开始。
这里不是游戏装备强化，选项数字更大并不代表效果更强。其他配置需要结合模型大小、精度和板端表现进行实测。
05 自动兼容部分其他 IR version 模型
软件固定使用 ONNX 1.15.0，其支持的最高 IR version 为 9。遇到其他版本的IR version模型时，软件会软尝试对齐IR版本和检查nncase支持的opset，尽可能的进行兼容，但是不保证一定可以转换成功。
如果模型实际使用了更高版本 IR 才有的结构，转换仍可能失败。这时应使用兼容 ONNX 1.15.0 的导出环境重新导出，而不是强行修改原模型。
06 绿色免安装，自带固定运行环境
软件内置并隔离加载：
- .NET Runtime 7.0.20
- Python 3.10.11
- nncase 2.11.0
- nncase-kpu 2.11.0
- ONNX 1.15.0
- ONNX Runtime 1.19.0
- ONNX Simplifier 0.4.36
- Pillow 10.4.0
它不修改系统 PATH，不替换电脑已有的 Python 或 .NET，不写入注册表；模型和校准图片不会上传，整个转换过程无需联网。
简单说就是：队友电脑上装了什么版本的 Python，不再影响这次转换。
四、从拍图片到 K230 跑起来，完整流程怎么走？
下面按备赛节奏一步一步来。
第一步：采集、标注、训练并导出 ONNX
- 先让数据覆盖真实比赛环境：
- 正常光照和阴影；
- 不同背景与干扰物；
- 目标的远近、大小和角度；
- 摄像头可能出现的真实安装位置；
- 赛场上可能遇到的曝光和运动情况。
完成训练后导出固定输入尺寸的 ONNX。模型名称、训练轮数和输入尺寸要根据自己的任务调整，前面的命令只是最小示例。
第二步：准备校准图片
PTQ 量化需要校准数据。软件要求目录中至少有 20 张可正常读取的图片，支持 JPG、JPEG、PNG、BMP 等 Pillow 可读取格式。
校准图不要在提交前五分钟从文件夹里“随缘抽卡”，建议从真实训练集或验证集中选取，覆盖典型光照、背景、目标大小和拍摄角度。
目录里不要混放标签文本、损坏文件和其他非图片。校准数据是否有代表性，会直接影响量化后的实际精度。
第三步：完整解压绿色版
软件支持 Windows 10/11 x64，解压后完整目录结构应为：
YOLO-KModel-Converter-Portable-Slim\
├─ YOLO-KModel-Converter-Portable-Slim-Win.exe
├─ README.md
└─ runtime\
不要只把 exe 单独拎出来。exe 和 runtime 是搭档，拆队之后谁也跑不起来。
双击YOLO-KModel-Converter-Portable-Slim-Win.exe，第一次使用可以先点“检测绿色环境”，确认组件完整。
第四步：选择模型并确认参数
依次完成：
- 选择待转换的 .onnx；
- 选择校准图片目录；
- 确认输出 .kmodel 路径；
- 选择正确的 YOLO 版本；
- 选择与训练一致的任务类型；
- 检查自动识别的输入宽高；
- 第一次转换选择量化选项 0。
如果无法自动读取输入尺寸，可以先用导出配置或 Netron 确认模型输入。常见原因包括动态宽高、多输入、非标准四维图像张量，或通道数不是3。
第五步：点击“开始转换”
转换期间不要关闭软件，也不要移动运行目录。成功后，界面会显示输出路径，点击“打开输出目录”即可找到生成的 .kmodel。
如果失败，也别急着进行传统艺能——卸载重装所有 Python。
先看日志，再按模型尺寸、任务类型、校准图片、依赖完整性和模型兼容性的顺序排查，通常更快。
第六步：放到 K230 上验证
.kmodel 是模型转换的终点，但只是板端应用的起点。K230 端仍然需要：
- 按训练与导出约定完成图像预处理；
- 使用 KPU Runtime 加载 .kmodel；
- 设置输入张量并执行推理；
- 读取输出张量；
- 按 detect/classify/segment/pose/obb 的输出格式完成后处理；
- 将结果用于显示、测量或控制。
尤其要核对输入尺寸、通道顺序、颜色顺序和归一化方式。很多“模型转换成功，但结果像在随机答题”的问题，最后查出来都是电脑端和板端预处理没有对齐。
赛前避坑速查
提示“绿色版依赖不完整”
通常是 exe 与 runtime 目录不完整，或相对位置被改变。请把最新版压缩包完整解压到全新目录，不要只复制 exe，也不要直接覆盖正在运行的软件。
提示校准图片数量不足
所选目录中需要至少 20 张可正常读取的图片。检查数量、格式和损坏文件，目录内不要混放标注文本。
提示未找到对应转换脚本
检查 YOLO 版本和任务组合。例如 YOLOv5 当前不支持 pose 与 obb。
转换成功，但板端精度下降
建议按下面顺序排查：
- 校准图片是否真正代表比赛场景；
- 输入分辨率是否与训练、导出时一致；
- 板端颜色顺序、通道与归一化是否一致；
- 后处理是否匹配对应 YOLO 版本和任务；
- 再测试不同 PTQ 选项并进行量化对比。
参考资料
Ultralytics 官方训练模式：
https://docs.ultralytics.com/modes/train/
Ultralytics 官方 ONNX 导出说明：
https://docs.ultralytics.com/modes/export/
Kendryte K230 nncase Github：
https://github.com/kendryte/nncase
Kendryte K230 YOLO大作战：
https://www.kendryte.com/k230_canmv/zh/main/example/ai/yolo_battle.html