# YOLO KModel 转换器用户指南

版本：1.0.0  
平台：Windows 10/11 x64  
目标设备：Kendryte K230

本软件用于将 YOLO 系列 ONNX 模型转换为 K230 可部署的 `.kmodel` 文件，支持
YOLOv5、YOLOv8、YOLO11、YOLO26，以及检测、分类、分割、姿态和 OBB 等任务。

## 1. 解压与启动

1. 完整解压 `YOLO-KModel-Converter-Portable-Slim-Win.zip`。
2. 打开解压后的 `YOLO-KModel-Converter-Portable-Slim-Win` 文件夹。
3. 双击 `YOLO-KModel-Converter-Portable-Slim-Win.exe`。
4. 首次使用建议点击“检测便携环境”。

正确的目录结构如下：

```text
YOLO-KModel-Converter-Portable-Slim-Win\
├─ YOLO-KModel-Converter-Portable-Slim-Win.exe
├─ README.md
└─ runtime\
   ├─ dotnet\
   ├─ python\
   ├─ tools\
   └─ installed.json
```

请勿单独复制 EXE，也不要移动、删除或重命名 `runtime` 文件夹。软件可以解压到任意
盘符和任意用户目录，但 EXE 必须始终与 `runtime` 保持同级。

建议解压到具有读写权限的位置，例如桌面、文档或其他工作目录。不要直接放在
`C:\Program Files` 中运行。

## 2. 转换前准备

### ONNX 模型

- 模型格式必须为 `.onnx`。
- YOLO 版本和任务类型必须与模型实际训练任务一致。
- 建议使用固定输入尺寸，例如 `320×320` 或 `640×640`。
- 模型使用动态输入尺寸时，需要手动填写实际部署宽度和高度。

### 校准图片

- 建议准备至少 20 张可正常读取的图片。
- 图片应来自模型实际应用场景，并覆盖不同目标、背景、光照和拍摄角度。
- 推荐使用 JPG、JPEG、PNG 或 BMP 格式。
- 可以选择包含多级子文件夹的数据集根目录；软件会递归查找图片。
- 文本、标注、子目录和无法读取的损坏图片会被自动忽略。

校准图片的代表性会直接影响量化后 KModel 的实际精度。

## 3. 转换步骤

1. 点击“ONNX 模型”右侧的“浏览…”，选择模型。
2. 软件会尝试自动读取输入尺寸，并生成默认的同名 `.kmodel` 输出路径。
3. 点击“校准图片目录”右侧的“浏览…”，选择校准图片文件夹。
4. 如需更改输出位置，点击“输出 KModel”右侧的“浏览…”。
5. 选择正确的 YOLO 版本。
6. 选择与模型一致的任务类型。
7. 检查输入宽度和高度；无法自动识别时请手动填写。
8. 选择量化选项，首次使用建议选择 `0`。
9. 点击“开始转换”。
10. 等待日志显示转换完成，然后点击“打开输出目录”查看结果。

转换期间请勿关闭软件、移动软件目录或修改 `runtime` 文件。

## 4. 参数说明

| 参数 | 说明 |
|---|---|
| ONNX 模型 | 需要转换的 `.onnx` 文件 |
| 校准图片目录 | PTQ 量化使用的图片目录 |
| 输出 KModel | 生成的 `.kmodel` 保存位置 |
| YOLO 版本 | YOLOv5、YOLOv8、YOLO11 或 YOLO26 |
| 任务类型 | detect、classify、segment、pose 或 obb |
| 输入尺寸 | 模型实际使用的宽度和高度 |
| 量化选项 | 校准算法、数据类型和权重类型组合 |

量化选项：

| 选项 | 校准算法 | 数据类型 | 权重类型 |
|---:|---|---|---|
| 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`。如果量化精度或部署效果不理想，再分别测试其他选项。

## 5. 支持的任务

| YOLO 版本 | 检测 | 分类 | 分割 | 姿态 | OBB |
|---|:---:|:---:|:---:|:---:|:---:|
| YOLOv5 | ✓ | ✓ | ✓ | — | — |
| YOLOv8 | ✓ | ✓ | ✓ | ✓ | ✓ |
| YOLO11 | ✓ | ✓ | ✓ | ✓ | ✓ |
| YOLO26 | ✓ | ✓ | ✓ | ✓ | ✓ |

检测模型必须选择“目标检测”，分类模型必须选择“图像分类”，其他任务同理。选择错误的
YOLO 版本或任务类型会导致转换失败或输出不符合预期。

## 6. 模型兼容提示

软件会在转换前自动检查 ONNX 模型兼容性，并在安全的情况下处理 IR 和 opset。原始
ONNX 文件不会被修改。

如果模型包含当前转换环境不支持的算子、自定义算子或无法安全转换的 opset，软件会
停止转换并在日志中显示原因。此时请根据日志重新导出 ONNX 模型，不要直接修改模型的
版本数字。

## 7. 常见问题

### 提示“便携运行时不完整”

说明 ZIP 没有完整解压，或者 EXE 与 `runtime` 的相对位置被改变。请删除当前目录，
重新完整解压 ZIP 后再运行。

### 三个“浏览”按钮打开的位置不合适

模型、数据集和输出位置分别记忆各自最近使用的目录。重新选择一次对应位置后，软件会
更新该项目的浏览目录。

### 无法自动读取输入尺寸

模型可能使用动态尺寸、多个输入或非标准图像布局。请使用模型导出配置或 Netron 确认
实际输入宽高，然后手动填写。

### 提示校准图片不足或无法读取

确保所选目录及其子目录中至少有 20 张有效图片。软件会自动忽略文本、标注、目录和
损坏文件，并在有效图片不足时显示扫描结果。

### 提示不支持某个算子或 opset

当前模型无法在不确定计算结果的情况下自动兼容。请使用与转换环境兼容的导出参数重新
导出 ONNX，或调整模型中不受支持的结构。

### 转换成功但板端精度下降

请检查：

- 校准图片是否具有代表性；
- 输入尺寸是否与训练、导出和部署时一致；
- 板端图像通道、颜色顺序、缩放和归一化是否正确；
- YOLO 版本和任务类型是否选择正确；
- 不同量化选项的效果是否有差异。

### 转换过程中软件无响应

大型模型编译需要较长时间。只要日志仍在更新或系统仍有计算活动，请继续等待，不要
重复点击转换或强制关闭软件。

## 8. 日志和临时文件

日志区域会显示兼容性检查、转换进度和错误信息。遇到问题时，请保留完整日志以便排查。
“清空日志”只会清除界面内容，不会删除模型或输出文件。

转换失败时，软件会在主窗口中央弹出错误说明，显示识别到的具体问题和处理建议；完整的
技术错误和 Traceback 仍保留在日志中。

转换使用的中间文件位于 Windows 临时目录，正常结束后会自动清理。如果软件被强制
关闭，可在系统临时目录中删除名称以 `YoloKModelConverter-` 开头的残留文件夹。

## 9. 卸载

本软件无需安装。关闭程序后，删除整个
`YOLO-KModel-Converter-Portable-Slim-Win` 文件夹即可完成卸载。
