first commit

2026-09-11 01:41:52 +08:00
commit 9f22e6ccae
263 changed files with 28935 additions and 0 deletions
@@ -0,0 +1,83 @@
+---
+name: 修复分类模型手表识别错误
+overview: 优化 Fashion-CLIP 分类服务的零样本提示词（大类「配饰」覆盖手表、强化「手表」子类别特征、纠正与「鞋/手链」的混淆），重启分类服务并用手表测试图验证识别结果。
+todos:
+  - id: tune-prompts
+    content: 优化 main.py 大类「配饰/鞋」与配饰组「手表/手链」提示词
+    status: completed
+  - id: restart-service
+    content: 重启分类服务进程并轮询健康检查直至恢复
+    status: completed
+    dependencies:
+      - tune-prompts
+  - id: verify-regression
+    content: 用测试图验证手表识别并回归验证正常衣物分类不受影响
+    status: completed
+    dependencies:
+      - restart-service
+  - id: iterate-archive
+    content: 按验证结果迭代微调提示词并归档测试图到 resources
+    status: completed
+    dependencies:
+      - verify-regression
+---
+
+## 产品概述
+
+修复衣柜小程序的衣物分类模型无法识别「手表」的问题。实测复现：上传手表图片后，分类服务将手表误识别为「鞋」大类（置信度 0.9471），正确大类「配饰」仅 0.0013，导致子类别轮不到「手表」。
+
+## 核心功能
+
+- 手表图片分类结果正确：大类输出「配饰」、子类别输出「手表」
+- 正常衣物图片分类结果不受影响（回归基线：上装/衬衫）
+- 分类服务重启后健康检查恢复，上传→抠图→分类链路保持正常
+
+## 技术栈
+
+- 分类服务：Python FastAPI + transformers + patrickjohncyh/fashion-clip（零样本 CLIP 分类，端口 8000）
+- 修改范围：仅 `thirdparty/classification_server/main.py` 的提示词字典，不改推理逻辑、响应结构、后端 Go 代码
+
+## 实现方案
+
+采用零样本 CLIP 提示词工程修复，三处针对性调整：
+
+1. **大类「配饰」提示词**（`CATEGORY_PROMPTS`，第 47 行）：加入 watch/wristwatch 描述，强化「小而独立的腕部配饰、非衣物主体」语义，补齐手表完全未覆盖的问题。
+2. **大类「鞋」提示词**（第 46 行）：补充强视觉特征（成双出现 pair、鞋底 sole、包裹脚的立体鞋型），压低手表白底商品图与「鞋」的相似度；微调幅度保守，避免影响正常鞋类识别。
+3. **「配饰」组内子类别提示词**（`SUBCATEGORY_GROUPS["配饰"]`，第 115、122 行）：
+
+- 「手表」强化表盘特征：round watch face、circular dial with numerals and hands、crown、metal or leather strap；
+- 「手链」显式排除表盘：no watch face、no dial、purely decorative，消除两者互选错误。
+
+关键决策：
+
+- 只改提示词字符串，每组 label 数量不变，单次前向 batch 规模不变，推理性能无变化；
+- 响应 JSON 字段结构不变，`pkg/classification/classification.go` 与 `internal/service/clothes.go` 无需改动，完全向后兼容；
+- 大类修复与子类别修复同步完成，一次生效，避免「大类对了但子类错」的二次返工。
+
+## 实施细节
+
+### 服务重启流程（已实测进程信息）
+
+- 当前分类服务 PID 3156827，cwd=/root/zt-closet-backend，启动命令 `thirdparty/matting_server/.venv/bin/python thirdparty/classification_server/main.py`（复用 matting_server 的 .venv，无 systemd 托管；模型在模块 import 时加载，改代码必须重启）。
+- 重启方式：kill 3156827 后，在项目根目录按原解释器与原命令用 nohup 拉起，日志重定向到 `storage/logs/classification.log`；轮询 `curl http://127.0.0.1:8000/healthz` 直至返回 ok（模型重载约 1 分钟）。
+- 严禁误动抠图服务 PID 3144600（cwd=thirdparty/matting_server）。
+- 重启窗口内后端有 retryCall（MaxRetry=3）兜底，短暂不可用影响可控。
+
+### 验证与回归
+
+- 手表测试图 `/root/zt-closet-backend/0d98288268054879d481a7bb1d2dd7af.jpg`：期望 category_main=配饰、category_sub=手表；
+- 回归图 `resources/微信图片_20260907235100_780_53.jpg`：期望维持 category_main=上装、category_sub=衬衫（当前基线 0.5028/0.5024）；
+- 若验证不达标，迭代微调提示词措辞（最多 2~3 轮），每轮重启后重测。
+
+### 目录结构
+
+```
+/root/zt-closet-backend/
+├── thirdparty/classification_server/
+│   └── main.py                          # [MODIFY] 修改 CATEGORY_PROMPTS 的「配饰」「鞋」提示词，及 SUBCATEGORY_GROUPS["配饰"] 的「手表」「手链」提示词
+├── storage/logs/classification.log      # [NEW] 重启后的分类服务日志（nohup 重定向）
+├── 0d98288268054879d481a7bb1d2dd7af.jpg # [MOVE] 验证通过后移入 resources/ 留作回归样本
+└── resources/
+    ├── 微信图片_20260907235100_780_53.jpg # [不变] 回归验证用正常衣物图
+    └── 0d98288268054879d481a7bb1d2dd7af.jpg # [NEW] 归档的手表测试图
+```