# 下线 pHash 去重 + FashionSigLIP「疑似同款」提示 — 设计文档

- 日期：2026-10-12
- 状态：待实现
- 相关代码：`internal/pkg/phash`、`internal/service/ingest_service.go`、`internal/repository/ingest_repository.go`、`internal/handler/backstage_handler.go`

---

## 1. 背景

现有图片去重基于 `internal/pkg/phash` 的 dHash（64 位），存入图片表的 `phash vector(64)` 列，配HNSW 索引（`brand_runway_images_phash_hnsw` / `street_snap_images_phash_hnsw`，L2 距离），在 `IngestService.dedupImage` 中判定，命中则写 `is_duplicate` + `dup_of`，前台折叠、后台显示「重复」徽章与重复率统计。

dHash 只看像素，只能识别「同一文件被重复上传 / 裁剪 / 缩放 / 重压缩」，识别不了「同一件衣服被不同角度重新拍摄」。且这套机制带来持续的维护成本：`is_duplicate` / `dup_of` 是持久化关系，删图、删文章时都必须重算（`article_service.go`、`street_snap_service.go` 各有一段专门的重算逻辑）。

**决策：下线整套自动去重**，不再有任何自动折叠，重复图全部平铺，靠人工清理。

新项目 `D:\project\fashion-siglip` 已用 `marqo-fashionSigLIP`（open_clip，ViT-B/16 SigLIP）验证语义向量可行：图片编码为归一化向量后，余弦相似度可反映语义层面的相似性。**SigLIP 只用于后台提示「疑似同款」，不参与任何去重判定。**

## 2. 目标

1. 下线 pHash 去重能力（代码、schema、模板、统计、测试一并清理）。
2. 新增独立 Python 视觉服务，常驻加载 FashionSigLIP，提供图片向量（embed）能力。
3. Go worker 入库时获取向量落库；后台查看图集时展示「疑似同款」提示。

## 3. 非目标（YAGNI）

- **不做自动去重、不做自动折叠**（本次明确下线）。
- 不做文本搜图 / 图文跨模态检索。
- 不实现 `/classify` 分类接口（仅在服务边界预留）。
- 不回填历史图片向量。
- 不做阈值自动调优。

## 4. 架构总览

```
                    ┌──────────────────────────────┐
   spider ──HTTP──▶ │  Go server (worker)          │
                    │  IngestService               │
                    │   下载 → embed ──上传         │
                    └───┬──────────────────┬───────┘
                        │ 写/查向量         │ POST /embed (批量)
                        ▼                  ▼
              ┌───────────────────┐  ┌───────────────────────────┐
              │  PostgreSQL       │  │  Python 视觉服务 (CPU)    │
              │  image_embeddings │◀─│  FashionSigLIP 常驻       │
              │  (vector(768)+HNSW)│  │  /embed  /health         │
              └───────────────────┘  └───────────────────────────┘
                        ▲
                        │ 后台看图集时按需 HNSW 查询
                        │
                  BackstageHandler
```

**进程边界理由**：FashionSigLIP 是 PyTorch 模型，Go 无法直接执行。独立服务做到模型常驻一次、与 Go 发布解耦，并为将来分类能力复用同一进程。

## 5. 下线现有去重能力（删除清单）

### 5.1 代码

| 位置 | 删除内容 |
|---|---|
| `internal/pkg/phash/` | 整个包（`phash.go`、`phash_test.go`） |
| `internal/model/runway_image.go`、`internal/model/street_snap.go` | `Phash` / `IsDuplicate` / `DupOf` 字段 |
| `internal/service/ingest_service.go` | `dedupImage()` 整个函数；`concurrentFetch` 中 `res.phashBits` 计算；`timing` 的 `phash` / `dedup` 字段；落库处 `Phash` / `IsDuplicate` 赋值；`formatTiming` 中「phash / 近重复」两段 |
| `internal/service/article_service.go:297-354` | 删图 / 下架时的 `dup_of` 重算逻辑 |
| `internal/service/street_snap_service.go:398-449` | 同上 |
| `internal/repository/ingest_repository.go` | `FindNearDuplicateImage`；写入处 `phash` / `is_duplicate` / `dup_of` 三列 |
| `internal/repository/article_repository.go:430` | `phash <->` 近邻查询 |
| `internal/repository/street_snap_repository.go:372` | 同上 |
| `internal/repository/admin_repository.go` | 重复率统计查询 |
| `internal/handler/backstage_handler.go` | 重复率统计（约 333/388 行）、徽章与折叠数据装配（约 683/702/713/732 等）、`buildDupSources`（约 961 行起） |
| `internal/handler/templates/partials.html:62` | 「重复」徽章与折叠模板 |
| `cmd/diagdup/` | 整个诊断命令 |

### 5.2 Schema（新增迁移）

- `brand_runway_images`：DROP 列 `phash` / `is_duplicate` / `dup_of`，DROP 索引 `brand_runway_images_phash_hnsw`
- `street_snap_images`：DROP 列同上，DROP 索引 `street_snap_images_phash_hnsw`
- DROP 死表 `image_duplicates`（2026-09-21 建表后全仓零引用，已确认的死物）

> 该迁移不可逆（**已确认接受**），执行前确认 `db/backups/` 里有备份。

### 5.3 测试

- 删除 `internal/repository/dedup_integration_test.go`
- 清理 `editor_image_delete_integration_test.go`、`ingest_single_table_integration_test.go` 中依赖 `phash.ToVectorBits` / 重复标记的用例
- 清理 `internal/service/ingest_image_count_test.go` 中 fake 仓储的 `FindNearDuplicateImage` 方法
- 清理 `cmd/dbtool/main.go` 中相关引用
- 更新 `README.md` 中 pHash / 去重的描述

### 5.4 保留

**`sha1` 批次内内容去重保留**——它是内容哈希（同一 URL / 同一文件在一次入库批次内只处理一次），与 pHash 无关，且几乎零成本。

## 6. Python 视觉服务

由 `D:\project\fashion-siglip` 改造而来（现有 `embed_images.py` / `compare_images.py` 是每次重新加载模型的脚本原型，不可直接用于生产）。

### 6.1 接口契约

| 接口 | 入参 | 出参 | 说明 |
|---|---|---|---|
| `POST /embed` | `{"images": ["<图片字节的 base64 数组>"]}` | `{"dim": 768, "vectors": [[...], ...]}` | 批量编码；向量已 L2 归一化 |
| `GET /health` | — | `{"ok": true, "dim": 768, "device": "cpu"}` | 探活与维度自检 |

- 单批上限由服务侧限制（建议 ≤ 32 张）。
- 损坏 / 无法解码的图片跳过，不导致整批失败。
- 维度**已由 M0 spike 实测确认为 768**（`marqo-fashionSigLIP` 输出 768 维，非 512）。Go 侧 `vision.dim` 默认值与 `image_embeddings.embedding` 列类型均按 768 处理。

### 6.2 部署

- 生产无 GPU，**CPU 推理**。日入库几百张的量级，CPU 足够。
- 依赖本地模型缓存（沿用现有脚本的 `HF_HUB_OFFLINE=1` 策略），避免运行时网络请求。
- 独立进程 / 容器，仅监听内网。

### 6.3 启动方式与端口

- **框架**：FastAPI + uvicorn（异步、批量接口顺手、自带 `/docs` 便于排查）。
- **端口**：`8900`，与 Go 侧 `vision.endpoint` 默认值一致；生产仅监听 `127.0.0.1`，启动前确认端口未被占用。
- **模型常驻单进程**：在应用 lifespan 启动阶段加载一次；加载完成前 `/health` 返回 `ready=false`，避免首个请求承担加载延迟并被 Go 侧超时打断。
- **`--workers 1`**：模型常驻进程内，多 worker 会各加载一份模型导致内存翻倍；吞吐靠**批量**（单次 `/embed` 传多张）提升，不靠多进程。
- **生产离线**：模型权重烤进镜像或挂载至 `HF_HOME`，并设 `HF_HUB_OFFLINE=1`，避免运行时访问 HuggingFace。
- **配置项**（环境变量）：`VISION_HOST` / `VISION_PORT` / `VISION_MODEL` / `HF_HOME`。
- **部署**：独立 Dockerfile（`python:3.11-slim` + CPU 版 torch + open_clip + Pillow），健康检查打 `/health`。

启动命令：

```bash
# 本地开发：用项目自带的 .venv（torch 2.14.1+cu132，走GPU）
.venv/Scripts/python.exe -m uvicorn app:app --host 127.0.0.1 --port 8900 --workers 1

# 生产：CPU 版 torch 的容器
uvicorn app:app --host 127.0.0.1 --port 8900 --workers 1
```

> 本地 `.venv` 已具备 CUDA 版 torch，无需重复安装；`fastapi` / `uvicorn` 已装入该venv。
> 服务会**自动探测** `cuda` 可用性并使用GPU，不可用时回退 CPU，无需配置区分。

## 7. Go 侧集成

在现有 `concurrentFetch` 的并发段中插入 embed 调用：

```
并发段（每张图）：下载 → embed → 上传
串行段（按下标）：组装 → 落库（同时写入图片记录与 image_embeddings）
```

- 向量随图片记录一起写入 `image_embeddings`。
- embed 失败 / 超时 → 不写 embedding 行，**不阻断入库**。
- `timing` 结构新增 `embed` 字段，沿用既有各阶段的统计方式。

## 8. 数据模型——复用 `image_embeddings`

该表**已存在**（当前列类型 `vector(512)` + 已建好的 HNSW 余弦索引 `image_embeddings_vec_idx`），但全仓零代码引用、零数据，是死表。直接复用，不在两张图片表新增列。

```sql
-- 目标结构
image_embeddings (
  id         bigint identity primary key,
  image_id   integer not null,
  kind       varchar(8) not null,          -- runway | street，对齐 dto.IngestKind
  embedding  vector(768),                 -- 实测维度，由 512 扩到 768
  created_at integer not null default 0
)
```

需要三处改造（同样在迁移中）：

1. **`embedding` 由 `vector(512)` 改为 `vector(768)`**：M0 spike 实测模型输出 768 维。表中无数据，类型变更即时完成。
2. **`kind` 由 `smallint` 改为 `varchar(8)`**，取值对齐既有的 `dto.IngestKind`（`"runway"` / `"street"`），与 `image_duplicates` 当年用 `varchar` 的做法一致。表中无数据、无代码引用，改动安全。
3. **新增唯一索引 `(kind, image_id)`**：现表只有 `id` 主键、没有业务唯一约束，不加会导致同一张图重复写入多行。

> HNSW 索引 `image_embeddings_vec_idx` 建在 `embedding` 上，列类型变更后需重建索引。

**软删一致性**：图片表有 `is_deleted`，`image_embeddings` 没有。删图后向量会残留，因此**读侧必须 join 图片表过滤 `is_deleted = 0`**（沿用 `image_duplicates` 当年的处理约定，不做主动级联清理）。

**不存持久化的「同款关系」**——同款提示在后台查看时现算现展示，避免新增/删图导致的陈旧标记。

## 9. 「疑似同款」判定与展示

- 后台查看图集时，对每张有向量的图做一次 HNSW top-k 近邻查询（k 建议 5）。
- 余弦相似度 ≥ `vision.similar_threshold` →挂「疑似同款」标签，显示「与 #\<id\> 相似 0.70」，可跳转对比。
- **阈值必须实测校准，不可拍脑袋定**（见 §12）。初稿假设的 0.85 已被实测证伪。
- **只排除图片自身**；同文章内的近邻同样参与提示——这能发现同一图集里的连拍糊片。
- **仅后台可见**，不影响前台展示、不写入任何「重复」语义。

## 10. 配置项

| 配置 | 默认值 | 说明 |
|---|---|---|
| `vision.enabled` | `false` | 总开关，关闭则完全跳过 embed |
| `vision.endpoint` | `http://127.0.0.1:8900` | 服务地址 |
| `vision.timeout` | `5s` | 单批超时 |
| `vision.dim` | `768` | 向量维度（须与模型一致，已实测确认） |
| `vision.similar_threshold` | `0.85` | 「疑似同款」相似度阈值 |
| `vision.fail_threshold` | `3` | 连续失败多少次后熔断冷却 |

## 11. 降级与容错

核心原则：**视觉服务不可用绝不能影响入库。**

| 故障 | 行为 |
|---|---|
| 服务未启用 | 跳过 embed，不写 embedding 行 |
| 连接失败 / 超时 | 该批向量为空，记日志，继续入库 |
| 连续失败 ≥ `fail_threshold` | 熔断冷却 **5 分钟**，期间直接跳过 embed（避免每张图都卡超时） |
| 返回维度与配置不符 | 拒绝写入并告警，防止写入脏数据 |

冷却结束后半开重试一次，成功则恢复。

## 12. 阈值校准（必须做，不可跳过）

**已实测到的关键反例**：`c1.jpg` 与 `c2.jpg` 是同一个人、同一地点、同一套穿搭（麂皮短外套 + 格纹百褶裙 + 麂皮短靴 + 托特包）的连拍，仅姿势不同——属于最典型的「同款不同拍」，但**余弦相似度只有 0.6965**。

初稿假设的 `0.85` 因此被证伪：按该阈值，这两张最该被认出来的图反而认不出来，会大量漏判。CLIP 类模型的归一化余弦相似度整体偏低，「同款不同拍」通常落在 **0.6~0.8**，「不同图」落在 0.3~0.5，真实分界线约在 **0.65~0.70**。

校准方法：取一批已知「同款不同拍」与「不同款」样本，统计相似度分布，确认两个分布的可分性，再定 `similar_threshold`。**至少需要覆盖：同套连拍、同款不同场次、不同款同风格**三类样本。

因该阈值只影响一个后台提示标签、不影响前台展示与任何去重逻辑，可以偏宽松（宁可多提示）。

## 13. 测试策略

**Go 侧**
- 入库主流程回归：图片正常入库，删除 phash 后 `go build ./...` 与全部现有测试通过。
- 降级路径：视觉服务返回错误 / 超时 / 维度不符时，入库正常完成且不产生 embedding 行。
- `vision.enabled=false` 时不产生任何 embed 请求。
- 同款查询：读侧正确过滤 `is_deleted = 1` 的图片。

**Python 侧**
- `/embed` 返回维度正确、向量已 L2 归一化（模长≈1）。
- 损坏图片被跳过而非整批失败。
- `/health` 可用。

## 14. 里程碑

**已确认：下线去重与 SigLIP 集成合成一个大改动**（同分支、同一次交付），内部按下列顺序推进，每步保持可编译、可回归。

**M0 — spike（已完成）**
把 `fashion-siglip` 包成常驻 `/embed` 服务（`app.py` + `smoke_test.py`），实测结论：

| 项 | 实测值 |
|---|---|
| 向量维度 | **768**（非设计初稿假设的 512，schema 与配置已按 768 修正） |
| 模型加载 | CPU 1.9s / GPU 2.5s（启动时一次） |
| CPU 推理 | 3 张图 217ms（约 **72ms/张**，`torch 2.14.0+cpu`） |
| GPU 推理 | 3 张图 57ms（约 **19ms/张**，`torch 2.14.1+cu132`，RTX 5060 Ti） |
| GPU/CPU 一致性 | 同一批图相似度 0.6965(GPU) vs 0.6964(CPU)，**数值一致** |
| 向量归一化 | 模长 1.0000，点积即余弦相似度 |

结论：

1. CPU 单图约 72ms，日入库几百张的量级完全无压力，**生产无 GPU 的部署假设成立**。
2. 本地 GPU 比 CPU 快约 3.8 倍，且**两种设备算出的向量数值一致**——本地 GPU 调试、生产 CPU 部署不会产生数据不一致。

**M1 — 主改动（一个分支，一次交付）**，内部顺序：

| 步骤 | 内容 |
|---|---|
| ① Schema 迁移 | DROP 三列 + 两个 phash HNSW 索引 + 死表 `image_duplicates`；`image_embeddings` 的 `kind` 改 `varchar(8)` + 补 `(kind, image_id)` 唯一索引 |
| ② 下线去重 | 按 §5 清单删除 `phash` / `is_duplicate` / `dup_of` 的全部代码、模板、统计、测试、文档 |
| ③ 服务化 | Python 服务正式化（配置、批处理、错误处理、`/health`） |
| ④ Go 集成 | `image_embeddings` 仓储读写 + `concurrentFetch` 挂钩 + 降级熔断 + 配置项 |
| ⑤ 后台展示 | 图集页「疑似同款」标签与对比入口 |

每步结束时 `go build ./...` 与现有测试须通过；步骤②完成后系统进入「无自动去重」状态（前台不再折叠），需在交付说明中显式提示这一行为变化。

**M2 — 阈值校准**
dry-run 诊断，定 `vision.similar_threshold`。

## 15. 后续（不在本次范围）

### 15.1 zero-shot 分类：已存向量可直接复用

FashionSigLIP 是图文对齐模型（CLIP 架构），文本与图像编码到同一向量空间，**点积即类别分数**。`D:\project\fashion-siglip\test_similarity_debug.py` 已用 8 组分类验证过该能力：Gender / Scene、Clothing、Color、Material、Pattern、Brand、Style、Shoes / Accessories。

关键性质：**文本向量是固定的，可在服务启动时算一次并缓存**；分类因此退化为「已存图像向量 · 预计算文本向量」的纯点积运算。于是：

- ✅ **性别 / 品类 / 颜色 / 品牌 / 风格 / 材质 / 图案 / 鞋包等 zero-shot 分类，可直接复用已存向量**，读时计算，无需重新编码任何图片、无需再调 GPU。
- ❌ **若要超越 zero-shot 的准确率**（微调专用分类器或更换模型），则**必须重新编码全部图片**——不同模型的向量空间不通用，旧向量作废。

这条性质使「入库时存向量」成为**一次投入、两处收益**的选择：既买下同款检索，也买下可无限扩展的 zero-shot 分类能力。

注意：zero-shot 判定的是**造型风格**而非人物生理性别（模型主要依据服装）。中性 / oversize 穿搭、多人合影、背影、无人物图易误判，建议输出**分数而非硬标签**，允许人工覆盖。

### 15.2 其他

- 历史图片向量回填（本次确认不做）。
- 阈值自动调优。