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

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 子包）

路径	作用	关键
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）
│   ├── 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 已经按这个原则封装：

场景	必须调用的 skill / 命令
首次发现板子 → 注册别名	scripts\detect.py --host <ip> --register-as <alias> → 内部调 ssh-skill\scripts\ssh_config_manager_v3.py create
远端执行命令	ssh-skill\scripts\ssh_execute.py <alias> "<cmd>"
上传文件 / 目录	ssh-skill\scripts\ssh_upload.py <alias> <local> <remote>（路径前缀 MSYS_NO_PATHCONV=1）
下载文件	ssh-skill\scripts\ssh_download.py <alias> <remote> <local>
多板批量	ssh-skill\scripts\ssh_cluster.py "<cmd>" --tags ai-vision-board --parallel
隧道访问板上 web (DeepStream / MaixVision)	ssh-skill\scripts\ssh_tunnel.py start <alias> --remote-port 8080
K230 串口日志抓取	serial-monitor
板端摄像头 / I2C 外设驱动	peripheral-driver
K230 SDK 重新编译（很少需要）	build-cmake
通用流程编排	embedded-dev（仅当多 skill 协作时）

为什么强制走 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