PokemonCardSearch

宝可梦卡牌识别 · 上线交付包（版本 card_seg_v0904）

打包日期：2026-08-21　包体积：≈5.5 GB　　更新：2026-09-07 双区检索升级 v0904（权重 + 91,116 行图库 + code 全量对齐 249 生产） 沿革：2026-09-04 卡牌分割升级 card_seg_pn_v2；2026-09-06 评级线权重更正为 7-15 -3 版；2026-09-07 本次。 14 个大资产已逐一 MD5 校验，全部对齐生产机 192.168.77.249（249 端五件 v0904 两端比对一致）。见 MD5SUMS.txt。 怎么操作看 README_操作方法.md（链式流程图 + 每步跑什么 + 踩坑），本文只讲"包里有什么、放到哪"。

---

一、版本口径：什么是 card_seg_v0904

card_seg_v0904 是整套版本标签，不是某个模型的名字。它指 「2026-09-04 版 v0904 双区权重 + gallery_v0904 图库特征（91,116 行）」 这一组合。 写死在三处，健康检查会返回它：code/serve_recognition_api.py:47、code/serve_card_match.py:258/325。

⚠️⚠️ 最重要的一条：权重 / 特征库 / 检索后端 三者强绑定，禁止混版

docs/DINOv2重训实验总结报告.md 实测：新老下半区权重对同一张卡产出的向量余弦仅 0.058（近乎正交），上半区 0.466。 → 换权重必须同时换特征库；只换一头等于检索全废。 本包里 models/02_双区检索_v0904/ 与 data/gallery_v0904/gallery_*_features.npy 是配对的，不可拆开单独升级。

---

二、包内目录

上线/
├── README_上线清单.md          ← 本文件（资产清单/MD5/落位）
├── README_操作方法.md          ← ★怎么操作：链式流程图 + 每步跑哪个脚本 + 坑
├── MD5SUMS.txt                 ← 13 个大资产的 MD5，全部对齐 249 生产端
├── 校验上线包.ps1              ← 本地一键自检（PowerShell）
├── models/                     2.4 GB
│   ├── 01_卡牌分割/            card_seg_pn_v2_best.pt
│   ├── 02_双区检索_v0904/      best_upper_half_model.pth + best_layer3_bottom_model.pth  ★核心
│   ├── 03_评级线/              card_v1_best.pt + yolo26s_seg_grading_best.pt
│   └── 04_cat16三属性与编号/   yolo26s_det_rarity/element/card_no _best.pt
├── data/                       781 MB   图库特征库(gallery_v0904) + meta + 字段表 + train_meta_v0904.json(建库输入)
├── code/                       ≈600 KB  服务(含8020 v2) + 检索 + 建库 + 双区训练 + 评级 + 编号 + 属性全部脚本（对齐 249/73 生产）
├── docs/                       260 KB   16 份文档（★宝可梦卡牌识别服务文档接口.md = 8000/8010/8100 三合一契约 + 流程/训练/OCR 政策）
└── offline_cache/              2.4 GB   离线依赖（HF dinov2-large 骨架 + PP-OCRv6 rec）

---

三、模型清单（逐个说明「是什么 / 为什么是最终版」）

models/01_卡牌分割 — 查询侧裁卡

文件	大小	MD5	说明
card_seg_pn_v2_best.pt	23 MB	30d649fc…e21c7	yolo26s-seg 两类合一 {0:pokemon, 1:nba}。card_seg_pn_v2 基于 card_seg_pn_v1 于 2026-09-04 微调而来（微调起点 = v1 best.pt，404 张密集多卡人工标注并入训练集，lr0=0.002 / 50ep；多卡 val Box mAP50 0.826→0.986、召回 0.738→0.98，原 366 张常规 val 零回退）。链路 = mask→4 点→warp 摆正→ensure_portrait 竖放。2026-09-04 起现役（替换 v1；v1 又替换了本包上一版 card_seg_v2-3_best.pt 单类模型）。

618 张 A/B 实测：检测 728.8ms→49.3ms（≈15×），fusion 均值 0.4316→0.4524。详见 docs/卡牌区域检测裁切与旋转正立流程.md。

models/02_双区检索_v0904 — ★核心，最终版权重

文件	大小	MD5	说明
best_upper_half_model.pth	1218 MB	5bbf240f…3c1c6	上半区（认精灵，物种级召回）。dinov2-large，392×196，冻结 18/24 层，InfoNCE T=0.07，name+no 分组，bs=224 / 100ep → best Top-1 87.89%（Ep89，v0904 训练 val）
best_layer3_bottom_model.pth	1218 MB	11fe95a4…4a07	下半区 Layer3（认版本/特效，重排）。bs=8 / 150ep → best 72.50%（40 图小 val，绝对值仅作选版用）

说明：v0904 版双区权重（2026-09-04~06 于 73 训成），搭配 91,116 行 v0904 图库特征，2026-09-07 起 249 三接口（8000/8010/8020）现役。 权威对比口径是 A/B 同尺 h2h（4,066 张 held-out，各版权重 + 各自图库）：上半区 Top-1 84.16%→88.54%、下半区 90.16%→95.84%，双半区胜出 v819。 训练数据 = 91,116 张全量图库（含 +2,728 张 PG 对齐新卡 + 用户手加 4 张 2065–2068/card_id=052065..052068）。

复现坑：下半区必须 CUDA_VISIBLE_DEVICES=1 单卡跑，否则 nn.DataParallel 在 bs=8 下每步复制 1.2G 模型（3.00s/it vs 14.8it/s，慢 44×）。 v819 旧权重已于 2026-09-07 从 73/249 删除，备份在本地 宝可梦\249备份\（5 件 MD5 已验）+ 本包 git 历史早期版本。

models/03_评级线 — 评级公司 / 评级区域

文件	大小	MD5	说明
card_v1_best.pt	20 MB	9962cae8…170b	YOLO26 检测封装壳评级公司标签，11 类：BGS / BGS-AUTHENTIC / BGS-AUTO / CGC / CGC-AUTO / CGC-OLD / PSA / PSA-AUTHENTIC / SGC / SGC-AUTO / SGC-OLD。2000 张测试集评级公司准确率 98.64%
yolo26s_seg_grading_best.pt	23 MB	c7eeb3eb…52e53	评级卡区域分割，12 类。选版定案（2026-09-06 更正）：三版本最终采用 7-15 的 -3 版（已在 114 上把 -3 重命名为 yolo26s_seg_grading 服役，对齐 step1_crop.py / infer_test.py 默认路径，见 评级卡区域研究框架说明.md）；本包内容即该 -3 版（2026-09-06 由 7-10 旧版更正替换，旧版 c185f3ae… 已弃用删除）。

models/04_cat16三属性与编号

文件	大小	MD5	说明
yolo26s_det_rarity_best.pt	20 MB	bfe7c1cc…9653	rarity 检测，25 类
yolo26s_det_element_best.pt	20 MB	a2889d5b…e0a9	element 检测，13 类
yolo26s_card_no_best.pt	20 MB	6e256de9…410f	编号区域检测（conf=0.3）。现役 card_no 链路 = card_seg 裁卡 → 本模型检编号框 → PP-OCRv6_medium_rec（仅 rec，不用 det）→ 单次宽容 modules/card_no_leniency.py → 低分置空。已废弃「固定 ROI + det+rec + 五格式猜号」老方案

---

四、data/ 图库与元数据（与 v0904 权重配对，不可换）

文件	大小	MD5	说明
gallery_v0904/gallery_upper_features.npy	356 MB	52a2c49b…90d2	上半区全库特征 (91116, 1024) float32，L2 归一化
gallery_v0904/gallery_lower_features.npy	356 MB	59b3821b…d9b5	下半区全库特征，同形状，与上半区行对齐
gallery_v0904/gallery_dual_meta.json	14 MB	b2ae9a6d…1ccb	图库元数据，行对齐；字段含 card_id / language / year / card_no / pg_label
card_master_fields.csv	21 MB	079e800e…b78a	卡牌字段表，8/19 从 PG cards_master_v2 全量重导 92,333 条。服务用它出 algorithm_card_name，cascade_match_batch.py 也用它取 img_url 展示
train_meta_v0904.json	26 MB	58bc7696…43ea	建库输入（91,116 条）。records[].fname = record.id.ext 命名的图片文件名，是现役建库脚本唯一认的卡列表

建库过程：★现役脚本是 code/build_dual_gallery_v0904.py（2026-09-06 建成，91,116 行、0 失败）。 ⚠️ 它输出到 data/gallery_v0904/，而落位时 config 就直接指向该子目录（config.py:96-98），无需再搬主路径。 ⚠️ 旧 train_meta_88407.json 的 fname 是旧 synthesis 名、与现图片名不匹配，已从包中移除；映射关系见 _work/rename_final_map.json（md文档整理/训练集/）。 Milvus 回滚重灌脚本 code/scripts/_milvus_rebuild_v819.py（带 PROTECTED 白名单）保留在包内，仅 v819 回滚场景使用。

---

五、offline_cache/ — 离线部署必需

目录	大小	落位
huggingface_hub/models--facebook--dinov2-large	2.3 GB	拷到目标机 ~/.cache/huggingface/hub/（或设 HF_HOME）
paddlex_official_models/PP-OCRv6_medium_rec	74 MB	拷到目标机 ~/.paddlex/official_models/

为什么必需：上/下半区 .pth 只存微调后的 backbone 权重，加载时 Dinov2Model.from_pretrained("facebook/dinov2-large") 会先取 HF 官方骨架再灌权重。若目标机能联网，可不拷，改设 export HF_ENDPOINT=https://hf-mirror.com（feature_extractor_dual.py 已默认该镜像）。

说明：HF 缓存在 Windows 上解包后 snapshots/ 的符号链接变成了真实文件，所以本地看到 2.3 GB（服务器 1.2 GB）。功能不受影响，拷到 Linux 后可直接用；若想省空间，删掉 blobs/ 即可（snapshots/ 里已是完整实体文件）。

---

六、部署：文件落位映射

以框架根 $R = ~/顾工交接/wzj 为准：

包内	→ 目标
models/01_卡牌分割/card_seg_pn_v2_best.pt	$R/ultralytics/runs/segment/card_seg_pn_v2/weights/best.pt
models/02_双区检索_v0904/best_upper_half_model.pth	$R/upper_model_output_v0904/best_upper_half_model.pth
models/02_双区检索_v0904/best_layer3_bottom_model.pth	$R/layer3_bg_model_output_v0904/best_layer3_bottom_model.pth
models/03_评级线/card_v1_best.pt	$R/ultralytics/runs/detect/card_v1/weights/best.pt
models/03_评级线/yolo26s_seg_grading_best.pt	$R/ultralytics/runs/segment/yolo26s_seg_grading-3/weights/best.pt（249 落位用 -3 路径；114 侧现役路径为重命名后的 yolo26s_seg_grading/，两者内容同为此文件）
models/04_cat16三属性与编号/yolo26s_det_rarity_best.pt	$R/ultralytics/runs/detect/yolo26s_det_rarity/weights/best.pt
models/04_cat16三属性与编号/yolo26s_det_element_best.pt	$R/ultralytics/runs/detect/yolo26s_det_element/weights/best.pt
models/04_cat16三属性与编号/yolo26s_card_no_best.pt	$R/ultralytics/runs/detect/yolo26s_card_no/weights/best.pt
data/gallery_v0904/*	$R/data/gallery_v0904/（子目录原样直放，config 指向这里）
data/card_master_fields.csv、data/train_meta_v0904.json	$R/data/（同名直放）
code/*	$R/（保持 pokemon/ scripts/ modules/ tools/ 子目录结构；config.py 若目标机已有现役配置，以现役为准不要覆盖）

换旧权重前务必先备份：mv best_upper_half_model.pth OLD_<日期>_best_upper_half_model.pth。

---

七、启动与自检

启动方法见 docs/宝可梦卡牌识别服务文档接口.md 附录。

加载约 25–30s。健康检查应返回：

{"status":"ok","gallery_size":91116,"model_version":"card_seg_v0904"}

gallery_size 必须是 91116——若是 88384/78272，说明特征库还是旧版，权重/图库混版了，立刻停。

★ /health 会「假 ok」，必须再打一个真实请求才算验过（冒烟 curl 见 docs/宝可梦卡牌识别服务文档接口.md 附录·自检，预期 card_id=04101495、match_rate≈96）。

---

八、服务器配置

部署服务器：192.168.77.249（用户 martin）

• 框架根目录：~/顾工交接/wzj
• GPU 铁律：物理 index0 = GTX1060（cu128 不支持，禁用）；index1/2 = V100。启动必须两变量一起写： CUDA_DEVICE_ORDER=PCI_BUS_ID CUDA_VISIBLE_DEVICES=N（8000→2，8010→1，8020→1,2）
• 检索后端：CASCADE_BACKEND="gpu"（双区特征库 fp32 常驻显存，召回 0.4ms/卡；2026-09-03 起）
• 相似度阈值：SIMILARITY_THRESHOLD = 0.50（config.py:75）
• Milvus（回滚兜底）：pokemon_dual_upper_dinov2l_1024 / pokemon_dual_lower_dinov2l_1024，回滚时 config 改 "milvus" + 重启

---

九、未收录内容说明

未收录	原因
gallery_images/（8.8 万张库图）	约几十 GB，服务运行不需要（只在重建特征库时需要）
Milvus 数据文件	用 scripts/_milvus_rebuild_v819.py 重灌而非拷文件

---

十、后续维护要点

• 新增卡片入库不需要重训：新图抽特征 → append 到 data/gallery_v0904/gallery_*_features.npy + gallery_dual_meta.json 即可（模型与图库解耦；gpu 后端直接生效，Milvus 兜底另需 insert）。
• 真要重训：权重 + 特征库 必须整套同步换，且下半区必须保持混淆对挖矿策略（改成全量分组已被证伪一次）。流程与脚本见 code/ 内 prepare_train_data_v3.py → mine_layer3_step1/2(_v0904).py → train_dinov2_layer3_bottom(_v0904).py / train_dinov2_upper_half(_v0904).py，权威文档 训练集/dinov2上下半卡训练框架与参数.md。
• 重训前先评估漂移：参考 docs/DINOv2重训实验总结报告.md 的对比方法 + code/ab_test_v0904.py（A/B 同尺 h2h，本次 v0904 的胜出判据）。

---

附：本地自检

PowerShell 里一行：

D:\顾工交接\wzj\宝可梦\上线\校验上线包.ps1

逐个核对 13 个资产的 MD5 与体积，并检查 code/ docs/ offline_cache/ 是否齐全。