# 宝可梦卡牌识别 · 上线交付包（版本 `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。健康检查应返回：

```json
{"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 里一行：

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

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