垃圾分类：20 个细类变成 4 个桶

01目标：每行读懂「大类·细类·分数」三段

02问题：模型认得出瓶子，可它不知道该扔哪个桶

教室后面一袋垃圾倒出来：矿泉水瓶、易拉罐、胡萝卜、电池、药片包装、砖块碎。要按四个桶分开。人靠常识，机器只有像素 —— 而且它连「桶」这个概念都没有。

更要紧的是：这一章跟前几章有个根本区别。颜色、轮廓、二维码都是「给一个答案」，而一袋垃圾一帧里常常有好几个东西。纯分类网络（ResNet 那类）对整张图只输出一个标签 —— 四个垃圾它只能说一个。所以这里必须用检测网络。

模型本身认的是 20 个细类，名字全是拼音（训练时就用的拼音，不是英文也不是中文）。而桶只有 4 个。下面这张对照表就是全部业务规则：

机器要顶替人，光「认得出」不够，它得同时回答三件事。这三问就是下一节原理的骨架：

① 一帧里有四个垃圾，它凭什么每个都报一遍？纯分类只能吐一个答案。检测网络是「逐个格子报」的 —— 可怎么保证四个都被报出来、又不重不漏？

② 它说 shuiping，谁把这句话翻成「可回收」？模型心里没有桶的概念。这层翻译放在模型里、还是放在代码里，会决定你以后加一种新垃圾时要不要重训模型。

③ 十来帧每秒够不够用？板上只有一个 NPU，一个线程喂不饱它。想更快，能靠堆线程吗？堆到几个才不亏？

先别急着答。第 03 节先把四张图跑一遍，四种桶全看一眼。

03现象：三段输出：recyclable yilaguan 0.85

🎬 现象速览 · 30 秒先看效果

你会看到：每个垃圾被一个红框套住，框上方一行三段字 —— recyclable yilaguan 0.85：该扔哪个桶 / 它是什么 / 模型多确定。四条命令跑完，四个桶全出现过。

三条步骤（第 2 步一次跑四张图）：

① 进目录，确认模型和测试图在。

cd ~/ros2_ws/src/xflz_eai_car1/vision/02_garbage_classification
ls models/
ls images/

models/: garbage_yolov5_20cls.rknn images/: 1.jpg 2.jpg 3.jpg 4.jpg

② 单图推理，一次把四张图都跑一遍。四张图的输出分别存成 out1.jpg～out4.jpg。注意：终端只会打印 saved -> out1.jpg 这一行 —— 认出了什么、在哪、多少分，全都画在图上。这一点和上一章的缺陷检测不同，别在终端里找坐标。

python src/app.py --model models/garbage_yolov5_20cls.rknn --image images/1.jpg --save out1.jpg
python src/app.py --model models/garbage_yolov5_20cls.rknn --image images/2.jpg --save out2.jpg
python src/app.py --model models/garbage_yolov5_20cls.rknn --image images/3.jpg --save out3.jpg
python src/app.py --model models/garbage_yolov5_20cls.rknn --image images/4.jpg --save out4.jpg

saved -> out1.jpg saved -> out2.jpg saved -> out3.jpg saved -> out4.jpg ← 就这四行。逐目标信息不打印，全在图上（见下面四张） ← 还会看到 RKNN 的版本/模型信息与一条 dynamic_shapes 警告，属正常，不影响结果

生成的四个文件，打开就是下面四张 —— 四条命令、四种桶：

③ 开实时流，让框跟着手走。要开两个终端：一号窗起相机驱动，二号窗跑 --ros。实时模式下终端会打印帧率，这是第 06 节的入口。

终端一 · 起相机驱动

source /opt/ros/humble/setup.bash && source ~/ros2_ws/install/setup.bash
export ROS_DOMAIN_ID=N
ros2 launch ascamera hp60c.launch.py

终端二 · 跑实时检测

source /opt/ros/humble/setup.bash && source ~/ros2_ws/install/setup.bash
export ROS_DOMAIN_ID=N
cd ~/ros2_ws/src/xflz_eai_car1/vision/02_garbage_classification
python src/app.py --ros

30帧平均帧率: 15.x 30帧平均帧率: 16.x ← 每 30 帧打一次，落在 15~18 区间（默认 tpes=2）。验收门是总平均 ≥ 15 FPS

浏览器打开（<板IP> 换成板子的局域网地址）：

http://<板IP>:8080/garbage_cam.mjpg

浏览器里出现滚动画面，把垃圾逐个放到镜头前，红框与三段字跟着动

🔍 看什么：四样东西 —— ① 一帧里有几个目标，是不是每个都被框了；② 三段字里哪一段是桶、哪一段是拼音；③ 分数高的是不是看得更清的那个（out1.jpg 里 0.89 的胡萝卜比 0.59 的碎块更清楚）；④ 同一张图里有没有两个框套住同一个东西。

这就是本实验最终要呈现的现象。此时照做、先看懂它就行；第 05 节会带你走一遍「命令 → 函数 → 文件」的对账，亲手复现同一个画面 —— 跑出来、对得上，实操才算完成。

扩展 · 四张图逐条对照，看四种桶怎么凑齐

这四张图不是随手拍的：它们刚好把四个桶各演了一遍。下面把每张图上框里的字原样抄下来（这些字在图上，不在终端），再对回第 02 节那张表 ——

其中两张图里藏了两个「后面要用的现象」，先记住：

① out1.jpg 一帧报了四个框。四个框是怎么「同时」产生的？不是模型看了四遍，是它在每个格子上都猜了一次，猜中的才留下 —— 这是第 04 节步骤 2 要拆的。

② 四张图里没有出现「同一个东西被两个框套住」。这是好事，说明去重生效了；但去重调过头就会出现反例 —— 两块贴在一起的砖块会被合成一个。调过头会怎样，第 06 节让你亲手试。

04原理：一条链八段，只有一段在 NPU 里

这一节先看整条链的八段（哪段在板子的 NPU 里、哪段在 Python 里），再按第 02 节的三问往里钻：① 一帧多个怎么逐个报（步骤 2）→ ② 拼音怎么变桶（步骤 3）→ ③ 怎么更快（步骤 4）。步骤 1 是三者共同的前置：得先把图摆成模型认识的样子。

1送进去之前，为什么必须补黑边、还得换颜色顺序？

先猜一下：把 1080p 的照片直接喂进去，行不行？

不行，模型只认 640×640。做法是等比缩放 + 补边，和上一章一样。但这页有个更严的细节：补边必须是纯黑（0）。模型训练时用的就是黑色填充 —— 推理时填成灰的，那圈灰边会真的参与特征计算，边缘就容易冒出假框。

第二个细节是颜色顺序。OpenCV 读进来是 BGR，而这个模型训练时用的是 RGB（转换时定了 rgb2bgr=False），喂之前必须换一次。弄反了不会报错，症状是「框的位置全对、类别全错」—— 模型看到的「红」其实是蓝。

2一帧四个垃圾，它凭什么每个都报一遍？

先猜一下：它是先找出所有物体、再一个个认，还是先猜一堆框再看框里是什么？

都不是。它是在每个格子上都猜一次：把 640 的图切三种粗细的格子 —— 80×80、40×40、20×20，每个格子先摆 3 个「预设框」（叫 anchor，是从训练数据里统计出来的常见长宽比），然后对每个「格子 × 预设框」都报一套数：框要怎么调、这里有没有东西、是 20 类里的哪一类。

所以第 ③ 段出来的三个张量，每个都是 [1, 75, h, w]：75 = 3 个锚框 ×（4 个框参数 + 1 个目标置信度 + 20 类分数）。

那「四个目标」是怎么出来的？就是四个地方各自猜中了。一帧里 80²+40²+20² = 8400 个位置、每个 3 个锚框，总共两万多次猜测，压在水瓶上的那几个报出了高分 —— 它从来不是「看四遍」，是一次性对全图下注。

为什么还要去重？因为压在一个物体上的不止一个格子，同一处会被报好几次，分数还都不一样。于是两道过滤：先按 score_thr=0.25 扔掉低分的，再按 nms_thr=0.45 逐类去重 —— 同一类里重叠超过 45% 的，只留分数最高的。注意是「逐类」：跨类不抑制，因为一个水瓶完全可能同时出现在「可回收」和「其他」两个候选里，让业务侧去裁决。

3它说 shuiping，谁把这句话翻成「可回收」？

先猜一下：这个映射是模型里学出来的，还是外面查表查的？

外面查表。模型输出的只有 0~19 的编号：编号靠 config/labels.txt 翻成拼音名；至于「这个编号该扔哪个桶」，全靠 config/category_map.txt —— 一个每行一个数字的文本文件，行号对应细类编号，值是 1~4 的桶号。

这正是本页最重要的一课：模型的原子能力是「认 20 个细类」，业务的消费单位是「4 个桶」，两者之间用一张表解耦。好处很实在 ——

表错一行会怎样？全错。因为映射是按行号对齐的：category_map.txt 第 11 行对应 labels.txt 第 11 行的 shuiping。中间插一行，后面全体错位 —— 水瓶会被判成有害。这是本节最容易踩、也最难查的坑：不报错，只是全错。

4只有一个 NPU，怎么让它从十来帧跑到二十帧以上？

先猜一下：开两个线程，帧率能翻倍吗？

不能翻倍，但确实会明显涨。原因有两个，容易被混淆：一是 NPU 不止一路并行能力，单线程时用不满；二是「等 NPU」和「干别的活」可以重叠 —— 一个线程在 NPU 上推理时，另一个线程正好在取帧、洗数据、画框、推流。后者往往比前者贡献更大，这也是为什么最优线程数会超过核数。

代码里用生产者 — 消费者实现：主线程把帧丢进队列，--tpes N 个工作线程各自从队列取帧、各自推理，结果按序取回。三条硬约束：

这四步在代码里分别是谁

这张表只看第三列和第五列 —— 左两列是「哪一步、屏幕上看到什么」，右两列是「谁在干、动了会怎样」。

先认识 6 个词

这六个词后面每一步都会出现。前四个属于「模型怎么说」，后两个属于「我们怎么接」。

现在回头看第 02 节那一袋垃圾：四个垃圾之所以能各报一次，是因为检测头在每个格子上都猜了一次（步骤 2）；shuiping 之所以能变成「可回收」，是因为第 ⑦ 段查了一张表（步骤 3）；十来帧之所以能涨到二十帧以上，是因为线程池把 NPU 与后处理重叠了起来（步骤 4）。三问都填上了。

05实操：单图、实时、线程数三条命令

全部在板子上执行。复制、粘贴、回车就行，每条命令后面都标了「跑完看到什么算对」。

1. 进目录，跑单测，看清两张表约 4 分钟

   先站到正确的位置，跑一遍单元测试确认依赖齐了（仓库自带 62 个用例，全部用假后端跑，不加载真权重），再把两张表打印出来 —— 这两张表就是本实验的全部业务规则。

   cd ~/ros2_ws/src/xflz_eai_car1/vision/02_garbage_classification
   python -m pytest tests/ -v

   62 passed ← 全绿说明配置加载、预处理、解码、NMS、映射、线程池都能跑

   然后看两张表：labels.txt 是 20 个细类（行号 = 类别编号），category_map.txt 每行一个 1~4 的数字，行序跟 labels 严格对齐。

   cat config/labels.txt
   cat config/category_map.txt

   bailuobo caiye chuangkotie ← 20 行，全是拼音；category_map 也是 20 行，每行一个 1~4

   对齐这件事亲手验一次最牢：两个文件并排看，第 11 行的细类是什么（shuiping）、第 11 行的数字是几（1）、按第 02 节那张表该扔哪个桶（可回收）。三处对上，你就掌握了这页的核心。

2. 单图推理，一次跑四张图约 10 秒

   --model 指模型，--image 指输入图，--save 把带框结果写盘。远程 SSH 一定要带 --save：不带会开窗等你按键。

   python src/app.py --model models/garbage_yolov5_20cls.rknn --image images/1.jpg --save out1.jpg
   python src/app.py --model models/garbage_yolov5_20cls.rknn --image images/2.jpg --save out2.jpg
   python src/app.py --model models/garbage_yolov5_20cls.rknn --image images/3.jpg --save out3.jpg
   python src/app.py --model models/garbage_yolov5_20cls.rknn --image images/4.jpg --save out4.jpg

   saved -> out1.jpg saved -> out2.jpg saved -> out3.jpg saved -> out4.jpg

   打开 out1.jpg，四行字的格式是固定的：{大类} {细类} {分数} —— 大类在前（分拣指令看这个），细类在中间（调试定位看这个），分数在后（质检门控看这个）。这四个文件就是第 03 节那四张图。

3. 实时流，再对比线程数约 8 分钟

   要开两个终端。source 两句把 ROS2 与本工作区环境装进当前终端；export ROS_DOMAIN_ID=N 把通信频道拨到 N（0~101 任选，每台设备各选各的）。

   终端一 · 起相机驱动

   source /opt/ros/humble/setup.bash && source ~/ros2_ws/install/setup.bash
   export ROS_DOMAIN_ID=N
   ros2 launch ascamera hp60c.launch.py

   日志持续滚动，无 ERROR / 无红字

   二号窗跑检测。source 两句和 DOMAIN_ID 都要重来一遍 —— 漏了就是两边互相看不见。

   终端二 · 跑实时检测（先用默认 2 线程）

   source /opt/ros/humble/setup.bash && source ~/ros2_ws/install/setup.bash
   export ROS_DOMAIN_ID=N
   cd ~/ros2_ws/src/xflz_eai_car1/vision/02_garbage_classification
   python src/app.py --ros

   30帧平均帧率: 15.x 30帧平均帧率: 16.x ← 每 30 帧打一次；跑够几轮后 Ctrl+C，最后一行会打「总平均帧率」

   浏览器打开 http://<板IP>:8080/garbage_cam.mjpg，然后 Ctrl+C 退出，改线程数再跑一次 —— 这是本实验唯一需要你亲手比出来的数据：

   python src/app.py --ros --tpes 1
   python src/app.py --ros --tpes 6
   python src/app.py --ros --tpes 8

   总平均帧率: 8~10 总平均帧率: 20 以上 总平均帧率: 略低于 6 线程 ← 三行的「形态」才是判据：低 → 高 → 略降。具体数值按你的板子会有出入 ← 请把你自己的三个数记下来，第 06 节要拿来对

   如果三行不是「低 → 高 → 略降」，先别怀疑代码：确认三次都是同一个场景、光照没变（画面里东西越多越慢）。

命令 → 函数 → 文件：你敲的每一行到底经过了谁

跑通之后要能回答：这个参数属于链上哪一段，改它会影响哪一格？这张表就是这段链条的「户口本」。

看不到的环节也要交代清楚：NPU 里那 3 组张量是怎么算出来的，源码里看不到 —— 那是 .rknn 里的指令。所以第 ③ 段在这个仓库里没有对应函数，别去找。

你该看到的画面

知道「正常」长什么样，才知道「异常」是哪一处出的问题。

重点与易错点

按「我看到的症状」找对应行。左边是你遇到的现象，右边是该做的事。

进阶与深读

基础三步跑通之后再看这里。做不完不影响成绩，做了有加分。

代码复盘：让 AI 带你把这套代码读明白

这一节不逐行讲代码。给你三组提示词，由你自己指挥 AI 产出三张图，再拿真源码去对 —— 图对不对，反过来证明你读没读懂。

请阅读这几个文件：src/app.py、src/detector.py、src/preprocess.py、
src/postprocess.py、src/rknnpool.py、src/mjpeg_server.py、
config/garbage_config.yaml、config/labels.txt、config/category_map.txt。
这是一个基于 RKNN 的垃圾分类检测项目，20 个细类映射到 4 个大类。
请输出一张模块职责表，回答三个问题：
1）每个文件负责哪一件事，用一句话说清；
2）从入口 src/app.py 往下，谁调用谁；
3）category_map.txt 的行序与 labels.txt 是什么关系，错位会怎样。
输出格式：markdown 表格，四列是「模块 / 职责一句话 / 被谁调用 /
关键函数」，每条职责后面用 文件名:行号 标注出处。

请为「一帧图的处理链」画一张控制流流程图，从读帧开始到推流结束。
要求：
1）必须体现「模型只占一段」：把 NPU 推理那一步单独标出来，
   其余步骤标成 Python 侧；
2）分支必须画全：读帧失败、一个目标都没检出、检出多个目标；
3）每个框里写真实函数名（letterbox、to_rgb、predict、
   decode_scale、classwise_nms、unletterbox、map_categories）；
4）用 mermaid 的 flowchart 语法输出。

请为「多线程推理池」画一张时序图，参与者包括：
主循环、输入队列、工作线程 1、工作线程 2、NPU 核 A、NPU 核 B、输出队列。
要求：
1）按时间顺序列出至少 6 次交互，体现生产者-消费者；
2）标出每个线程各自持有一个 RKNNLite 实例，不是共享；
3）标出线程数超过 NPU 并行能力时会发生什么，排队从哪里开始；
4）用 mermaid 的 sequenceDiagram 语法输出。

06互动：线程数 1→8，帧率为什么涨又为什么跌

📌 这一节是「掌握检查」：亲手改一个参数，看现象是否朝你预期的方向变，还要能说出为什么 —— 说得出，才算掌握。

要改的只有 config/garbage_config.yaml 里的 pool.tpes（命令行 --tpes 可直接覆盖）。下面是配置内容，不用执行：

pool:
  tpes: 2
  core_mask: auto

下面这个实验台把「线程数 → 帧率」画出来。曲线是流水线模型仿真的（NPU 并行能力 + 取帧/后处理与推理的重叠 + 超量线程的排队开销），两个锚点来自板端实测：2 线程 15~18 帧、6 线程 20 帧以上。你手里那三个实测数正好可以拿来对。

三种读法，对应三个不同的问题：

你刚才发现的：线程数不是「越多越快」，它有两个上限 —— 物理上限是 NPU 的并行能力，经济上限是最优点（本板大约 4~6）。

所以在产线上真正要问的不是「开到多少最快」，而是：这条产线要求多少帧？为那几帧多开线程，值不值多占的内存？想清楚这个，参数就定了。

07验证：四道小测

08章节总结：模型只管认细类，查表才管扔哪个桶

这页讲了什么，它们怎么串起来

前置依赖 · 缺一样就跑不起来

这套代码用在哪儿

• 垃圾分拣线：传送带上方架相机，四类结果直接驱动四个料仓的推杆或机械臂。--tpes 按产线节拍调 —— 验收门其实就是「每秒能过几个」。
• 智能垃圾桶：桶盖上方一个摄像头，识别到人手里的东西就开对应的盖子。这类场景帧率要求低，单线程就够，重点在「细类要覆盖你那儿真有的垃圾」。
• 有害垃圾专项筛查：只关心电池、药瓶那几类，可以把它们的 score_thr 调低（宁可多报，交人工复核）—— 阈值属于业务策略，不属于模型。
• 换一套细类就是换一个行业：这个模式能搬去任何「模型识别细类、业务按规则归大类」的场景 —— 快递按区域分、零件按工序分、作物按等级分。只要归类规则由人定，就该写在表里，而不是训进模型。

下一章换个更细的问题：这一章给的是「框」，可如果想知道「这个人形到底占了哪些像素」，框就不够用了 —— 那要用分割。