Auto Vision

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 的边界（避免冲突）

2. 平台支持矩阵（务必先看）

2.1 硬件 / 工具链矩阵

2.2 任务 × 平台支持等级

🟢 可跑通（templates 内有完整脚手架，5 分钟跑起） 🟡 半自动（有官方 example 但需要手动调整，详见 platforms/*.md） 🔵 仅指导（仅提供配方与上游链接，需要用户自行实现） ⚫ 不支持（硬件或工具链限制）

说明：

• 🔵→🟡 升级路径：需求高的任务请优先选 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 中间态：

本 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（本 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 平台"（最常见）

1. 读取 recipes\yolo_workflow.md
2. 按 platforms\<target>.md 的转换章节执行
3. 用 templates\<target>_yolo\ 脚手架启动板端代码
4. 出问题查 knowledge\errors.md

4.2 "模型转换报错了"

1. grep 报错关键字 → knowledge\errors.md
2. 不命中则查 references\op_support.md（算子兼容速查）
3. 仍未解决：参考 references\upstream.md 找上游 issue

4.3 "我要自定义训练再上板"

1. 训练侧用 Ultralytics 官方流程（templates\ 内有 train.md 引导）
2. 导出 ONNX：yolo export model=best.pt format=onnx opset=12 simplify=True
3. 之后接 4.1 流程

4.4 "我要选型，对比 4 个平台"

1. 看 references\version_matrix.md（成本/性能/语言生态）
2. 跑 scripts\benchmark.py 在你已有的板子上自测
3. 4 个 templates 都用相同 YOLO11n 320×320 测，便于横评

4.5 "我要做非 YOLO 任务"（分类/分割/姿态/人脸）

1. 看 recipes\yolo_workflow.md 章末"非 YOLO 任务索引"
2. K230/MaixCAM：MaixHub 模型库直接拉
3. RK3588：airockchip\rknn_model_zoo 已覆盖检测/分割/OCR/人脸/车牌
4. 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 子包）

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）
│   ├── tracking.py              BoxMOT (ByteTrack/BoT-SORT/OC-SORT) + ROI lite fallback
│   ├── ocr.py                   PP-OCR 两阶段
│   └── cv_classical\            ★ R4 经典 CV 18 模块 60+ 算法（含 IPM 逆透视）
│       ├── _utils.py            validate_image / capability_gate / has_cv_feature / make_result
│       ├── geometry.py          ★ IPM / homography / PnP / 文档矫正
│       ├── calibration.py       棋盘标定 / Undistorter / stereo / triangulate
│       ├── lane.py              ★ HLS+Sobel+IPM+滑动窗口+二次拟合 (gated)
│       ├── motion.py            LK / Farneback(gated) / DIS / MOG2 / Kalman2D
│       ├── stereo.py            BM / SGBM(gated→BM) / disparity_to_depth
│       ├── markers.py           ArUco / AprilTag 检测+生成+姿态
│       ├── stitching.py         Stitcher / HDR / triangulate / 白平衡 (gated)
│       ├── registration.py      findTransformECC / phaseCorrelate
│       ├── pyramid.py           pyrDown/Up / Laplacian / OF 金字塔
│       ├── filters.py / edges.py / morphology.py / shape.py
│       ├── features.py          Harris/FAST/ORB/AKAZE/SIFT/HOG/cornerSubPix
│       ├── matching.py          template/BF/FLANN/RANSAC
│       ├── segmentation_classical.py  watershed/GrabCut/颜色分割
│       └── quality.py           Laplacian variance/BRISQUE/亮度/对比度
├── adapters\                    ★ R3 平台 pipeline 翻译器
│   ├── maix_base.py             公共：MUD 生成 / 模型推送
│   ├── k230_canmv.py            K230 CanMV (MicroPython) 模板
│   ├── maixcam_maixpy.py        MaixCAM/Pro/2 MaixPy 模板
│   ├── rk3588_gst.py            RK3588 三线程 cv2/GST
│   └── jetson_savant.py         Jetson 走 Savant YAML + fallback main.py
├── policies\                    ★ R3 自适应配置
│   ├── device_profile.yaml      5 平台硬件画像
│   ├── task_policy.yaml         3 任务 × 5 平台
│   └── <device>_auto_tuned.yaml 由 tuner 自动生成
├── model_zoo\manifest.yaml      ★ R3 模型×平台 性能矩阵
├── runtime\scheduler.py         ★ R3 AdaptiveScheduler (FPS/imgsz/skip/ROI)
├── tools\                       ★ R3
│   ├── budget_pruner.py         候选剪枝（理论≤18，实际≤6）
│   └── benchmark_tuner.py       离线 tune + 可解释输出
├── image_quality\               ★ R3
│   ├── isp_autotune.py          v4l2-ctl / nvargus ISP 参数
│   └── lowlight.py              gamma + CLAHE（无模型）
├── eval\                        ★ R3
│   ├── eval_detection.py        COCO mAP
│   └── eval_mot.py              MOTA/IDF1（motmetrics optional）
├── schema\pipeline_config.py    ★ R3 dataclass 校验
├── apps\                        ★ R3 完整闭环 demo
│   ├── traffic_count\           detection + tracker + LineZone
│   └── ocr_meter\               YOLO ROI + PP-OCR 两阶段
├── platforms\                   平台专属文档（4 个）
│   ├── k230.md                  K230 + CanMV
│   ├── maixcam.md               MaixCAM-Pro + MaixCAM2 合并
│   ├── rk3588.md                RK3588 / RK3576
│   └── jetson.md                Orin Nano Super 8GB
├── scripts\                     可执行工具（Python 3.10+）
│   ├── detect.py                平台自动探测
│   ├── env_check.py             SDK 版本兼容矩阵校验
│   ├── convert.py               统一前端：dispatch 到平台
│   ├── deploy.py                SSH 部署 + 启动
│   ├── camera_probe.py          板端摄像头自检
│   └── benchmark.py             统一性能采集
├── recipes\                     高级配方
│   ├── yolo_workflow.md         端到端 YOLO 流程
│   ├── quantization.md          PTQ 校准实操
│   └── debug_workflow.md        通用调试方法
├── templates\                   项目脚手架（每平台一套，5 分钟跑通）
│   ├── k230_canmv_yolo\
│   ├── maixpy_yolo\
│   ├── rk3588_yolo\
│   └── jetson_yolo\
├── references\                  长查询文档（按需 Read）
│   ├── upstream.md              ★ 所有上游开源 repo 索引
│   ├── version_matrix.md        SDK / 工具链 / 固件版本对应
│   └── op_support.md            4 平台算子兼容速查
└── knowledge\
    └── errors.md                报错→根因→修复

6. 与本仓库其他 skill 的协作关系（★ 强制约束）

所有 SSH 操作必须走 ssh-skill，不直接用 ssh / scp / paramiko。 本 skill 内的 scripts\deploy.py / camera_probe.py / benchmark.py 已经按这个原则封装：

为什么强制走 ssh-skill：

• 守护进程长连接（~0.12s vs paramiko 直连 ~0.45s），跑 benchmark / 多次部署效率提升数倍
• 自动重连、心跳检测、跳板机支持
• 多板别名管理统一（k230-01 / maixcam2-lab / rk3588-prod / jetson-dev），免记 IP
• 按 tags 批量操作：--tags rk3588 一次跑遍所有 RK3588 板

典型首次接入流程：

# 1. 探测并注册到 ssh-skill
python scripts\detect.py --host 192.168.1.30 --user rock --password rock \
    --register-as rk3588-lab

# 2. 之后所有操作走别名
python scripts\camera_probe.py --alias rk3588-lab --target rk3588 --output probe.jpg
python scripts\deploy.py --alias rk3588-lab --model yolo11n.rknn --remote /home/rock/
python scripts\benchmark.py --alias rk3588-lab --target rk3588 --model /home/rock/yolo11n.rknn

7. 复用 vs 自研边界（务必遵守）

✅ 必须复用（不要重写）：

• ultralytics 训练 / export 流程
• 官方转换工具：nncase / nncase-kpu / tpu-mlir / pulsar2 / rknn-toolkit2 / trtexec
• 官方 model zoo：airockchip\rknn_model_zoo、kendryte\K230_training_scripts、MaixHub、dusty-nv\jetson-inference
• 容器：dustynv\* Jetson 容器、官方 docker 镜像

✏️ 本 skill 自研（胶水层）：

• 平台探测脚本、版本矩阵 yaml
• 校准数据集组织 + 精度对比报告
• SSH 部署器（薄包装 paramiko）
• benchmark 报告模板
• 错误根因知识库

❌ 不要做：

• 重写推理 runtime
• 改 ONNX/PyTorch 模型结构（除非平台明确要求）
• 隐藏量化精度损失
• 跨平台运行时抽象（坑大于收益）

8. PC 端推荐环境（本机已验证）

本机推荐使用 conda 环境 yolo_env 作为 PC 训练 / 转换默认环境：

conda activate yolo_env       # 已装 PyTorch 2.6+CUDA 12.4 / Ultralytics 8.4 / ONNX / onnxsim / paramiko

完整路径：C:\ProgramData\miniconda3\envs\yolo_env\python.exe（Python 3.10.19）

若需直接调用（如 Windows cmd 没 conda activate）：

& "C:\ProgramData\miniconda3\envs\yolo_env\python.exe" scripts\convert.py ...

或在 VSCode .vscode\settings.json 中：

{"python.defaultInterpreterPath": "C:\\ProgramData\\miniconda3\\envs\\yolo_env\\python.exe"}

env_check.py 会自动检测当前是否在 yolo_env，不在则给出切换提示。

9. 快速开始（新手 5 分钟）

# 0. 切到推荐环境
conda activate yolo_env

# 1. 探测你手头的板子
python scripts\detect.py

# 2. 假设探测到 rk3588，看专属文档
# → 阅读 platforms\rk3588.md

# 3. 跑脚手架（已自带 yolo11n.rknn 预转模型 + 板端推理脚本）
# → 阅读 templates\rk3588_yolo\README.md

# 4. 想自己训练并上板
# → 阅读 recipes\yolo_workflow.md

9. 版本声明

• skill 版本：0.1.0
• 基线工具链版本（2026-05）：
  • nncase 2.9.x / 2.10.x（K230）
  • tpu-mlir 最新 dev（MaixCAM）
  • pulsar2 最新 dev（MaixCAM2）
  • rknn-toolkit2 2.3.x（RK3588）
  • JetPack 6.1 / 6.2 + TensorRT 10.x（Orin Nano Super）
  • ultralytics ≥ 8.3
• 详细版本对应见 references\version_matrix.md