diff --git a/docs/doc/assets/maixhub_converter_create_job.jpg b/docs/doc/assets/maixhub_converter_create_job.jpg new file mode 100644 index 00000000..288ec320 Binary files /dev/null and b/docs/doc/assets/maixhub_converter_create_job.jpg differ diff --git a/docs/doc/assets/maixhub_converter_download_result.jpg b/docs/doc/assets/maixhub_converter_download_result.jpg new file mode 100644 index 00000000..9ae76742 Binary files /dev/null and b/docs/doc/assets/maixhub_converter_download_result.jpg differ diff --git a/docs/doc/assets/maixhub_converter_job_done.jpg b/docs/doc/assets/maixhub_converter_job_done.jpg new file mode 100644 index 00000000..c57ea232 Binary files /dev/null and b/docs/doc/assets/maixhub_converter_job_done.jpg differ diff --git a/docs/doc/assets/maixhub_converter_labels.jpg b/docs/doc/assets/maixhub_converter_labels.jpg new file mode 100644 index 00000000..d03d43e3 Binary files /dev/null and b/docs/doc/assets/maixhub_converter_labels.jpg differ diff --git a/docs/doc/assets/maixvision_create_my_models.jpg b/docs/doc/assets/maixvision_create_my_models.jpg new file mode 100644 index 00000000..35a245e2 Binary files /dev/null and b/docs/doc/assets/maixvision_create_my_models.jpg differ diff --git a/docs/doc/assets/maixvision_enter_my_models.jpg b/docs/doc/assets/maixvision_enter_my_models.jpg new file mode 100644 index 00000000..ad48b38a Binary files /dev/null and b/docs/doc/assets/maixvision_enter_my_models.jpg differ diff --git a/docs/doc/assets/maixvision_file_manager.jpg b/docs/doc/assets/maixvision_file_manager.jpg new file mode 100644 index 00000000..b4b58c16 Binary files /dev/null and b/docs/doc/assets/maixvision_file_manager.jpg differ diff --git a/docs/doc/assets/maixvision_upload_model_files.jpg b/docs/doc/assets/maixvision_upload_model_files.jpg new file mode 100644 index 00000000..56b3c549 Binary files /dev/null and b/docs/doc/assets/maixvision_upload_model_files.jpg differ diff --git a/docs/doc/en/ai_model_converter/ai_model_deploy.md b/docs/doc/en/ai_model_converter/ai_model_deploy.md index e5990450..b8059ade 100644 --- a/docs/doc/en/ai_model_converter/ai_model_deploy.md +++ b/docs/doc/en/ai_model_converter/ai_model_deploy.md @@ -4,12 +4,16 @@ title: AI Model Download, Debugging, and Deployment Guide ## Choose a Model Deployment Workflow -Before deploying a local model on MaixCAM / MaixCAM-Pro / MaixCAM2, first identify the model source, target device, and deployment path. Choose the workflow that matches your current resources instead of starting with ONNX conversion immediately. +Before deploying a local model on MaixCAM / MaixCAM-Pro / MaixCAM2, first identify the model source, target device, and deployment path. Choose the workflow that matches your current resources: do not retrain a model if a ready-made one already works; train first when you need custom classes; after obtaining a `.pt` file, export it to ONNX and prefer the online conversion platform to generate deployable model files. Manual command-line conversion is an advanced workflow for custom conversion parameters or deeper debugging. | Goal | Recommended workflow | Documentation | | --- | --- | --- | | Use built-in or ready-made models | Use built-in models first. For more resolutions or class sets, choose the matching device platform in [MaixHub Model Zoo](https://maixhub.com/model/zoo). MaixCAM / MaixCAM-Pro model packages usually include `.mud` and `.cvimodel` files, while MaixCAM2 model packages usually include `.mud` and `.axmodel` files. Place the files from the same package in the same directory on the device | [Model and dataset sources](../pro/datasets.md) | | Train a custom recognition target | Use MaixHub online training to complete data collection, annotation, training, and deployment | [MaixHub online training](../vision/maixhub_train.md) | -| Deploy an ONNX model | Choose the conversion workflow based on the target device: convert to `.mud` + `.cvimodel` for MaixCAM / MaixCAM-Pro, or to `.mud` + `.axmodel` for MaixCAM2 before deployment | [MaixCAM model conversion](./maixcam.md) / [MaixCAM2 model conversion](./maixcam2.md) | +| Train a YOLO model offline | Prepare the dataset and train the YOLO model on a computer. Use the recommended Ultralytics versions for training and export. After training produces a `.pt` file, export it to an ONNX model with a fixed input size | [YOLO model offline training](../vision/customize_model_yolo.md) | +| Convert a YOLO model online | Upload the ONNX model and a ZIP archive containing 20-100 calibration images. The platform generates `.mud` + `.cvimodel` for MaixCAM / MaixCAM-Pro, or `.mud` + `.axmodel` for MaixCAM2 | [Online graphical model conversion platform](./online_converter.md) | +| Convert an ONNX model manually | Use command-line conversion when you need custom output nodes, conversion parameters, toolchain configuration, or when online conversion does not meet the requirement | [MaixCAM2 model conversion](./maixcam2.md) / [MaixCAM model conversion](./maixcam.md) / [Trim ONNX model output nodes](./onnx_export.md) | +| Self-host the conversion platform | Use this when uploading models to the online service is not suitable, or when you need intranet deployment, a self-managed conversion server, or platform-source debugging | [Self-hosted graphical model conversion platform](./web_converter.md) | +| Port a new AI model | Use this for model types not yet wrapped by MaixPy, where you need to handle preprocessing, postprocessing, MUD description, and inference code yourself | [Port a new AI model](../pro/customize_model.md) | After choosing your workflow, continue with the corresponding document. diff --git a/docs/doc/en/ai_model_converter/online_converter.md b/docs/doc/en/ai_model_converter/online_converter.md new file mode 100644 index 00000000..21971740 --- /dev/null +++ b/docs/doc/en/ai_model_converter/online_converter.md @@ -0,0 +1,190 @@ +--- +title: Convert YOLO Models Online +--- + +## Introduction + +The MaixCAM model conversion tool is a Web model-conversion service hosted by Sipeed. You do not need to install Docker, Pulsar2, or TPU-MLIR locally. Prepare the ONNX model file and calibration image dataset, create a conversion job on the page, wait for the platform to finish, and download the result. + +The online platform is suitable for quickly converting common YOLO Detect models and generating model files that can be deployed directly on MaixCAM, MaixCAM Pro, or MaixCAM2. If you need private intranet deployment, a self-managed conversion environment, or cannot upload model files to the online service, see [Self-hosted Graphical Model Conversion Platform](./web_converter.md). + +## Current Support + +The platform currently supports the following devices and models: + +| Item | Supported | +| --- | --- | +| Target devices | MaixCAM, MaixCAM Pro, MaixCAM2 | +| Model types | YOLO26, YOLO11, YOLOv8, YOLOv5u | +| Tasks | Object detection (Detect) | +| Input models | `.onnx` | +| Calibration dataset | A `.zip` file containing 20-100 `.jpg`, `.png`, or `.bmp` images, no larger than 100MB | + +> Classification, segmentation, pose estimation, and OBB tasks are not currently supported. For other models or custom conversion parameters, use the manual conversion methods described in the previous guides, or self-host the conversion platform and modify it as needed. +> +> YOLOv5u models belong to the newer Ultralytics `ultralytics` repository. Use `nn.YOLOv8` directly in the inference code, not `nn.YOLOv5`. + +## Open the Online Platform + +Open the online model conversion platform in a browser: + +[MaixHub Converter tool](https://maixhub.com/toolbox) + +## Export a PT Model to ONNX + +The online platform only accepts `.onnx` models. If your training result is a `.pt` weight file, export it to ONNX on your computer before uploading it to the platform. + +For YOLO26, YOLO11, YOLOv8, or YOLOv5u models trained with Ultralytics, use `ultralytics==8.4.104` for both training and ONNX export. Pinning this version avoids model-structure or output-node differences from other Ultralytics releases, which may cause conversion failures later. + +Install the specified export tools first: + +```shell +pip install ultralytics==8.4.104 ultralytics-thop onnx onnxslim onnxruntime +``` + +Then choose the input resolution for the target device. The previous model-conversion guides recommend `320x224` for MaixCAM, and `640x480` or `320x240` for MaixCAM2. These resolutions are described as "width x height", while the Ultralytics `imgsz` argument is written as "height,width". + +For MaixCAM, export an ONNX model with `320x224` input: + +```shell +yolo export model=best.pt format=onnx imgsz=224,320 opset=17 simplify=True +``` + +For MaixCAM2, export an ONNX model with `640x480` input: + +```shell +yolo export model=best.pt format=onnx imgsz=480,640 opset=17 simplify=True +``` + +To improve runtime speed on MaixCAM2 with a smaller input, you can also export `320x240`: + +```shell +yolo export model=best.pt format=onnx imgsz=240,320 opset=17 simplify=True +``` + +Replace `model` with the path to your `.pt` file, and set `imgsz` to the input resolution you will use on the device. After export, `best.onnx` is usually generated in the same directory. + +After exporting, use Netron or another ONNX viewer to confirm that the model has a fixed input shape and that it matches the width and height entered on the platform. + +## Prepare the Model and Calibration Dataset + +The platform only accepts `.onnx` model files. It uses the ONNX model's own static input shape for later processing and conversion, and does not resize the model after upload. Decide the final deployment input resolution when exporting the ONNX model. + +The calibration dataset must be packaged as a `.zip` file containing images only; annotation files are not required. The archive must contain 20-100 images, supported image formats are `.jpg`, `.png`, and `.bmp`, and the uploaded ZIP file must be no larger than 100MB. + +Images may be stored directly in the archive: + +```text +dataset.zip + 000001.jpg + 000002.jpg + 000003.jpg +``` + +Calibration images should resemble the model's actual deployment environment. For example, if the model will process camera images, prefer images captured by a similar camera under realistic conditions. Prepare 20-50 images for a quick workflow check, then increase the number toward 100 for final conversion as needed. + +## Create a Conversion Job + +Open the Web page and complete the form from top to bottom: + +![Create a MaixHub conversion job](../../assets/maixhub_converter_create_job.jpg) + +The platform usually detects the labels stored in the model automatically. If it does not, enter the labels manually. + +![Set MaixHub model labels](../../assets/maixhub_converter_labels.jpg) + +Click **Start Conversion** after completing the form. The page displays upload progress, the current job status, and live conversion logs. Conversion time depends on the model size, calibration image count, and the server job queue. + +Wait for the conversion to complete. + +![MaixHub conversion job completed](../../assets/maixhub_converter_job_done.jpg) + +## Download the Conversion Result + +After a successful conversion, the **Download Result** button becomes available. Click it to download a ZIP archive containing the generated model files. + +![Download MaixHub conversion result](../../assets/maixhub_converter_download_result.jpg) + +A MaixCAM2 result normally contains: + +```text +model_name.mud +model_name_npu.axmodel +model_name_vnpu.axmodel +``` + +A MaixCAM or MaixCAM Pro result normally contains: + +```text +model_name.mud +model_name.cvimodel +``` + +## Transfer the Model Files to MaixCAM / MaixCAM Pro / MaixCAM2 + +1. Open MaixVision and connect to the device. + +2. Open the device file manager. + +![MaixVision device file manager](../../assets/maixvision_file_manager.jpg) + +3. Create a `my_models` folder under the `root` directory to store the converted model. + +![Create my_models folder in MaixVision](../../assets/maixvision_create_my_models.jpg) + +4. Click the `my_models` folder to enter it. + +![Enter my_models folder in MaixVision](../../assets/maixvision_enter_my_models.jpg) + +5. Upload the converted files to `my_models`. For MaixCAM / MaixCAM Pro, upload the `.mud` and `.cvimodel` files. For MaixCAM2, upload the `.mud` and `.axmodel` files. + +![Upload model files in MaixVision](../../assets/maixvision_upload_model_files.jpg) + +6. Write the inference code. + +The following example uses YOLOv8. + +Assume the `.mud` file you just obtained is `model_4090.mud`. + +```python +from maix import app, camera, display, image, nn + +detector = nn.YOLOv8(model="/root/my_models/model_4090.mud", dual_buff=True) +cam = camera.Camera(detector.input_width(), detector.input_height(), detector.input_format()) +disp = display.Display() + +while not app.need_exit(): + img = cam.read() + objs = detector.detect(img, conf_th=0.5, iou_th=0.45) + for obj in objs: + img.draw_rect(obj.x, obj.y, obj.w, obj.h, color=image.COLOR_RED) + msg = f"{detector.labels[obj.class_id]}: {obj.score:.2f}" + img.draw_string(obj.x, obj.y, msg, color=image.COLOR_RED) + disp.show(img) +``` + +For YOLO26 or YOLO11, replace `nn.YOLOv8` with the corresponding MaixPy model interface. + +## Notes + +- Confirm the source and license of the model before uploading it. Do not upload models you are not allowed to use. +- The online platform only accepts ONNX models. If you have a `.pt` weight file, export it to ONNX first. +- The calibration dataset must contain 20-100 `.jpg`, `.png`, or `.bmp` images, and the ZIP file must be no larger than 100MB. +- If the model or dataset contains sensitive information, use the [self-hosted graphical model conversion platform](./web_converter.md) on your own server. +- Conversion jobs may wait in a queue. Runtime depends on model size, calibration image count, and server load. +- Download the result promptly after conversion succeeds to avoid job expiration or cleanup. +- The online platform mainly targets common YOLO Detect conversion. Use self-hosting if you need to modify Docker images, toolchain parameters, or result-generation logic. + +## FAQ + +### Not Enough Calibration Images + +The **Image Count** value must be between 20 and 100 and cannot exceed the number of valid images in the uploaded ZIP archive. If the archive contains only 50 images, do not set the value to 100. + +### Incorrect Classes in a Custom Model + +The platform tries to read class names from ONNX metadata. If the deployed model reports incorrect class names or counts, check whether `labels` in the generated `.mud` file matches the trained model. + +### Conversion Job Failed + +Check the live log on the page first and confirm that the model format, YOLO version, input resolution, and calibration image count are correct. If the log reports unsupported operators, abnormal output nodes, or quantization failure, go back to the training, ONNX export, or manual conversion flow for diagnosis. diff --git a/docs/doc/en/ai_model_converter/web_converter.md b/docs/doc/en/ai_model_converter/web_converter.md index 6e1678f6..fb897926 100644 --- a/docs/doc/en/ai_model_converter/web_converter.md +++ b/docs/doc/en/ai_model_converter/web_converter.md @@ -1,9 +1,11 @@ --- -title: Graphical Model Conversion Platform +title: Self-hosted Graphical Model Conversion Platform --- ## Introduction +If you only need to convert common YOLO Detect models, use the [online graphical model conversion platform](./online_converter.md) first. It does not require installing Python, Docker, or model-conversion images on your computer. Use this self-hosted guide when you need private intranet deployment, full control of the conversion server, platform-source debugging, or when uploading model files to the online service is not suitable. + After reading the previous model-conversion guides, have all those commands started to blur together? Exporting ONNX, locating output nodes, trimming the model, preparing calibration images, editing configuration files, and running Docker commands—missing a single parameter can send you back through the whole process. Sometimes converting a trained `.pt` model feels harder than training it in the first place. Do not worry, and put away that command-line checklist. Maix Converter Platform brings the complicated steps together in a Web interface. Upload the model and calibration dataset, select the target device, YOLO version, and input resolution, and the platform will handle model export, node processing, quantization, MUD generation, and result packaging automatically. @@ -24,7 +26,7 @@ The platform currently supports the following devices and models: > Classification, segmentation, pose estimation, and OBB tasks are not currently supported. For other models or custom conversion parameters, use the manual conversion methods described in the previous guides. -## Get the Conversion Platform +## Get the Self-hosted Platform Maix Converter Platform is open source. Its source code is available at [github.com/sipeed/maix_converter_platform](https://github.com/sipeed/maix_converter_platform). diff --git a/docs/doc/en/sidebar.yaml b/docs/doc/en/sidebar.yaml index 361b6173..3d7db365 100644 --- a/docs/doc/en/sidebar.yaml +++ b/docs/doc/en/sidebar.yaml @@ -140,26 +140,28 @@ items: - label: Local deployment of AI models items: - file: ai_model_converter/ai_model_deploy.md - label: AI model download and deployment guide + label: AI model download, debugging, and deployment guide - file: pro/datasets.md label: Where to find models & datasets - - file: vision/maixhub_train.md - label: MaixHub online AI training - file: vision/customize_model_yolo.md label: YOLO model offline training - - file: ai_model_converter/maixcam2.md - label: Convert ONNX model for MaixCAM2 - - file: ai_model_converter/maixcam.md - label: Convert ONNX model for MaixCAM - - file: ai_model_converter/onnx_export.md - label: Trim ONNX model output nodes - - file: ai_model_converter/web_converter.md - label: Convert YOLO models with Web UI - - file: pro/customize_model.md - label: Port a new AI model - - - + - file: ai_model_converter/online_converter.md + label: MaixHub online YOLO conversion + - file: vision/maixhub_train.md + label: MaixHub online YOLO training + - label: Advanced Operations + collapsed: true + items: + - file: ai_model_converter/maixcam2.md + label: Convert ONNX model for MaixCAM2 + - file: ai_model_converter/maixcam.md + label: Convert ONNX model for MaixCAM + - file: ai_model_converter/onnx_export.md + label: Trim ONNX model output nodes + - file: ai_model_converter/web_converter.md + label: Self-host the Web converter + - file: pro/customize_model.md + label: Port a new AI model - label: Network items: - file: network/network_settings.md diff --git a/docs/doc/zh/ai_model_converter/ai_model_deploy.md b/docs/doc/zh/ai_model_converter/ai_model_deploy.md index 5e6439e3..7edeb34d 100644 --- a/docs/doc/zh/ai_model_converter/ai_model_deploy.md +++ b/docs/doc/zh/ai_model_converter/ai_model_deploy.md @@ -4,12 +4,16 @@ title: AI 模型下载、调试和部署指南 ## 选择模型部署方式 -首次进行 MaixCAM / MaixCAM-Pro / MaixCAM2 本地模型部署时，建议先明确模型来源、目标设备和部署方式。请根据当前已有资源选择对应流程，避免一开始就直接进行 ONNX 转换。 +首次进行 MaixCAM / MaixCAM-Pro / MaixCAM2 本地模型部署时，建议先明确模型来源、目标设备和部署方式。请根据当前已有资源选择对应流程：能直接使用现成模型时不要重新训练；需要识别自定义目标时先训练模型；训练得到 `.pt` 后先导出 ONNX，再优先使用在线转换平台生成设备可部署的模型文件。手动命令行转换适合需要自定义转换参数或排查复杂问题的进阶场景。 | 使用目标 | 建议流程 | 查看文档 | | --- | --- | --- | | 使用预置或现成模型 | 优先使用系统预置模型；如需更多分辨率或类别，可在 [MaixHub 模型库](https://maixhub.com/model/zoo) 选择对应设备平台。MaixCAM / MaixCAM-Pro 模型包通常包含 `.mud` 与 `.cvimodel`，MaixCAM2 模型包通常包含 `.mud` 与 `.axmodel`，部署时放入设备同一目录 | [模型与数据集来源](../pro/datasets.md) | | 训练自定义识别目标 | 使用 MaixHub 在线训练完成数据采集、标注、训练与部署 | [MaixHub 在线训练](../vision/maixhub_train.md) | -| 部署 ONNX 模型 | 根据目标设备选择转换流程：MaixCAM / MaixCAM-Pro 转换为 `.mud` + `.cvimodel`，MaixCAM2 转换为 `.mud` + `.axmodel` 后再部署 | [MaixCAM 模型转换](./maixcam.md) / [MaixCAM2 模型转换](./maixcam2.md) | +| 离线训练 YOLO 模型 | 在电脑上准备数据集并训练 YOLO 模型，训练和导出建议使用指定版本的 Ultralytics。训练得到 `.pt` 后，先按文档导出固定输入尺寸的 `.onnx` | [离线训练 YOLO 模型](../vision/customize_model_yolo.md) | +| 在线转换 YOLO 模型 | 上传 ONNX 模型和 20～100 张量化图片组成的 ZIP 包，在线生成 MaixCAM / MaixCAM-Pro 的 `.mud` + `.cvimodel`，或 MaixCAM2 的 `.mud` + `.axmodel` | [在线图形化模型转换平台](./online_converter.md) | +| 手动转换 ONNX 模型 | 需要自定义输出节点、转换参数、工具链配置，或在线转换无法满足需求时，再使用命令行手动转换流程 | [MaixCAM2 模型转换](./maixcam2.md) / [MaixCAM 模型转换](./maixcam.md) / [裁剪 ONNX 模型输出节点](./onnx_export.md) | +| 私有部署转换平台 | 不方便上传模型到在线服务，或需要内网部署、自管转换服务器、调试平台源码时使用 | [私有部署图形化模型转换平台](./web_converter.md) | +| 移植新的 AI 模型 | MaixPy 尚未封装的模型类型，需要自行处理前后处理、MUD 描述和推理代码 | [移植新的 AI 模型](../pro/customize_model.md) | 选定流程后，进入对应文档继续操作即可。 diff --git a/docs/doc/zh/ai_model_converter/online_converter.md b/docs/doc/zh/ai_model_converter/online_converter.md new file mode 100644 index 00000000..3f3bfcb5 --- /dev/null +++ b/docs/doc/zh/ai_model_converter/online_converter.md @@ -0,0 +1,188 @@ +--- +title: 在线转换 YOLO 模型 +--- + +## 简介 + +MaixCAM 模型转换工具是 Sipeed 部署好的网页模型转换服务。你不需要在本机安装 Docker、Pulsar2 或 TPU-MLIR 环境，只需要准备 ONNX 模型文件和量化图片数据集，在网页中创建转换任务，等待平台完成转换后下载结果即可。 + +在线平台适合快速转换常见 YOLO Detect 模型，并生成可以直接在 MaixCAM、MaixCAM Pro 或 MaixCAM2 上部署的模型文件。如果需要内网部署、自管转换环境，或不方便上传模型文件到在线服务，请参考[私有部署图形化模型转换平台](./web_converter.md)。 + +## 当前支持 + +目前平台支持的设备和模型如下： + +| 项目 | 支持范围 | +| --- | --- | +| 目标设备 | MaixCAM、MaixCAM Pro、MaixCAM2 | +| 模型类型 | YOLO26、YOLO11、YOLOv8、YOLOv5u | +| 任务类型 | 目标检测（Detect） | +| 输入模型 | `.onnx` | +| 量化数据集 | 包含 20～100 张 `.jpg`、`.png` 或 `.bmp` 图片的 `.zip` 文件，不能大于 100MB | + +> 当前暂不支持分类、分割、姿态检测和 OBB 等任务。其他模型或者需要自定义转换参数时，请使用前面介绍的手动转换方法，或自行私有部署转换平台后按需修改。 +> +> YOLOv5u 属于 Ultralytics 新版 `ultralytics` 仓库中的模型，推理代码直接使用 `nn.YOLOv8` 即可，不要使用 `nn.YOLOv5`。 + +## 打开在线平台 + +在浏览器中打开在线模型转换平台： + +[MaixHub Converter tool](https://maixhub.com/toolbox) + +## 将 PT 模型导出为 ONNX + +在线平台只支持上传 `.onnx` 模型。如果你训练得到的是 `.pt` 权重文件，需要先在电脑上导出为 ONNX，再上传到平台转换。 + +对于使用 Ultralytics 训练得到的 YOLO26、YOLO11、YOLOv8 或 YOLOv5u 模型，训练和导出 ONNX 都建议固定使用 `ultralytics==8.4.104`，避免不同版本导出的模型结构或输出节点不一致，导致后续转换失败。 + +先安装指定版本的导出工具： + +```shell +pip install ultralytics==8.4.104 ultralytics-thop onnx onnxslim onnxruntime -i https://pypi.tuna.tsinghua.edu.cn/simple +``` + +然后根据目标设备选择合适的输入分辨率。前面模型转换文档中推荐 MaixCAM 使用 `320x224`，MaixCAM2 使用 `640x480` 或 `320x240`。这里的分辨率按“宽 x 高”描述，而 Ultralytics 导出命令中的 `imgsz` 按“高,宽”填写。 + +以 MaixCAM 为例，导出 `320x224` 输入的 ONNX： + +```shell +yolo export model=best.pt format=onnx imgsz=224,320 opset=17 simplify=True +``` + +以 MaixCAM2 为例，导出 `640x480` 输入的 ONNX： + +```shell +yolo export model=best.pt format=onnx imgsz=480,640 opset=17 simplify=True +``` + +如果希望 MaixCAM2 使用更小分辨率提高运行速度，也可以导出 `320x240` 输入的 ONNX： + +```shell +yolo export model=best.pt format=onnx imgsz=240,320 opset=17 simplify=True +``` + +其中 `model` 替换为你的 `.pt` 文件路径，`imgsz` 设置为模型部署时使用的输入分辨率。导出完成后通常会在同目录生成 `best.onnx`。 + +导出后建议用 Netron 或其它 ONNX 查看工具确认模型输入尺寸是固定尺寸，并且与后续在平台中填写的宽度、高度一致。 + +## 准备模型和量化数据集 + +模型文件只支持 `.onnx` 格式。平台会使用 ONNX 模型自身的静态输入尺寸进行后续处理和转换，不会在上传后重新调整模型尺寸。建议在导出 ONNX 时就确定好最终部署使用的输入分辨率。 + +量化数据集需要打包为 `.zip` 文件，压缩包中只需要图片，不需要标注文件。图片数量需要在 20～100 张之间，支持 `.jpg`、`.png` 和 `.bmp` 格式，上传的 ZIP 文件不能大于 100MB。 + +压缩包中可以直接放置图片： + +```text +dataset.zip + 000001.jpg + 000002.jpg + 000003.jpg +``` + +量化图片应该尽量接近模型部署后的真实使用场景。例如模型将用于摄像头拍摄，就优先使用同类摄像头在实际环境中采集的图片。建议先准备 20～50 张图片快速验证流程，正式转换时再根据数据集情况增加到接近 100 张。 + +## 创建转换任务 + +打开网页后，按照页面从上到下填写转换参数： + +![MaixHub 创建转换任务](../../assets/maixhub_converter_create_job.jpg) + +平台一般会自己识别出模型里面的标签，如果没有的话就手动填上去。 + +![MaixHub 模型标签设置](../../assets/maixhub_converter_labels.jpg) + +填写完成后点击“开始转换”。页面会显示文件上传进度、当前任务状态和实时转换日志。转换时间与模型大小、量化图片数量以及服务器任务排队情况有关，请耐心等待。 + +等待转换完成 + +![MaixHub 转换任务完成](../../assets/maixhub_converter_job_done.jpg) + +## 下载转换结果 + +![MaixHub 下载转换结果](../../assets/maixhub_converter_download_result.jpg) + +MaixCAM2 的结果通常包含： + +```text +model_name.mud +model_name_npu.axmodel +model_name_vnpu.axmodel +``` + +MaixCAM 和 MaixCAM Pro 的结果通常包含： + +```text +model_name.mud +model_name.cvimodel +``` + +## 把模型文件传送到 MaixCAM / MaixCAM Pro / MaixCAM2 + +1. 打开 MaixVision，连接上设备。 + +2. 点击设备文件管理器。 + +![MaixVision 设备文件管理器](../../assets/maixvision_file_manager.jpg) + +3. 在 `root` 目录新建一个 `my_models` 文件夹，用来保存刚刚转换的模型。 + +![MaixVision 新建 my_models 文件夹](../../assets/maixvision_create_my_models.jpg) + +4. 单击 `my_models` 文件夹，进入到 `my_models` 文件夹。 + +![MaixVision 进入 my_models 文件夹](../../assets/maixvision_enter_my_models.jpg) + +5. 把转换出来的文件上传到 `my_models` 目录。如果是 MaixCAM / MaixCAM Pro，上传 `.mud` 和 `.cvimodel` 文件；如果是 MaixCAM2，上传 `.mud` 和 `.axmodel` 文件。 + +![MaixVision 上传模型文件](../../assets/maixvision_upload_model_files.jpg) + +6. 编写推理代码。 + +下面以 YOLOv8 为例： + +假设你刚刚得到的 `.mud` 文件是 `model_4090.mud`。 + +```python +from maix import app, camera, display, image, nn + +detector = nn.YOLOv8(model="/root/my_models/model_4090.mud", dual_buff=True) +cam = camera.Camera(detector.input_width(), detector.input_height(), detector.input_format()) +disp = display.Display() + +while not app.need_exit(): + img = cam.read() + objs = detector.detect(img, conf_th=0.5, iou_th=0.45) + for obj in objs: + img.draw_rect(obj.x, obj.y, obj.w, obj.h, color=image.COLOR_RED) + msg = f"{detector.labels[obj.class_id]}: {obj.score:.2f}" + img.draw_string(obj.x, obj.y, msg, color=image.COLOR_RED) + disp.show(img) +``` + +如果转换的是 YOLO26 或 YOLO11，请将示例中的 `nn.YOLOv8` 换成对应的 MaixPy 模型接口。 + +## 注意事项 + +- 上传模型前请确认模型来源和授权，避免上传没有使用权限的模型文件。 +- 在线平台只接受 ONNX 模型；如果手上是 `.pt` 权重，请先导出 ONNX。 +- 量化数据集需要包含 20～100 张 `.jpg`、`.png` 或 `.bmp` 图片，ZIP 文件大小不能超过 100MB。 +- 如果模型或数据集包含敏感信息，建议使用[私有部署图形化模型转换平台](./web_converter.md)在自有服务器中转换。 +- 转换任务可能需要排队，耗时与模型大小、量化图片数量和服务器负载有关。 +- 转换成功后请及时下载结果，避免任务过期或被清理。 +- 在线平台主要面向通用 YOLO Detect 转换；需要修改 Docker 镜像、工具链参数或生成逻辑时，请使用私有部署方式。 + +## 常见问题 + +### 量化图片数量不足 + +页面中的“图片数量”需要在 20～100 之间，并且不能大于 ZIP 文件中实际包含的有效图片数量。如果只准备了 50 张图片，就不要将图片数量设置为 100。 + +### 自训练模型的类别不正确 + +平台会尝试从 ONNX metadata 中读取类别名称。如果模型运行后类别数量或名称不正确，请检查生成的 `.mud` 文件中 `labels` 的内容是否与训练模型一致。 + +### 转换任务失败 + +先查看页面中的实时日志，确认模型格式、YOLO 版本、输入分辨率、量化图片数量是否正确。如果日志中提示模型算子不支持、输出节点异常或量化失败，需要回到训练、导出 ONNX 或手动转换流程中排查。 diff --git a/docs/doc/zh/ai_model_converter/web_converter.md b/docs/doc/zh/ai_model_converter/web_converter.md index bb0b5aee..ae28efc8 100644 --- a/docs/doc/zh/ai_model_converter/web_converter.md +++ b/docs/doc/zh/ai_model_converter/web_converter.md @@ -1,9 +1,11 @@ --- -title: 图形化模型转换平台 +title: 私有部署图形化模型转换平台 --- ## 简介 +如果只是转换常见的 YOLO Detect 模型，推荐优先使用[在线图形化模型转换平台](./online_converter.md)，无需在本机安装 Python、Docker 和模型转换镜像。只有在需要内网部署、转换服务器自管、调试平台源码，或不方便上传模型文件到在线服务时，再参考本文进行私有部署。 + 看完前面的模型转换教程，是不是已经被一长串命令绕晕了？导出 ONNX、查找输出节点、裁剪模型、准备量化数据集、修改配置文件、运行 Docker……步骤一个接一个，少写一个参数都可能要从头检查。好不容易训练出了 `.pt` 模型，却发现“转换模型”似乎比“训练模型”还让人头大。 别担心，也不用再抱着命令行逐个参数对答案了！Maix Converter Platform 把这些复杂步骤都搬进了一个 Web 页面。你只需要上传模型和量化图片数据集，再选择目标设备、YOLO 版本和输入分辨率，剩下的模型导出、节点处理、量化转换、MUD 文件生成和结果打包，就交给平台自动完成。 @@ -24,7 +26,7 @@ title: 图形化模型转换平台 > 当前暂不支持分类、分割、姿态检测和 OBB 等任务。其他模型或者需要自定义转换参数时，请使用前面介绍的手动转换方法。 -## 获取转换平台 +## 获取私有部署平台 Maix Converter Platform 是一个开源工具，源代码在 [github.com/sipeed/maix_converter_platform](https://github.com/sipeed/maix_converter_platform)。 diff --git a/docs/doc/zh/sidebar.yaml b/docs/doc/zh/sidebar.yaml index c8ba3f3c..633ed4e4 100644 --- a/docs/doc/zh/sidebar.yaml +++ b/docs/doc/zh/sidebar.yaml @@ -140,23 +140,28 @@ items: - label: AI 模型本地部署 items: - file: ai_model_converter/ai_model_deploy.md - label: AI 模型下载和部署指南 + label: AI 模型下载、调试和部署指南 - file: pro/datasets.md label: 哪里找模型和数据集 - - file: vision/maixhub_train.md - label: MaixHub 在线训练 AI 模型 - file: vision/customize_model_yolo.md label: 离线训练 YOLO 模型 - - file: ai_model_converter/maixcam2.md - label: ONNX 模型转换为 MaixCAM2 模型 - - file: ai_model_converter/maixcam.md - label: ONNX 模型转换为 MaixCAM 模型 - - file: ai_model_converter/onnx_export.md - label: 裁剪 ONNX 模型输出节点 - - file: ai_model_converter/web_converter.md - label: 使用网页工具转换 YOLO 模型 - - file: pro/customize_model.md - label: 移植新的 AI 模型 + - file: ai_model_converter/online_converter.md + label: MaixHub 在线转换 YOLO 模型 + - file: vision/maixhub_train.md + label: MaixHub 在线训练 YOLO 模型 + - label: 进阶操作 + collapsed: true + items: + - file: ai_model_converter/maixcam2.md + label: ONNX 模型转换为 MaixCAM2 模型 + - file: ai_model_converter/maixcam.md + label: ONNX 模型转换为 MaixCAM 模型 + - file: ai_model_converter/onnx_export.md + label: 裁剪 ONNX 模型输出节点 + - file: ai_model_converter/web_converter.md + label: 私有部署网页转换平台 + - file: pro/customize_model.md + label: 移植新的 AI 模型 # - label: YOLO模型零算法基础入门使用