{"id":51717070,"url":"https://github.com/sipeed/maix_converter_platform","last_synced_at":"2026-07-17T04:36:51.175Z","repository":{"id":370165513,"uuid":"1293292771","full_name":"sipeed/maix_converter_platform","owner":"sipeed","description":null,"archived":false,"fork":false,"pushed_at":"2026-07-08T11:09:56.000Z","size":65,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-08T13:07:27.961Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sipeed.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-07-08T08:23:08.000Z","updated_at":"2026-07-08T11:10:06.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/sipeed/maix_converter_platform","commit_stats":null,"previous_names":["sipeed/maix_converter_platform"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/sipeed/maix_converter_platform","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sipeed%2Fmaix_converter_platform","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sipeed%2Fmaix_converter_platform/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sipeed%2Fmaix_converter_platform/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sipeed%2Fmaix_converter_platform/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sipeed","download_url":"https://codeload.github.com/sipeed/maix_converter_platform/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sipeed%2Fmaix_converter_platform/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35568173,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-17T02:00:06.162Z","response_time":116,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-07-17T04:36:50.498Z","updated_at":"2026-07-17T04:36:51.166Z","avatar_url":"https://github.com/sipeed.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Maix Converter Platform\n\nMaix Converter Platform 是一个面向 MaixCAM / MaixCAM Pro / MaixCam2 的 YOLO 模型转换网页工具。它的目标是把原本需要手动敲很多命令、准备配置文件、进入 Docker、复制结果文件的转换流程，整理成一个更容易使用的 Web 页面。\n\n你只需要上传 YOLO 模型和量化图片数据集，选择 YOLO 版本、输入分辨率和转换参数，平台就会自动完成：\n\n- `.pt` 导出 `.onnx`\n- ONNX 输出节点裁剪\n- 量化图片打包\n- Pulsar2 / TPU-MLIR 转换\n- 生成 `.mud`\n- 生成 MaixCam2 可用的 `.axmodel`，或 MaixCAM / MaixCAM Pro 可用的 `.cvimodel`\n- 打包转换结果 zip\n\n## 当前支持\n\n- 设备：MaixCam2、MaixCAM / MaixCAM Pro\n- 任务：Detect\n- YOLO26\n- YOLO11\n- YOLOv8\n- 输入模型：`.pt` / `.onnx`\n- 量化数据集：`.zip`\n\n## 1. 克隆项目\n\n```bash\ngit clone git@github.com:sipeed/maix_converter_platform.git\ncd maix_converter_platform\n```\n\n如果你使用 HTTPS：\n\n```bash\ngit clone https://github.com/sipeed/maix_converter_platform.git\ncd maix_converter_platform\n```\n\n## 2. 准备 Python 环境\n\n建议使用 conda 单独创建一个环境：\n\n```bash\nconda create -n maix-converter python=3.11\nconda activate maix-converter\n```\n\n安装 Web 服务依赖：\n\n```bash\npip install -r requirements-web.txt\n```\n\n如果你需要上传 `.pt` 模型，让平台自动导出 ONNX，还需要安装 Ultralytics：\n\n```bash\npip install ultralytics onnx\n```\n\n如果你只上传已经导出的 `.onnx`，可以不安装 `ultralytics`。但如果是自训练模型，建议安装 `onnx`，这样平台可以从 ONNX metadata 里读取类别名并写入 `.mud`。\n\n## 3. 安装 Docker\n\n平台使用 Docker 运行 Pulsar2 转换环境。你需要先安装 Docker，并确认当前用户可以执行 `docker`。\n\nWindows 建议安装 Docker Desktop，并启用 WSL2 backend。项目所在磁盘需要能被 Docker Desktop 访问，否则后续转换时可能无法把 `jobs/` 目录挂载进容器。安装完成后打开 PowerShell 或 Anaconda Prompt 检查：\n\n```bash\ndocker --version\ndocker ps\n```\n\nLinux 用户可以参考下面的 Ubuntu / Debian 命令。\n\nUbuntu / Debian 可以参考：\n\n```bash\nsudo apt update\nsudo apt install docker.io\nsudo usermod -aG docker $USER\n```\n\n执行完 `usermod` 后，需要重新登录终端，或者重启系统。然后检查：\n\n```bash\ndocker --version\ndocker ps\n```\n\n如果 `docker ps` 没有权限错误，就说明 Docker 基本可用。\n\nWindows 下如果 Docker 转换阶段报错，优先查看任务目录里的 `convert.log`。如果日志显示路径挂载失败，建议把项目放到纯英文路径下，比如 `C:\\maix_converter_platform`，避免中文目录、特殊符号或过深路径影响 Docker bind mount。\n\n## 4. 安装 Pulsar2 Docker 镜像\n\nMaixCam2 模型转换使用的是 AX620E 工具链。按照 [Sipeed MaixCAM2 模型转换文档](https://wiki.sipeed.com/maixpy/doc/zh/ai_model_converter/maixcam2.html)，推荐把 Pulsar2 放在 Docker 里运行，这样可以避免宿主机 Python、系统库和工具链版本不匹配。\n\n本项目默认调用的 Docker 镜像名是：\n\n```text\npulsar2:6.0\n```\n\n你需要先获取 Pulsar2 Docker 镜像包。镜像包通常是 `.tar` 或 `.tar.gz` 文件，文件名可能因版本不同而变化。\n\n加载镜像：\n\n```bash\ndocker load -i \u003c你的_pulsar2_镜像包.tar\u003e\n```\n\n如果你的镜像包是 `.tar.gz`，也可以直接加载：\n\n```bash\ndocker load -i \u003c你的_pulsar2_镜像包.tar.gz\u003e\n```\n\n加载完成后查看镜像：\n\n```bash\ndocker images\n```\n\n你需要确认列表里有一个可用的 Pulsar2 镜像。如果镜像名已经是 `pulsar2:6.0`，可以直接进入下一步。\n\n如果加载出来的镜像名不是 `pulsar2:6.0`，需要给它打一个 tag。比如 `docker images` 显示的是：\n\n```text\nREPOSITORY   TAG\npulsar2      6.0\n```\n\n那就不需要处理。如果显示的是其他名字，比如：\n\n```text\nREPOSITORY        TAG\nsipeed/pulsar2    latest\n```\n\n则执行：\n\n```bash\ndocker tag sipeed/pulsar2:latest pulsar2:6.0\n```\n\n如果显示的是：\n\n```text\nREPOSITORY   TAG\npulsar2      3.3\n```\n\n则执行：\n\n```bash\ndocker tag pulsar2:3.3 pulsar2:6.0\n```\n\n再次确认：\n\n```bash\ndocker images | grep pulsar2\n```\n\n最后可以简单验证容器里的 Pulsar2 是否可用：\n\n```bash\ndocker run --rm pulsar2:6.0 -c \"pulsar2 version\"\n```\n\n如果输出类似下面这样，就说明镜像基本可用：\n\n```text\nversion: 6.0\ncommit: 48520c11\n```\n\n也可以查看 Pulsar2 支持的子命令：\n\n```bash\ndocker run --rm pulsar2:6.0 -c \"pulsar2 --help | head -20\"\n```\n\n正常会看到类似：\n\n```text\nusage: main.py [-h] {version,build,run,llm_build} ...\n```\n\n\u003e 平台运行转换任务时会自动调用 Docker，不需要你手动进入容器。只有在排查环境问题时，才需要手动运行上面的验证命令。\n\n## 5. 安装 MaixCAM / MaixCAM Pro TPU-MLIR Docker 镜像\n\n如果你只转换 MaixCam2，可以跳过本节。\n\nMaixCAM / MaixCAM Pro 使用算能 TPU-MLIR 工具链，底层需要 `model_transform.py`、`run_calibration.py`、`model_deploy.py` 这些命令。官方推荐在 Docker 里使用 TPU-MLIR，避免宿主机 Python、系统库和工具链版本不匹配。\n\n本项目分两层镜像：\n\n```text\nsophgo/tpuc_dev:v3.4       # 算能基础开发镜像\nmaixcam-tpumlir:v3.4       # 本项目使用的镜像，基于上面镜像预装 tpu_mlir\n```\n\n平台运行 MaixCAM / MaixCAM Pro 转换时，默认调用的是：\n\n```text\nmaixcam-tpumlir:v3.4\n```\n\n所以你需要先准备 `sophgo/tpuc_dev` 基础镜像，再构建一次 `maixcam-tpumlir:v3.4`。\n\n### 5.1 获取 sophgo/tpuc_dev 基础镜像\n\n先尝试直接拉取：\n\n```bash\ndocker pull sophgo/tpuc_dev:latest\n```\n\n如果能成功，查看镜像：\n\n```bash\ndocker images | grep sophgo/tpuc_dev\n```\n\n正常会看到类似：\n\n```text\nsophgo/tpuc_dev   latest   ...\n```\n\n如果 `docker pull` 下载失败，可以参考 [MaixPy MaixCAM 模型转换文档](https://wiki.sipeed.com/maixpy/doc/zh/ai_model_converter/maixcam.html) 和 [TPU-MLIR 官方 README](https://github.com/sophgo/tpu-mlir/blob/master/README_cn.md) 的方式，下载镜像包后导入。\n\nTPU-MLIR 官方 README 当前给出的 v3.4 镜像包示例：\n\n```bash\nwget https://sophon-assets.sophon.cn/sophon-prod-s3/drive/25/04/15/16/tpuc_dev_v3.4.tar.gz\ndocker load -i tpuc_dev_v3.4.tar.gz\n```\n\nMaixPy 文档里也给过类似写法，只是示例链接可能是旧版本：\n\n```bash\nwget https://sophon-file.sophon.cn/sophon-prod-s3/drive/24/06/14/12/sophgo-tpuc_dev-v3.2_191a433358ad.tar.gz\ndocker load -i sophgo-tpuc_dev-v3.2_191a433358ad.tar.gz\n```\n\n本项目建议优先使用 v3.4。导入完成后再次检查：\n\n```bash\ndocker images | grep sophgo/tpuc_dev\n```\n\n如果看到 `sophgo/tpuc_dev`，就说明基础镜像已经有了。镜像 tag 可能是 `latest`，也可能是 `v3.4`，下一步构建时按实际情况选择命令。\n\n镜像包导入成功后，下载的 `.tar.gz` 文件可以删除，Docker 已经把镜像保存到本地镜像库里。\n\n### 5.2 构建本项目使用的 maixcam-tpumlir 镜像\n\n不要进入 `sophgo/tpuc_dev` 容器后手动执行 `pip install tpu_mlir` 来作为长期方案。`docker run --rm` 启动的是临时容器，退出后容器会被删除，刚刚安装的 Python 包也会消失。\n\n正确做法是构建一次本项目提供的派生镜像，把 `tpu_mlir` 固化到镜像里。\n\n如果你的基础镜像是 `sophgo/tpuc_dev:v3.4`，在项目根目录执行：\n\n```bash\ndocker build -f docker/maixcam-tpumlir.Dockerfile -t maixcam-tpumlir:v3.4 .\n```\n\n如果你的基础镜像只有 `sophgo/tpuc_dev:latest`，执行：\n\n```bash\ndocker build \\\n  --build-arg TPUC_DEV_IMAGE=sophgo/tpuc_dev:latest \\\n  -f docker/maixcam-tpumlir.Dockerfile \\\n  -t maixcam-tpumlir:v3.4 \\\n  .\n```\n\n构建完成后检查：\n\n```bash\ndocker images | grep maixcam-tpumlir\n```\n\n正常会看到类似：\n\n```text\nmaixcam-tpumlir   v3.4   ...\n```\n\n### 5.3 验证 TPU-MLIR 命令是否可用\n\n执行：\n\n```bash\ndocker run --rm maixcam-tpumlir:v3.4 model_transform.py --help\n```\n\n正常会看到 `model_transform.py` 的帮助信息，开头类似：\n\n```text\nusage: model_transform.py ...\n```\n\n再检查部署命令：\n\n```bash\ndocker run --rm maixcam-tpumlir:v3.4 model_deploy.py --help\n```\n\n如果也能看到帮助信息，就代表 MaixCAM / MaixCAM Pro 转换环境可用。\n\n### 5.4 常见问题\n\n如果构建时报：\n\n```text\npull access denied for sophgo/tpuc_dev\n```\n\n说明本地没有 `sophgo/tpuc_dev:v3.4`，而 Docker 也没能从网络拉到这个 tag。先用 `docker images | grep sophgo/tpuc_dev` 看你本地实际的 tag。如果只有 `latest`，使用上面带 `--build-arg TPUC_DEV_IMAGE=sophgo/tpuc_dev:latest` 的构建命令。\n\n如果验证时报：\n\n```text\nmodel_transform.py: command not found\n```\n\n说明你运行的不是 `maixcam-tpumlir:v3.4`，或者派生镜像没有构建成功。重新执行 `docker build ... -t maixcam-tpumlir:v3.4 .` 后再验证。\n\n如果下载镜像包很慢，建议先手动用浏览器或 `wget` 下载到本机，再执行 `docker load -i \u003c镜像包文件名\u003e`。`docker load` 成功后，原始 `.tar.gz` 镜像包可以删除。\n\n之后平台会默认使用 `maixcam-tpumlir:v3.4` 进行 MaixCAM / MaixCAM Pro 转换，不需要再手动进入 Docker 安装 `tpu_mlir`。\n\n## 6. 启动网页端\n\n进入项目目录并激活 Python 环境：\n\n```bash\ncd maix_converter_platform\nconda activate maix-converter\n```\n\n启动服务：\n\n```bash\nuvicorn web.app:app --host 0.0.0.0 --port 8000\n```\n\n浏览器打开：\n\n```text\nhttp://127.0.0.1:8000/\n```\n\n如果你是在另一台电脑访问这台转换服务器，把 `127.0.0.1` 换成服务器 IP。\n\n## 7. 准备上传文件\n\n模型文件支持：\n\n- `.pt`\n- `.onnx`\n\n量化数据集必须上传 `.zip` 文件。zip 里面只需要图片，不需要标注文件。\n\n支持图片格式：\n\n- `.jpg`\n- `.jpeg`\n- `.png`\n- `.bmp`\n\nzip 可以直接放图片：\n\n```text\ndataset.zip\n  000001.jpg\n  000002.jpg\n  000003.jpg\n```\n\n也可以有目录：\n\n```text\ndataset.zip\n  images/\n    000001.jpg\n    000002.jpg\n```\n\n建议选择和实际使用场景接近的图片。调试时可以先用 50 到 100 张，正式转换可以适当增加。\n\n## 8. 网页选项说明\n\n### 模型文件\n\n上传你要转换的 YOLO 模型。\n\n- 上传 `.pt`：平台会先用 Ultralytics 导出 ONNX，再继续转换\n- 上传 `.onnx`：平台直接进入 MaixCam2 转换流程\n\n### 量化数据集\n\n上传图片数据集 zip。它用于量化校准，不需要标签文件。\n\n量化数据集越接近真实摄像头画面，转换后的模型效果通常越稳定。\n\n### 模型名称\n\n输出文件的基础名称。比如填写：\n\n```text\nyolo11n\n```\n\n输出结果会类似：\n\n```text\nyolo11n.mud\nyolo11n_npu.axmodel\nyolo11n_vnpu.axmodel\n```\n\n### YOLO 版本\n\n选择模型对应的 YOLO 类型：\n\n- `YOLO26 Detect`\n- `YOLO11 Detect`\n- `YOLOv8 Detect`\n\n这个选项会影响输出节点选择和 `.mud` 里的 `model_type`，必须和模型实际版本对应。\n\n当前支持的是 Detect 任务，不包含 pose、seg、obb。YOLO11 和 YOLOv8 的 `.pt -\u003e .onnx` 导出使用当前 Python 环境里的 `ultralytics` 包；如果上传 `.onnx`，平台会直接使用 ONNX 进入后续转换。\n\n| 选项 | `.mud` model_type | Detect 输出节点 |\n|------|-------------------|-----------------|\n| YOLO26 | `yolo26` | 6 个 `one2one_cv2 / one2one_cv3` 输出 |\n| YOLO11 | `yolo11` | `/model.23/dfl/conv/Conv_output_0` 和 `/model.23/Sigmoid_output_0` |\n| YOLOv8 | `yolov8` | `/model.22/dfl/conv/Conv_output_0` 和 `/model.22/Sigmoid_output_0` |\n\n这里的 YOLO11 / YOLOv8 Detect 节点选择对应 MaixPy 文档里的方案二。它会让更多计算进入模型参与量化，适合 MaixCAM / MaixCAM Pro；当前平台也用这套节点生成 MaixCam2 模型。\n\n### 图片数量\n\n参与量化校准的图片数量。这个数量不能超过 zip 里实际图片数量。\n\n建议：\n\n- 快速测试：`50` 到 `100`\n- 正式转换：根据数据集情况增加\n\n### 宽度 / 高度\n\n模型输入分辨率。\n\n例如填写：\n\n```text\n宽度 640\n高度 480\n```\n\n对应输入形状是 `[1, 3, 480, 640]`。宽高必须和你希望在 MaixCam2 上运行的模型输入尺寸一致。\n\n### 快速模式\n\n快速模式会跳过部分 Pulsar2 精度分析和输出校验，转换速度更快，适合调试流程。\n\n正式部署到 MaixCam2 前，建议关闭快速模式重新转换一次。\n\n## 9. 开始转换和下载结果\n\n填写完选项后，点击“开始转换”。\n\n页面会显示：\n\n- 上传进度\n- 当前任务状态\n- 转换日志\n- 最近任务列表\n- 下载结果按钮\n\n转换成功后，“下载结果”按钮会变成可点击状态。下载得到的是一个 zip，里面包含：\n\n```text\nmodel_name.mud\nmodel_name_npu.axmodel\nmodel_name_vnpu.axmodel\n```\n\n把这几个文件放到 MaixCam2 的同一个目录中，然后在 MaixPy 代码里加载 `.mud`。\n\n如果目标设备选择的是 MaixCAM / MaixCAM Pro，zip 里会包含：\n\n```text\nmodel_name.mud\nmodel_name.cvimodel\n```\n\n把这两个文件放到 MaixCAM / MaixCAM Pro 的同一个目录中，然后在 MaixPy 代码里加载 `.mud`。\n\n下面以 YOLO11 为例：\n\n```python\nfrom maix import camera, display, image, nn, app\n\ndetector = nn.YOLO11(model=\"/root/yolo11/yolo11n.mud\", dual_buff=True)\n\ncam = camera.Camera(detector.input_width(), detector.input_height(), detector.input_format())\ndisp = display.Display()\n\nwhile not app.need_exit():\n    img = cam.read()\n    objs = detector.detect(img, conf_th=0.5, iou_th=0.45)\n    for obj in objs:\n        img.draw_rect(obj.x, obj.y, obj.w, obj.h, color=image.COLOR_RED)\n        msg = f\"{detector.labels[obj.class_id]}: {obj.score:.2f}\"\n        img.draw_string(obj.x, obj.y, msg, color=image.COLOR_RED)\n    disp.show(img)\n```\n\n如果你转换的是其他 YOLO 版本，代码里的模型类需要换成 MaixPy 对应接口。\n\n## 10. 任务目录和自动清理\n\n每次转换都会生成一个任务目录：\n\n```text\njobs/\u003cjob_id\u003e/\n```\n\n里面包含日志、临时文件、输出结果和结果 zip。\n\n平台默认会自动清理旧任务：\n\n- 只清理 `jobs/\u003cjob_id\u003e/`\n- 不清理根目录下的 `inputs/`\n- 不清理 `queued` 或 `running` 任务\n- 已结束任务超过 7 天会被清理\n- 已结束任务超过 30 个时，会优先清理更旧的任务\n- Web 服务启动时清理一次，之后每 6 小时清理一次\n\n可以用环境变量调整：\n\n```bash\nMAIX_JOBS_KEEP_DAYS=7\nMAIX_JOBS_KEEP_COUNT=30\nMAIX_JOBS_CLEAN_INTERVAL_SECONDS=21600\n```\n\n关闭自动清理：\n\n```bash\nMAIX_JOBS_AUTO_CLEAN=0\n```\n\n## 常见问题\n\n### 为什么需要量化数据集？\n\nMaixCam2 使用 NPU 量化模型。转换工具需要用一批图片统计模型中间层的数据范围，然后把浮点模型转换成适合 NPU 运行的量化模型。\n\n### `.pt` 和 `.onnx` 应该上传哪个？\n\n如果你只有训练后的 `.pt`，可以直接上传 `.pt`。\n\n如果你已经有确认可用的 `.onnx`，上传 `.onnx` 会更直接。\n\n### 自训练模型类别数不对怎么办？\n\n平台会优先从 Ultralytics `.pt` 或 `.onnx` metadata 里读取类别名，并写入 `.mud`。\n\n如果 MaixCam2 运行时报 `get tensor idx error`，或者模型信息里的 `labels num` 和你的训练类别数不一致，优先检查导出的模型 metadata 和 `.mud` 里的 `labels`。\n\n### 转换失败怎么办？\n\n先看网页里的实时日志。每个任务目录里也会保留：\n\n```text\napi.log\nconvert.log\njob.json\n```\n\n这些文件可以帮助定位是上传、ONNX 导出、输出节点、量化数据集还是 Pulsar2 转换阶段出错。\n\n## 开发文档\n\n转换节点、Web API、任务目录结构和后续开发计划放在：\n\n```text\ndocs/DEVELOPMENT.md\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsipeed%2Fmaix_converter_platform","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsipeed%2Fmaix_converter_platform","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsipeed%2Fmaix_converter_platform/lists"}