auto-vision

name auto-vision description 边缘 AI 视觉开发统一框架，覆盖 K230 / MaixCAM-Pro / MaixCAM2 / RK3588 / Jetson Orin Nano Super 五平台。包含模型转换（ONNX→kmodel/cvimodel/axmodel/rknn/engine）、INT8/FP16 量化、SSH/串口/SD 部署、自适应调度、benchmark、OTA、19 个经典 CV 模块（IPM 逆透视/车道线/ArUco/HDR/光流/立体）+ YOLO/BoxMOT/PaddleOCR。触发：K230、CanMV、MaixCAM、RK3588、Jetson、NPU、KPU、TensorRT、RKNN、kmodel、cvimodel、axmodel、nncase、rknn-toolkit2、trtexec、DeepStream、Savant、YOLO、ByteTrack、PaddleOCR、目标检测、跟踪、OCR、IPM 逆透视、车道线、立体视觉、ArUco、HDR、超分、模型转换、量化、部署、采图、benchmark、OTA。 auto-vison — 边缘 AI 视觉模块统一开发 skill 目标： 降低 4 类 AI 视觉模块的开发门槛 + 提升从训练到上板的迭代效率 。 原则： 复用 > 改良 > 自研 ，最大化复用 Ultralytics、官方 model zoo、上游 SDK，自己只写胶水。 1. 何时使用本 skill 触发条件（命中任一即用）： 用户提到目标硬件：K230、CanMV、MaixCAM、MaixCAM-Pro、MaixCAM2、RK3588（含 RK3576/RK3568）、Jetson Orin Nano Super 任务：模型转换（PyTorch/ONNX → 平台格式）、上板部署、摄像头采图/标定、推理性能调优、量化校准、OTA / 远程日志、模型加密 报错关键字： nncase 、 kmodel 、 rknn-toolkit2 、 tpu-mlir 、 pulsar2 、 trtexec 、 cvimodel 、 axmodel 、MaixPy nn.YOLO11 、CanMV aicube / aidemo 不用本 skill 的场景 ：纯 PC 推理（直接 Ultralytics）、单纯模型训练（用原生 PyTorch）、非视觉任务（音频/LLM 单独走 rknn-llm 或 jetson-containers）。 1.1 与其他 skill 的边界（避免冲突） 任务边界 用本 skill 用其他 skill AI 视觉模型转换 / 部署 / 调优 / 摄像头 ISP ✅ auto-vision — 通用 MCU 外设驱动（STM32 寄存器、IIC 设备初始化） — peripheral-driver / stm32-hal-development 嵌入式 RIPER-5 流程编排（多阶段大任务） — embedded-dev 板端 SSH 通信 / 文件传输 调用 ssh-skill K230 串口日志解析 调用 serial-monitor K230 SDK 编译 / Linux 镜像构建 — build-cmake / build-makefile 板端 GDB 调试（非 AI 推理崩溃） — debug-gdb-openocd / debug-jlink 视觉模型推理崩溃 / 内存溢出诊断 ✅ auto-vision（recipes/debug_workflow.md） — 2. 平台支持矩阵（务必先看） 2.1 硬件 / 工具链矩阵 平台 上层 API 转换工具链 板端运行时 模型格式 主力代码语言 K230 裸 SDK CanMV-MicroPython / Linux C nncase ≥ 2.9 + nncase-kpu KPU runtime .kmodel Python (CanMV) / C MaixCAM / MaixCAM-Pro MaixPy v4 / MaixCDK tpu-mlir (Docker) MaixCAM runtime .cvimodel + .mud Python MaixCAM2 MaixPy v4 / MaixCDK pulsar2 (Docker, AX620E) MaixCAM2 runtime .axmodel + .mud Python RK3588 / RK3576 rknn-toolkit-lite2 / rknpu2 C rknn-toolkit2 ≥ 2.3 (x86 Linux) rknpu2 .rknn Python (Lite2) / C++ Jetson Orin Nano Super 8GB PyTorch + TensorRT / DeepStream trtexec / ultralytics export TensorRT 10 (JetPack 6.x) .engine / .plan Python (+ CUDA C++) 2.2 任务 × 平台支持等级 🟢 可跑通 （templates 内有完整脚手架，5 分钟跑起） 🟡 半自动 （有官方 example 但需要手动调整，详见 platforms/*.md） 🔵 仅指导 （仅提供配方与上游链接，需要用户自行实现） ⚫ 不支持 （硬件或工具链限制） 任务 K230 MaixCAM/Pro MaixCAM2 RK3588 Jetson Orin Nano Super 目标检测 (YOLO11/v8/v5) 🟢 🟢 🟢 🟢 🟢 图像分类 (MobileNet/ResNet) 🟢 🟢 🟢 🟢 🟢 语义分割 (YOLO-seg/DeepLab) ★P1 🟡 🟡 🟢 🟢 🟢 关键点姿态 (YOLO-pose/HRNet) ★P1 🟡 🟡 🟢 🟢 🟢 人脸检测 (RetinaFace/YuNet) 🟢 🟢 🟢 🟢 🟢 人脸识别 (ArcFace/FaceNet) ★P1 🔵 🟡 🟢 🟢 🟢 OCR (PP-OCR / CRNN) 🔵 🟡 🟡 🟢 🟢 多目标跟踪 (ByteTrack/SORT) ⚫ 🔵 🟡 🟡 🟢 ReID 行人再识别 ⚫ 🔵 🔵 🟡 🟢 车牌识别 (LPRNet) 🔵 🟡 🟡 🟢 🟢 多模型 pipeline（detect+track+reid） ⚫ 🔵 🔵 🟡 🟢 (DeepStream) Open-Vocab 检测 (NanoOWL/Grounding) ⚫ ⚫ 🔵 🔵 🟢 VLM 多模态 (Live Llava / VILA) ⚫ ⚫ ⚫ 🔵 🟢 说明 ： 🔵→🟡 升级路径：需求高的任务请优先选 RK3588 / Jetson；K230/MaixCAM 适合单模型轻量场景 多模型 pipeline 在 Jetson 上用 DeepStream，在 RK3588 上手写 GStreamer pipeline VLM / Live Llava 需要 ≥ 8GB 内存，目前只 Jetson Orin Nano Super 满足 MaixCAM 注意 ：MaixCAM 和 MaixCAM-Pro 用 .cvimodel （tpu-mlir），MaixCAM2 用 .axmodel （pulsar2）。两者 不通用 ，模型转换工具链完全不同。本 skill 把它们合并在 platforms\maixcam.md 内部分章讲解。 Jetson ：本 skill 只针对 Orin Nano Super 8GB （67 TOPS, JetPack 6.x, TensorRT 10）。注意 TensorRT 10 的 INT8 在某些算子上有兼容问题，量化默认走 FP16。 MaixCAM 与 K230 关系 ：MaixCAM-Pro/MaixCAM2 用的就是 K230 芯片，但上层固件是 MaixPy， 不能直接用 CanMV/K230 SDK 的 kmodel 。 3. PC 侧 vs 板端分工（核心心智模型） ┌─────────────────────────────────────────┐ ┌─────────────────────────────────┐ │ PC 侧（训练 + 转换） │ │ 板端（仅推理） │ │ 通用 Python / GPU │ │ 受限算力 / 专用 NPU │ ├─────────────────────────────────────────┤ ├─────────────────────────────────┤ │ • PyTorch / Ultralytics（训练） │ │ • CanMV-MicroPython (K230) │ │ • OpenCV / PIL（数据集预处理） │ │ • MaixPy v4 (MaixCAM/Pro/2) │ │ • onnx / onnxsim（中间格式） │ → │ • rknn-toolkit-lite2 (RK3588) │ │ • nncase / tpu-mlir / pulsar2 / │ │ • TensorRT runtime (Jetson) │ │ rknn-toolkit2 / trtexec（转换器） │ │ • cv2 板端 wheel（可选） │ │ • Docker（隔离工具链版本） │ │ │ │ • 大显存 / 大磁盘 │ │ • RAM 通常 ≤ 8GB │ └─────────────────────────────────────────┘ └─────────────────────────────────┘ ↑ ↓ 完整 Python 生态 仅平台特定 API 通用算法库随便用 + 量化后的 .kmodel/.rknn/.engine 关键边界 ： ✅ PC 侧 ：用 Ultralytics / OpenCV / PyTorch / 任何 pip 包，不受任何限制 ✅ 板端 ：只用平台官方 SDK（CanMV / MaixPy / rknnlite / TensorRT），通用 Python 库 未必有 ARM/RISC-V wheel ❌ 不要 ：试图在板端 pip install ultralytics 跑训练 ❌ 不要 ：试图在板端 pip install torch 做完整推理（用量化模型走 NPU 才高效） ⚠️ 特例 ：Jetson Orin Nano Super 可以装 PyTorch（NVIDIA 提供 ARM wheel），但仍推荐用 TRT engine 3.1 "一键转换" vs "二段式转换"（ 新手最易踩坑 ） 通用框架自带的模型导出 ≠ 覆盖所有平台。 只有 Jetson / RK3588 能 Ultralytics 一键直达 ，其余 3 个平台 必须走 ONNX 中间态 ： 目标平台 Ultralytics yolo export 一键？ 必走路径 Jetson (.engine) ✅ format=engine half=True 板上一行命令 RK3588 (.rknn) ✅ format=rknn name=rk3588 int8=True PC x86 Linux 一行命令 K230 (.kmodel) ❌ yolo export onnx → nncase 二段 MaixCAM/Pro (.cvimodel) ❌ yolo export onnx → tpu-mlir (Docker) 二段 MaixCAM2 (.axmodel) ❌ yolo export onnx → pulsar2 (Docker) 二段 本 skill 把"二段式"封装到 scripts\convert.py ，你只需： yolo export model=best.pt format=onnx opset=12 simplify=True imgsz=640 dynamic=False python scripts\convert.py --target k230 --onnx best.onnx --calib data\calib\ --mode run python scripts\convert.py --target maixcam --onnx best.onnx --calib data\calib\ --mode run --mode plan 仅打印命令（默认，安全）， --mode run 真跑（拉 Docker / 调 Python API）。 3.2 板端语言：Python 原型，C++ 量产 模型工件与板端推理语言无关 ——同一个 .rknn / .engine 在 Python 和 C++ 都能加载，不需要重转。 平台 模型工件 Python binding C/C++ binding（量产推荐） K230 .kmodel CanMV nncase_runtime K230 SDK C API MaixCAM/Pro/MaixCAM2 .cvimodel / .axmodel MaixPy maix.nn MaixCDK （API 与 MaixPy 几乎一致） RK3588 .rknn rknn-toolkit-lite2 rknpu2 C API （延迟更低、易集成） Jetson Orin Nano Super .engine tensorrt Python TensorRT C++ API （量产标配 / DeepStream） 推荐路径 ：原型用 Python（本 skill 的 templates 默认 Python）→ 上量产时用 C++ 重写推理 loop（ 模型工件保持不变 ）。各平台 C++ 集成示例： K230: github.com/kendryte/k230_sdk 内的 src\big\nncase\... MaixCAM: https://github.com/sipeed/MaixCDK RK3588: airockchip/rknn_model_zoo/examples/yolo11/cpp/ Jetson: DeepStream-Yolo / 自写 TRT C++ inference loop 4. 工作流（5 步标准化） [1] 平台探测 ──> [2] 环境检查 ──> [3] 模型转换 ──> [4] 部署上板 ──> [5] 板端验证 detect.py env_check.py convert.py deploy.py camera_probe.py benchmark.py 每一步都对应一个 scripts\*.py ，可独立运行也可串联。串联调用例（ 通过 ssh-skill 别名，免记 IP ）： # 一次性注册板子 python scripts\detect.py --host 192.168.1.30 --user rock --password rock \ --register-as rk3588-lab # 同时探测 + 写入 ssh-skill # 之后所有操作只用别名 python scripts\env_check.py --target rk3588 python scripts\convert.py --target rk3588 --onnx yolo11n.onnx --calib data\calib\ python scripts\deploy.py -- alias rk3588-lab --model yolo11n.rknn --remote /home/rock/ python scripts\camera_probe.py -- alias rk3588-lab --target rk3588 --output probe.jpg python scripts\benchmark.py -- alias rk3588-lab --target rk3588 \ --model /home/rock/yolo11n.rknn --imgsz 640 --iters 100 4. 推荐执行路径（按用户意图分流） 4.1 "我要把 YOLO 跑到 X 平台"（最常见） 读取 recipes\yolo_workflow.md 按 platforms\<target>.md 的转换章节执行 用 templates\<target>_yolo\ 脚手架启动板端代码 出问题查 knowledge\errors.md 4.2 "模型转换报错了" grep 报错关键字 → knowledge\errors.md 不命中则查 references\op_support.md （算子兼容速查） 仍未解决：参考 references\upstream.md 找上游 issue 4.3 "我要自定义训练再上板" 训练侧用 Ultralytics 官方流程（ templates\ 内有 train.md 引导） 导出 ONNX： yolo export model=best.pt format=onnx opset=12 simplify=True 之后接 4.1 流程 4.4 "我要选型，对比 4 个平台" 看 references\version_matrix.md （成本/性能/语言生态） 跑 scripts\benchmark.py 在你已有的板子上自测 4 个 templates 都用相同 YOLO11n 320×320 测，便于横评 4.5 "我要做非 YOLO 任务"（分类/分割/姿态/人脸） 看 recipes\yolo_workflow.md 章末"非 YOLO 任务索引" K230/MaixCAM：MaixHub 模型库直接拉 RK3588： airockchip\rknn_model_zoo 已覆盖检测/分割/OCR/人脸/车牌 Jetson： dusty-nv\jetson-inference Hello AI World 5. 自适应视觉框架（R3 — codex accept） 上面 1-4 节是"YOLO 部署脚手架"层，本节是"成熟视觉框架"层。 三轮擂台辩论记录见 .iter\R1_proposal.md / R2_proposal.md / R3_proposal_final.md 。 5.1 三层自适应引擎 [L1 静态] policies/device_profile.yaml → 5 平台硬件画像（出厂常量） [L2 默认] policies/task_policy.yaml → 3 任务 × 5 平台 → model/imgsz/quant/tracker [L3 实测] tools/benchmark_tuner.py → 候选剪枝≤6, early-stop → auto_tuned.yaml ↓ [运行时] runtime/scheduler.py → FPS/温度/imgsz/跳帧/ROI 三动作 5.2 R3+R4 模块清单（含经典 CV 子包） 路径 作用 关键 algo/ 统一插件（ 对齐 supervision.Detections ） Detector / Tracker (BoxMOT) / OCRPipeline (PaddleOCR) algo/cv_classical/ ★ 经典 CV 算法库（18 模块 60+ 算法） IPM 逆透视 / 车道线 / Hough / 形态学 / 光流 / 立体 / ArUco / HDR / 全景 / 标定 / 配准 / HOG （详见 algo/cv_classical/README.md ） adapters/ 平台 pipeline 翻译器 k230_canmv / maixcam_maixpy / rk3588_gst / jetson_savant (走 Savant 不重写) policies/ 自适应核心配置 device_profile + task_policy（schema 校验） model_zoo/manifest.yaml 模型 × 平台 × imgsz × mAP × 延迟矩阵 runtime/scheduler.py AdaptiveScheduler FPS EWMA → imgsz/skip/ROI tools/ 离线 tuner budget_pruner（理论≤18，启发式≤6）+ benchmark_tuner image_quality/ 策略型增强 isp_autotune（v4l2/nvargus）+ lowlight（gamma+CLAHE，无模型） eval/ 评测 COCO mAP + MOT（py-motmetrics optional） schema/pipeline_config.py dataclass 校验 6 字段，无 DSL apps/ 完整闭环 demo traffic_count + ocr_meter 5.3 典型自适应工作流 # Step 1：默认配置（不需要 tuner，直接读 task_policy.yaml） python schema/pipeline_config.py --validate policies/task_policy.yaml # Step 2：看候选剪枝（codex 验收"可解释"） python tools/budget_pruner.py --profile policies/device_profile.yaml \ --platform rk3588 --task detection # → 输出 12 候选 + 每个的 rationale（"NPU 6 TOPS → model yolo11s ..."） # Step 3：实测 tune（需有板子） python tools/benchmark_tuner.py -- alias rk3588-lab --platform rk3588 \ --task detection --target-fps 30 # → 生成 policies/rk3588_lab_auto_tuned.yaml（含可解释字段 + audit_trail） # Step 4：跑 demo app（自适应 scheduler 在线运行） python apps/traffic_count/main.py --platform rk3588 -- source 11 \ --model /home/rock/yolo11s.rknn --show 5.4 codex R3 验收标准（已通过） "同 task_policy.yaml 在 RK3588/Jetson/Maix 至少两平台生成不同执行路径，benchmark 选出可解释配置" 实际验证：同 detection task 对三平台产物： RK3588 : main.py (cv2/GST 三线程) + postprocess.py + labels.txt Jetson : main.py (Ultralytics) + savant.yml (生产 pipeline) K230 : main.py (CanMV MicroPython) + model/ + labels.txt 三种完全不同的执行路径，由同一份配置驱动。 6. 目录速查（含 R3 新模块） auto-vision\ ├── SKILL.md ← 你正在看 ├── algo\ ★ R3 视觉算法插件（对齐 sv.Detections） │ ├── base.py AlgoBase / DetectorBase / TrackerBase / OCRBase │ ├── detection.py YOLO 统一（ultralytics + rknnlite）