ddai10/filter-aqs-v3

滤光片暗场外观判废 v3 · 可直接运行版（Linux x86_64）

下载、解压后直接运行。不需要另装 Python、CUDA、cuDNN 或任何 pip 包，只需要 NVIDIA 显卡驱动。

训练数据：daipath/appearance-quality-stats（不含旧数据），性能不良算不良。打包日期 2026-10-31。

v3 和 v2 的区别： 标准版从 8 个集成成员加到 10 个，新加了 SigLIP2-so400m 和 DINOv2-L（带 register）两个冻结骨干的判别头。默认阈值下，外观漏检基本不变（1.38% → 1.44%），误检从 2.27% 降到 1.75%，最差批次的误检从 8.6% 降到 4.9%。这两个成员是看着这 8 个批次挑的，所以这组数字偏乐观；按更严格的估计，误检约 1.9–2.1%，最差批次约 5.5–6.8%，也就是误检实际大约降 0.2–0.4 个百分点（见「指标速览」）。误检的改善几乎都来自 38028_P17 这一批里 632×632 格式的良品（这批误检 8.6% → 4.9%），其余批次基本不变；外观不良最多的 38028_P10 批次，外观漏检反而从 5.6% 升到约 6.6–6.8%。代价是速度慢了一半多，所以包里同时保留了原来的 8 成员版，叫“快速版”，分数和 v2 标准版完全一样。

包里有什么

文件 / 目录	内容
predict	标准版（10 个成员，误检最少，默认用这个）。7 个模型文件：DINOv2-L、DINOv3-L、DINOv2-B 各带 2 个判别头，SigLIP2-so400m、DINOv2-L-reg 各带 1 个判别头，加 convnext_small、edgenext 两个 CNN。程序里显示为“7 个模型文件（共 10 个集成成员）”。
predict-fast	快速版（8 个成员，就是 v2 的标准版）：比标准版少 SigLIP2 和 DINOv2-L-reg 两个成员，速度约是标准版的 2.2 倍。
predict-lite	轻量版（4 个成员）：DINOv2-B（2 个判别头）+ convnext_small + edgenext。
examples/	10 张样例图（良品/ 4 张、不良/ 6 张）和 预期结果.csv，解压后就能拿来试
standard/、fast/、lite/	三个版本各自的模型（ONNX）、自检用的内置图（fixtures/，程序自动使用，和 examples/ 无关）、详细说明 README.md（预设、阈值、能力边界）。三个版本共用的模型文件在磁盘上只存一份。
runtime/	自带的 Python 3.12 + onnxruntime-gpu 1.31.1 + CUDA 13 / cuDNN 9 运行库

用哪个：

• 一般用标准版。 在 RTX 5080 上估计每小时能处理约 1.8–2.5 万张（见下文「速度」）。它比快速版好的地方主要在 632×632 格式的良品上（误检少）；产线如果不用 632×632 格式，两个版本的误检差别很小，用快速版也可以。
• 每小时要处理的图超过约 1.8 万张时，用快速版（5080 上约 4.1–5.5 万张/小时）。默认阈值下误检 2.27%，比标准版多约 0.5 个百分点（按严格估计约多 0.2–0.4 个百分点）；最差批次 8.6%，标准版 4.9%（严格估计约 5.5–6.8%）。
• 没有显卡，或者要更快时，用轻量版（5080 上约 24–30 万张/小时）。默认阈值下误检约 3.27%，最差批次 14.9%。

机器要求

• 系统： Linux x86_64，推荐 Ubuntu 22.04 或 24.04。程序本身在 glibc ≥ 2.28 的系统上都能跑（如 Debian 10+、RHEL/Rocky 8+），但 Ubuntu 20.04 上很难装到足够新的显卡驱动。

• 显卡驱动： 版本 ≥ 580，推荐 590 以上；我们在 595.91 上测试通过。运行 nvidia-smi，右上角 CUDA Version 要 ≥ 13.0。

  • RTX 50 系（包括 5080）在 Linux 上必须装带 -open 的驱动，例如 Ubuntu 的 nvidia-driver-580-open 或更新版本。sudo ubuntu-drivers install 一般会自动选对。

• 显存： 标准版批 8 峰值约 13.3 GB（nvidia-smi 上约 13,600 MiB），16 GB 的 5080 够用（这是在 16 GB 卡上测的；显存更大的卡上程序会多占一些，属正常），但运行时不要再开别的占显存的程序；快速版约 10 GB，轻量版约 4 GB。同一时间只运行一个程序。显存不够时程序会自动把一批拆小重算，结果不变，只是慢一些。

• 磁盘： 压缩包约 7.2 GB，解压后约 8.8 GB。解压时需要约 16 GB 空闲空间，解压完可以删掉压缩包。

• 内存： 用显卡时约 3 GB。没有显卡（用 CPU）时批 8 的峰值：标准版约 23 GB，快速版约 9 GB，轻量版约 3 GB。内存不到 32 GB 的电脑不要用 CPU 跑标准版。

• 没有显卡也能跑（自动改用 CPU），但慢很多：

  • 轻量版约 0.5 秒/张，每小时约 7,000 张；
  • 快速版约 2.3 秒/张，每小时约 1,500 张；
  • 标准版约 5 秒/张，每小时约 700 张。

  后两个都达不到每小时 3,600 张。这是在我们的测试服务器（Xeon Gold 6530，16 线程）上测的，换 CPU 会有差别，可以用 ./predict-lite --device cpu --bench 实测。

下载和解压

仓库是私有的，需要用有权限的账号或 token 下载。给工厂电脑用时，建议在 HF 上建一个只读、只限这个仓库的 fine-grained token。

# 方法一：网页登录 HF → 仓库页面 → Files → 下载 filter-aqs-v3-linux-x64.tar.gz 和 SHA256SUMS
#         （网页上的 examples 文件夹可以直接点开看样例图；压缩包里也带了同样的样例）

# 方法二：命令行。先输入 token（输入时不显示，也不会留在命令历史里）
read -rs HF_TOKEN; export HF_TOKEN
for f in filter-aqs-v3-linux-x64.tar.gz SHA256SUMS; do
  curl -fL --retry 5 -C - -H "Authorization: Bearer $HF_TOKEN" -o "$f" \
       "https://huggingface.co/daipath/filter-aqs-v3/resolve/main/$f"
done
# 断了重新运行同一段即可续传；curl 报错（例如 401）说明 token 不对或没有权限

# 方法三：装了 hf 命令行工具的话（仓库是私有的，要先 hf auth login，或先执行方法二第一行设好 HF_TOKEN）
# hf download daipath/filter-aqs-v3 --local-dir .

sha256sum -c SHA256SUMS          # 显示 OK 才说明下载完整
tar xzf filter-aqs-v3-linux-x64.tar.gz      # 约 1–2 分钟
cd filter-aqs-v3
./predict --selftest             # 第一次用先自检，最后一行显示“自检通过”才能用
./predict examples               # 跑 10 张样例图，应该 10 张全对（见下一节）

• 请在 Linux 上解压到 Linux 磁盘（ext4 等）里。不要在 Windows 上解压后再拷过来，也不要解压到 U 盘的 exFAT/NTFS 分区，否则会丢失文件链接和可执行权限。
• 整个 filter-aqs-v3 文件夹可以放到任意位置、改名。不要把 predict 等脚本单独拷走，它们要和 runtime/、standard/、fast/、lite/ 在一起；做软链接可以。
• 解压目录可以设成只读，程序运行时不会往里面写东西。

先拿例子试一下

解压后的 examples/ 里有 10 张样例图：良品 4 张，不良 6 张（5 种外观不良 + 1 张性能不良）。性能不良那张能判出来，是因为图上有人工画的框；产线图上没有框，本模型不能代替性能检测。在 HF 网页上点开 examples/ 文件夹，也可以直接看这些图。

./predict examples                       # 逐张显示：判定、不良分、文件名
./predict --evaluate examples            # 按验收口径算两个桶
./predict examples --csv ~/例子结果.csv    # 写成 CSV，和 examples/预期结果.csv 行顺序相同，可以并排对照

标准版的正常输出如下（第一行是设备信息，之后每张一行：判定、不良分、文件名；快速版、轻量版分数略有不同，判定一样）：

7 个模型文件（共 10 个集成成员），运行设备：GPU（CUDAExecutionProvider）
不良     0.9921  examples/不良/外观_侧崩碎裂.png
不良     0.9988  examples/不良/外观_划伤.png
不良     0.9998  examples/不良/外观_崩边崩角.png
不良     0.9978  examples/不良/外观_白点脏污.png
不良     0.9949  examples/不良/外观_麻点脏污.png
不良     0.9999  examples/不良/性能不良_带框.png
良品     0.0004  examples/良品/良品_1_40-20.png
良品     0.0000  examples/良品/良品_2_20-10.png
良品     0.0016  examples/良品/良品_3_632x632格式.png
良品     0.0006  examples/良品/良品_4_38030批次.png
合计：不良 6，良品 4（阈值 0.2557）

• 判定和上面一样就说明程序正常。分数最后一位可能略有差别，没关系。
• 这些图来自训练数据，只能用来确认程序跑通，不代表准确率。
  • 每一类选的是交叉验证分数居中的图，不是专挑最好认的。
  • 但训练数据里良品和不良是分盘拍的，产线上混在一起拍的图，分数不会这么两极（见下文「指标速览」最后的“上线前必须用产线现场图验收”）。
  • 准确率要用产线现场的新图验收，详见 examples/README.md。
• 自己的图怎么放： 把图片放进一个目录（可以有子目录，png/jpg/bmp/tif 都行），运行 ./predict 目录 --csv ~/结果.csv。
  • 要算验收指标的话，在目录下建「良品」「不良」两个子目录分别放图，运行 ./predict --evaluate 目录。
  • 「不良」里只放外观不良。--evaluate 不区分不良种类，放了性能不良图会混进漏检率。

常用命令

和源码版的 python predict.py ... 完全相同，只是换成 ./predict（快速版换成 ./predict-fast，轻量版换成 ./predict-lite）：

命令	作用
./predict --selftest	自检：逐个模型核对内置自检图的输出，全部 ✔ 才能用。第一行出现“运行设备：GPU”就是用上了显卡
./predict /图片目录 --csv ~/结果.csv	用默认阈值（高检出）判定，结果写成 CSV（文件、不良分、判定、阈值）。CSV 请写到自己的目录，不要写进解压目录
./predict /图片目录 -t 0.3	自定阈值：分数 ≥ 阈值判不良。阈值越低，漏检越少、误检越多
./predict --thresholds	阈值对照表：每个阈值预计的外观漏检、误检和两个桶的比例（不加载模型，秒出）
./predict --list-presets	查看预设（高检出 / 均衡 / 保良品），用 --preset 均衡 切换
./predict --evaluate 已标注目录 --sweep	验收：目录下放「良品」「不良」两个子目录，逐个阈值列出你自己数据上的漏检、误检和两个桶的比例
./predict --calibrate 已标注目录 --target-recall 0.99	按批次标定阈值。0.99 表示这批不良至少 99% 要被检出，需要约 300 张不良
./predict /图片目录 --triage	三区分流：放行 / 人工复核 / 判废
./predict --bench	本机测速。输出是 ms/张，每小时张数 ≈ 3,600,000 ÷ 这个数（例如 108 ms/张 ≈ 3.3 万张/小时）
--device gpu/cpu、--batch-size 8、--workers 8、-q	设备、批大小、读图线程数、不逐张打印

• 三个版本的分数刻度不同，阈值不能混用。 例如标准版的默认阈值是 0.2557，快速版是 0.1999。用 -t 自定阈值时，要按所用版本的 --thresholds 对照表来选。
• 两个桶是你的验收口径：判为良品的那堆里混进了多少不良；判为不良的那堆里有多少其实是良品。
• 运行方式： 每次运行前程序会自动做一次快速自检，不通过就拒绝运行。CSV 是边算边写的，中途按 Ctrl-C，已经算完的结果会保留。
• 退出码： 0 = 全部成功，1 = 出错，2 = 有图片读取失败（这些图在输出和 CSV 里标为“读取失败”），130 = 被中断。

速度（需求：每小时 3,600–36,000 张）

版本	RTX 5090 实测（批 8，端到端）	RTX 5080 估计
标准版（10 个成员）	约 108 ms/张（约 3.3 万张/小时）	批 8 约 1.8–2.5 万张/小时；批大小 1 约 1.7–2.2 万张/小时
快速版（8 个成员）	约 49 ms/张（约 7.4 万张/小时）	批 8 约 4.1–5.5 万张/小时；批大小 1 约 3.4–4.4 万张/小时
轻量版（4 个成员）	约 9 ms/张（约 40 万张/小时）	批 8 约 24–30 万张/小时；批大小 1 约 9–13 万张/小时

• 标准版在 5080 上达不到每小时 3.6 万张。 每小时超过约 1.8 万张时请用快速版，或者两块显卡各跑一部分图。
• RTX 5080 的数字是在 5090 上限制显存和计算单元模拟出来的：区间的高端是只用一半计算单元的实测，低端按 FP32 算力比（5090 / 5080 ≈ 1.86）保守换算。到实机上请用 ./predict --bench 复测。
• 不要每张图启动一次程序。 每次启动都要加载模型并自检：标准版约 10 秒，快速版约 8 秒，轻量版约 4 秒；第一次启动要从硬盘读模型，会更慢。请把一批图放进一个目录一次处理。表里“批大小 1”也是指一次运行处理整个目录、一张一张送进显卡。

指标速览（交叉验证估计，详见解压后的 standard/README.md）

8 个“批次号_炉号”单元轮流当新批次测试，阈值只用其余 7 个批次定，8 个批次取平均：

标准版预设	阈值	外观漏检	误检	判良品中不良（产线不良率 10%，按外观漏检算）	判不良中良品（产线不良率 10%，按外观漏检算）
高检出（默认）	0.2557	1.44%（最差批次 6.8%）	1.75%（最差批次 4.9%）	0.16%	12.3%
均衡	0.5918	2.84%（最差批次 11.4%）	1.16%（最差批次 3.1%）	0.32%	8.9%
保良品	0.7809	4.34%（最差批次 11.3%）	0.90%（最差批次 2.7%）	0.48%	7.0%

快速版（8 个成员）同样口径：高检出 1.38% / 2.27%（最差批次 5.6% / 8.6%），两个桶 0.16% / 14.2%；均衡 2.84% / 1.28%；保良品 4.82% / 0.86%。

• 外观漏检 = 崩边、划伤、麻点脏污等外观不良被判成良品的比例。看漏检时只看这一项，不要看含性能不良的“全部漏检”。
• 最后两列是你的验收口径（两个桶），按外观漏检、产线不良率 10% 换算：每个批次先各自换算，再 8 批取平均。./predict --thresholds 也按外观漏检、10% 换算，但它是先把 8 批的漏检、误检取平均再换算，阈值也是固定的，所以同一阈值下数字会有出入（默认阈值：上表判不良中良品 12.3%，--thresholds 14.5%）。standard/README.md 表里同名的列是按全部不良（含性能不良）的漏检换算的，所以判良品中不良会更小（例如默认 0.11% 对 0.16%），两边不矛盾。
• 新加的两个成员是在这 8 个批次上从 69 个候选里挑出来的，上表偏乐观。 更严格的估计是每个批次都只用其余 7 个批次重新挑这两个成员，再在这个批次上测：默认阈值下误检约 1.9–2.1%（上表 1.75%，快速版 2.27%），最差批次约 5.5–6.8%（上表 4.9%，快速版 8.6%），外观漏检基本不变。范围来自两次严格估计（两个新成员的特征分别按 bf16 和 fp32 提取，各批次挑中的成员不完全一样）。所以加两个成员后误检实际大约降 0.2–0.4 个百分点，比上表显示的 0.5 小，而且几乎都降在 38028_P17 这批 632×632 格式的良品上。原来的 8 个成员也是看着这 8 个批次定的，两个版本的数字都略偏乐观。
• 性能不良： 训练图上有人工画的框，模型是靠这个框认出来的，所以在训练数据里几乎不漏。产线图上没有这个框，本模型不能代替性能检测。
• 判不良中良品： 产线上良品占九成，所以即使误检只有 1.75%，判为不良的那堆里也会有约 12–14% 是良品（每批先换算再平均约 12%，用平均误检直接换算约 14%）。要把它压到 1%，误检需要低到约 0.1%，目前做不到。
• 同一个阈值会看到几种数字，原因是算法不同：
  • 上表：阈值也只用其余 7 个批次重新定，是跨批次估计。
  • ./predict --thresholds：固定阈值，逐批测量后取平均。和上表比，外观漏检通常低一些，误检和判不良中良品不一定（默认阈值：外观漏检 1.12% 对 1.44%，误检 1.86% 对 1.75%，判不良中良品 14.5% 对 12.3%）。
  • --evaluate：把所有图合在一起算，大批次分量更重。按这种算法，标准版默认阈值下外观漏检约 1.6%、误检约 2.4%（快速版约 1.6% / 3.0%）。
• 想让外观漏检和误检差不多： 标准版用 -t 0.34：所有图合在一起算，两者都约 2.0%；固定这个阈值逐批测量再平均（和 --thresholds 同算法）约 1.3% / 1.6%。快速版用 -t 0.33：所有图合在一起算两者都约 2.1–2.2%，逐批平均约 1.3% / 1.7%。

上线前必须用产线现场图验收。 训练数据里良品和不良是分盘、分开拍的，模型学到了一部分“这一盘的拍摄样子”，交叉验证查不出来。按模拟估计（用 8 成员版做的），产线上良品和不良同场拍摄时，可能出现下面两种情况之一：

• 外观漏检约 4%（2–9%）；
• 误检约 9%（6–20%）。

加了两个成员并不能解决这个问题。请在产线工位上把良品和外观不良混在同一批拍：建议至少 3 个批次，每批 ≥500 良品 + ≥200 外观不良。然后用 ./predict --evaluate 目录 --sweep 验收并定阈值。

常见问题

• 显示“运行设备：CPU”，或出现 ⚠ 提示、大段英文 EP Error： GPU 没用上。用 nvidia-smi 检查驱动版本是否 ≥ 580（50 系要用 -open 驱动）；加 --device gpu 可以看到具体报错。没有显卡的电脑请加 --device cpu，就不会有这些提示。
• Permission denied 或 not found： 多半是在 Windows 上解压过，丢了权限和链接。请在 Linux 上重新解压。
• 自检失败： 说明文件损坏或被改动。重新下载，并用 sha256sum -c SHA256SUMS 核对。
• 无法写入 CSV： 换一个有写权限的位置，例如 --csv ~/结果.csv。
• 显存不够（出现 out of memory 提示或速度突然变慢）： 关掉其他占显存的程序，或者改用快速版 / 轻量版。
• Windows： 这个包只能在 Linux 上运行。Windows 电脑可以试 WSL2 + Ubuntu 24.04，解压到 Linux 的家目录（不要放在 /mnt/c 下），这种用法我们没有测过。
• 输出格式： 不良分是 0~1，越高越像不良。CSV 是 UTF-8（带 BOM），可以直接用 Excel 打开。