CoralNPU · YOLOv8s 优化成果（增量交付）

⚠️ 执行前必须先读两份文档，否则会踩坑：

doc/yolov8s/HW-CONFIG-2026-10-20.md —— 硬件/固件配置、复现命令（§5）、期望结果（§6）

doc/yolov8s/HANDOFF-2026-10-16.md —— 环境清单（§5）、10 条踩坑清单（§6）

以及 doc/yolov8s/OPTIMIZATION-SUMMARY.md —— 8 个优化阶段的完整记录。（这些文档在 overlay/doc/yolov8s/ 下；执行 apply.sh 后位于 upstream/doc/yolov8s/。）

这是什么

本仓库是 「YOLOv8s 在 CoralNPU 上端到端 int8 推理 + 优化」 的增量交付：相对上游 google-coral/coralnpu 的 commit 517f4c09 的全部改动（代码 + RTL + 文档），打包成一个 commit。

结果（mpact ISS 实测）：

指标	值
端到端周期	9.39 G（优化前 149.17 G，15.9×）
数值一致	T12 98.09% 逐位一致、max 40
检测正确	L3 6/6 框匹配、IoU ≥ 0.959
优化阶梯	149.17 → 34.47 → 9.40 → 7.59 → 3.648 → 3.475 G（含 VDOT 指令的完整阶梯）

复现步骤（别人 / 新服务器）

第 0 步：先读文档

读上面两份文档（HW-CONFIG §5 复现命令、HANDOFF §5 环境 + §6 踩坑清单）。

第 1 步：拉上游 + 应用增量

./apply.sh

脚本会：clone 上游 google-coral/coralnpu → checkout 到 517f4c09 → 把 overlay/ 的改动覆盖进去 → 得到含全部优化的完整树（在 upstream/）。

第 2 步：装环境（版本必须精确）

见 HW-CONFIG.md §5.5 / HANDOFF.md §5，要点：

项	版本
bazel	9.1.0
conda env `yolo`（模型导出+验证）	python 3.10 + `ultralytics==8.4.82`（≥8.4.83 会段错误）、`tensorflow==2.19.1`、onnx、onnxslim、numpy、pyyaml、onnxruntime
conda env `toolchain`（ISS 构建）	clang 23 + lld 23
系统	gcc/g++ 12

一键脚本：overlay/doc/yolov8s/tools/env_yolo.sh（注意先补 ultralytics==8.4.82 的 pin，见脚本注释）。

第 3 步：导出模型（.tflite 未包含在仓库，需自生成）

cd upstream && conda activate yolo && \
python doc/yolov8s/tools/export_yolov8s_int8.py --force
# 产出 sw/examples/models/yolov8s_int8.tflite（全整型变体，11,564,448 B）

说明：模型二进制不随仓库分发，由导出脚本从 yolov8s.pt（Ultralytics 官方权重）+ 标定样本再生成。

第 4 步：构建 → ISS 推理 → 验证

命令全文见 HW-CONFIG.md §5，三个必带参数缺一不可：

bazel build //sw/examples/yolov8s:yolov8s_binary //tests/npusim_examples:npusim_run_yolov8s \
  --action_env=PATH=<toolchain PATH> --host_action_env=PATH=<同值>  \
  --repo_env=CC=/usr/bin/gcc --repo_env=CXX=/usr/bin/g++            \
  --distdir=<distdir>

常见错误（已有人踩过，先看这里）

错误信息	原因	修复
`invalid registered toolchain ... no such package '@@rules_cc++cc_configure_extension+local_config_cc'` 或 `error fetching repository '...local_config_cc'`	全新 output_base 上 CC 工具链自动探测失败	构建命令加 `--repo_env=CC=/usr/bin/gcc --repo_env=CXX=/usr/bin/g++`
`no such package '//coralnpu_test_utils/sim_backends'`	该包属于上游 517f4c09；说明树不是「正确的上游 + overlay」（没 checkout 到 517f4c09，或 clone 不完整）	重跑 `./apply.sh`（它带自检，会明确报出 HEAD 不对）；确认 `git -C upstream rev-parse --short HEAD` = `517f4c09`
`clang: command not found` / 配置切换后重分析失败	没带 `--action_env=PATH`	见上（两个 PATH 参数都必须带）
`bazel-bin/...yolov8s_binary.elf: No such file`	同一条命令构建固件+ISS 驱动会切换 `bazel-bin` 软链	用 ST 树绝对路径，或单独重 build 固件目标

仓库结构

README.md        # 本文件
apply.sh         # 一键：拉上游 517f4c09 + 应用增量
overlay/         # 相对上游的增量（按原 coralnpu 目录结构）
  ├── sw/opt/litert-micro/        # 优化内核（conv/logistic/mul/add…）
  ├── sw/examples/yolov8s/        # 固件
  ├── sw/examples/{*_probe}/      # 探针
  ├── hdl/verilog/rvv/design/     # VDOT 指令 RTL（vdot_unit + 译码改动）
  ├── third_party/coralnpu_mpact/ # ISS 补丁（0009-0014）
  ├── third_party/tflite-micro/   # AddLogistic 重载补丁
  ├── rules/ toolchain/           # 构建/工具链改动
  └── doc/yolov8s/                # 全部文档 + 工具脚本
.gitignore       # 忽略 upstream/