# ModelConverter

**Repository Path**: ybf521/model-converter

## Basic Information

- **Project Name**: ModelConverter
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-06-08
- **Last Updated**: 2026-06-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ONNX Model Converter

[English](README.en.md) | 中文

一个基于 Flask 的 ONNX 模型转换 Web 服务，支持将 ONNX 模型转换为多种端侧推理框架格式，提供直观的 Web 界面进行拖拽上传、参数配置和结果下载。

## 支持的转换格式

| 输出格式 | 推理后端 | 量化支持 | 平台要求 |
|----------|----------|----------|----------|
| `.ncnn` (param+bin) | NCNN | FP32 / FP16 | Linux / Windows |
| `.mnn` | MNN | FP32 / FP16 / INT8 | Linux / Windows |
| `.tflite` | TFLite | FP32 / FP16 / INT8 | Linux / Windows |
| `.om` | HIAI (CANN NPU) | FP16 / INT8 | Linux |
| `.ms` | MindSpore Lite | FP32 / FP16 / INT8 | Linux / Windows |

> **注意**：Web 前端当前仅提供 FP32 / FP16 量化选项，INT8 量化可通过 API 直接调用。

## 功能特性

- 拖拽上传 ONNX 模型文件，实时显示文件信息
- 多格式批量转换，一次提交可同时转换多种格式
- 自定义输入 Shape（支持逐维输入和文本输入两种模式）
- 动态维度自动修正，对含动态/符号维度的 ONNX 模型进行固定化处理
- FP16 / INT8 量化支持（按目标格式不同）
- 标杆数据自动生成，基于 ONNX Runtime 推理生成输入/输出标杆数据用于精度验证
- MindSpore Lite 工具链自动下载，首次使用 `.ms` 格式转换时自动下载 `converter_lite` 到 `tools/mslite/`
- HIAI DDK 工具链自动下载，首次使用 `.om` 格式转换时自动下载 DDK 到 `tools/hiai/`，并自动降级 ONNX opset（最高支持 opset 18）
- Download Key 分享机制，转换完成后生成 8 位 Key，可通过 URL `?key=xxxx` 或页面输入查询下载结果
- 任务过期自动清理，转换结果 24 小时后自动删除，前端实时显示剩余有效期倒计时
- 异步转换任务，轮询状态查询，完成后自动展示下载链接
- 日志记录请求全生命周期

## 项目结构

```
model-converter/
├── entry.py              # Flask 服务入口，定义路由和任务管理
├── backend/
│   ├── benchmark.py      # 标杆数据生成（ONNX Runtime 推理）
│   ├── ncnn/
│   │   ├── __init__.py
│   │   └── ncnn.py       # ONNX → NCNN 转换 (通过 PNNX)
│   ├── mnn/
│   │   ├── __init__.py
│   │   └── mnn.py        # ONNX → MNN 转换 (通过 MNNConvert)
│   ├── tflite/
│   │   ├── __init__.py
│   │   └── tflite.py     # ONNX → TFLite 转换 (通过 onnx2tf)
│   ├── mslite/
│   │   ├── __init__.py
│   │   ├── ms_converter.py # ONNX → MindSpore Lite 转换 (通过 converter_lite)
│   │   └── setup_env.py    # MindSpore Lite 工具自动下载与环境配置
│   └── hiai/
│   │   ├── __init__.py
│   │   ├── hiai_converter.py # ONNX → HIAI .om 转换 (通过 omg/atc/nn_convert)
│   │   └── setup_env.py      # HIAI DDK 自动下载与环境配置
├── index.html             # Web 前端页面
├── app.js                 # 前端交互逻辑
├── api.js                 # 前端 API 请求封装
├── style.css              # 前端样式
├── tests/
│   ├── autotest.py        # 自动化测试入口
│   ├── test_common.py     # 测试公共工具与 fixture
│   ├── ncnn/              # NCNN 转换单元/系统测试
│   ├── mnn/               # MNN 转换单元/系统测试
│   ├── mslite/            # MindSpore Lite 转换单元/系统/环境配置测试
│   ├── tflite/            # TFLite 转换单元/系统测试
│   └── hiai/              # HIAI 转换单元/环境配置测试
├── tools/                 # 工具链缓存目录（自动下载）
│   ├── mslite/            # MindSpore Lite converter_lite
│   ├── hiai/              # HIAI DDK
│   └── onnx2tf/           # onnx2tf 校准数据缓存
├── requirements.txt       # Python 依赖
└── LICENSE                # Apache 2.0 许可证
```

## 快速开始

### 环境要求

- Python 3.8+
- PNNX 可执行文件（用于 NCNN 转换，需单独安装并确保 `pnnx` 模块中 `EXEC_PATH` 配置正确）
- MindSpore Lite `converter_lite` 工具（首次使用 `.ms` 格式时会自动下载，也可手动设置 `CONVERTER_LITE_PATH` 和 `PACKAGE_ROOT_PATH` 环境变量）
- HIAI DDK 转换工具（首次使用 `.om` 格式时会自动下载，仅支持 Linux 平台，也可手动设置 `HIAI_CONVERTER_PATH` 和 `HIAI_PACKAGE_ROOT` 环境变量）

### 安装

```bash
git clone <repository-url>
cd model-converter
pip install -r requirements.txt
```

### 启动服务

```bash
python entry.py
```

服务默认运行在 `http://0.0.0.0:9999`。

### 使用

1. 在浏览器中打开 `http://localhost:9999`
2. 拖拽或选择 `.onnx` 模型文件
3. 选择目标输出格式（NCNN / MNN / TFLite / MindSpore Lite / HIAI）
4. 配置转换参数（输入格式、量化类型、输入 Shape）
5. 点击「开始转换」，等待完成后下载转换结果
6. 转换完成后会生成 Download Key，可通过页面 Key 查询或 URL `?key=xxxx` 分享下载链接

## API 接口

### 提交转换任务

```
POST /api/convert
```

| 参数 | 类型 | 说明 |
|------|------|------|
| model | file | ONNX 模型文件 |
| formats | JSON string | 目标格式列表，如 `["ncnn", "mnn", "om"]` |
| inputFormat | string | 输入数据格式：`NCHW` 或 `NHWC` |
| quantType | string | 量化类型：`fp32`、`fp16` 或 `int8` |
| outputFormat | string | 输出数据格式：`NCHW` 或 `NHWC` |
| inputShape | JSON string | 自定义输入 Shape，如 `[1,3,224,224]`（可选） |

返回：

```json
{
  "taskId": "uuid",
  "status": "pending",
  "downloadKey": "a1b2c3d4"
}
```

### 查询任务状态

```
GET /api/status/<taskId>
```

返回：

```json
{
  "taskId": "uuid",
  "status": "success",
  "createdAt": 1718000000,
  "expireSeconds": 86400,
  "downloadKey": "a1b2c3d4",
  "results": [
    {
      "format": "ncnn",
      "backend": "NCNN",
      "status": "success",
      "outputDir": "ncnn",
      "files": [{"name": "model.ncnn.param", "size": 1234}, {"name": "model.ncnn.bin", "size": 5678}]
    }
  ],
  "benchmarkFiles": [
    {"name": "images.txt", "size": 1024},
    {"name": "conv_out.txt", "size": 2048}
  ],
  "benchmarkDir": "benchmark"
}
```

### 通过 Download Key 查询

```
GET /api/key/<key>
```

返回与 `GET /api/status/<taskId>` 相同格式的结果。也可在浏览器中通过 `http://localhost:9999?key=a1b2c3d4` 直接访问。

### 下载转换结果

```
GET /api/download/<taskId>/<path:filename>
```

## 运行测试

```bash
python -m pytest tests/ -v
```

或使用自动化脚本：

```bash
python tests/autotest.py
```

## 转换原理说明

- **NCNN**：调用 [PNNX](https://github.com/pnnx/pnnx) 将 ONNX 模型转换为 NCNN param+bin 格式，支持自动设置 Input Shape
- **MNN**：调用 MNN 的 Python 转换工具 `MNNConvert`，支持 FP16 半精度和 INT8 权重量化（`--weightQuantBits 8`）
- **TFLite**：调用 [onnx2tf](https://github.com/PINTO0309/onnx2tf) 进行 ONNX→TFLite 转换，INT8 量化通过 TensorFlow Lite 的 `TFLiteConverter` 后训练量化实现
- **MindSpore Lite**：调用 MindSpore Lite 的 `converter_lite` 命令行工具将 ONNX 模型转换为 `.ms` 格式，支持 FP16 和 INT8 量化，首次使用时自动从官方 CDN 下载工具链（版本 2.9.0）
- **HIAI**：调用 HIAI DDK 转换工具（支持 `omg`、`atc`、`hiai_model_convert`、`hiai_nn_convert`）将 ONNX 模型转换为 `.om` 格式，仅支持 Linux 平台；支持 FP16 混合精度和 INT8 量化；ONNX opset 超过 18 时自动降级；首次使用时自动下载 HIAI DDK（版本 6.0.1.0）
- **标杆数据**：使用 ONNX Runtime 对原始 ONNX 模型进行推理，生成随机输入数据和对应输出数据，保存为文本格式用于各框架转换后的精度对比验证

## 许可证

[Apache License 2.0](LICENSE)