first commit

2026-09-11 01:41:52 +08:00
commit 9f22e6ccae
263 changed files with 28935 additions and 0 deletions
@@ -0,0 +1,176 @@
+---
+name: classify-service-align-clothes-model
+overview: 根据 mysqlmodel.Clothes 的 15 个分类维度字段，全面重构 thirdparty/classification_server/main.py 分类服务：所有维度（含已有）的 prompt 大幅扩充至全面覆盖各种情况，补齐 8 个缺失分类维度，响应字段命名与 model 对齐，并将多次模型前向推理合并为单次批量前向以提升性能。
+todos:
+  - id: expand-existing-prompts
+    content: 扩充已有 6 组 prompt：颜色至 30、子类别至约 60、风格至 25、版型加直筒、材质至 17、图案至 19，全部配详细英文视觉描述
+    status: completed
+  - id: add-new-dimension-prompts
+    content: 新增 7 组维度 prompt（厚度/袖型/衣长/领型/正式度/场合/视觉冲击）、维度适用性映射表与副颜色阈值常量
+    status: completed
+    dependencies:
+      - expand-existing-prompts
+  - id: implement-batch-forward
+    content: 实现 _classify_all 单次批量前向：按组 softmax、子类别按大类过滤、副颜色 top-2 阈值提取
+    status: completed
+    dependencies:
+      - add-new-dimension-prompts
+  - id: rewrite-classify-api
+    content: 重写 /classify 接口：响应字段对齐 Clothes 模型命名、不适用维度置空、occasions top-N 逗号连接、formality 与 visual_impact 返回数字加标签
+    status: completed
+    dependencies:
+      - implement-batch-forward
+  - id: preprocess-verify
+    content: 优化图片预处理（仅透明图合成白底）并运行 Python 语法检查与启动自检验证
+    status: completed
+    dependencies:
+      - rewrite-classify-api
+---
+
+## 产品概述
+
+根据 `mysqlmodel.Clothes` 的 15 个分类维度字段，全面优化 Fashion-CLIP 衣物分类服务（`thirdparty/classification_server/main.py`）：不仅补齐缺失维度，所有已有维度的 prompt 也要大幅扩充细化，覆盖各种衣物边界情况（多色拼色、稀有颜色、特殊袖型领型、加厚冬装、各类场合等），同时将推理从逐组多次前向合并为单次批量前向，响应字段与模型命名完全对齐。
+
+## 核心功能
+
+- **已有 prompt 全面扩充**：颜色扩至 30+（新增玫红/荧光/墨绿/宝蓝/驼色/砖红等），子类别扩至约 60 个（补针织衫/工装裤/喇叭裤/玛丽珍鞋/马丁靴/发带/戒指/胸针/手表等），风格扩至 25 个（补极简/波西米亚/朋克/嘻哈/森系/法式/日系/韩系等），材质扩至 17 个（补天鹅绒/缎面/网纱/羊羔绒/PU皮/磨毛棉），图案扩至 19 个（补千鸟格/菱格纹/人字纹/拼色块/渐变/豹纹/几何/logo等）
+- **补齐 8 个缺失维度**：副颜色（color_sub，颜色 top-2 阈值提取）、厚度（4 档）、袖型（8 档）、衣长类型（5 档）、领型（10 档）、正式程度（1-5）、适用场合（10 档 top-N）、视觉冲击力（1-5）
+- **单次批量前向**：约 210 个文本合并为一次模型前向，按组 softmax，推理耗时从 15 次降为 1 次
+- **品类适用性控制**：鞋/配饰等品类的不适用维度自动置空，避免不合理标签
+- **响应对齐模型**：category_main/category_sub/color_main/color_sub/thickness/version/material/pattern/sleeve_type/clothes_type/neckline_type/formality/occasions/visual_impact，均附 *_confidence，details 保留 Top-5 明细
+
+## 边界说明
+
+- 改动仅限 `thirdparty/classification_server/main.py` 单文件，Go 侧无消费方，字段改名无破坏风险
+- 多色衣物通过 color_sub 副颜色机制表达，颜色组内不放"多色"标签避免抢占主色
+- 所有 prompt 沿用"中文标签键 + 详细英文视觉描述值"模式，英文描述包含剪裁、长度、材质视觉特征
+
+## 技术栈
+
+- 沿用现有：Python 3 + FastAPI + Transformers（patrickjohncyh/fashion-clip）+ PyTorch，不引入新依赖
+
+## 实现方案
+
+### 核心策略
+
+1. **Prompt 维度全覆盖**：已有 6 组 prompt 扩充 + 新增 7 组维度 prompt，全部收敛为统一 dict 结构
+2. **单次批量前向**：新增 `_classify_all`，全部组（约 210 个文本）拼一个 batch 一次推理，输出 logits 按组 start/end 边界切分后分别 softmax
+3. **子类别等价合并**：所有大类子类别合并进同一批前向，大类确定后在其组内取 top1——同组内相对分数不变，argmax 与当前两阶段方案数学等价
+4. **适用性映射**：`DIMENSION_APPLICABILITY` 表声明各维度适用的大类，不适用直接返回空字符串
+5. **副颜色逻辑**：颜色组 top-2，第二置信度达到阈值（top1 的 40% 与绝对值 0.15 取较低者）才输出 color_sub
+
+```mermaid
+flowchart LR
+    A[图片上传] --> B[预处理: 仅透明图合成白底]
+    B --> C[一次前向: 全部维度约210文本拼batch]
+    C --> D[按组softmax归一化]
+    D --> E[大类 top1]
+    E --> F[子类别: 大类组内 top1]
+    E --> G[颜色 top1/top2 主色/副色]
+    E --> H[其余维度 top1 或 top-N]
+    H --> I[适用性映射: 不适用置空]
+    F --> J[响应字段对齐 model]
+    G --> J
+    I --> J
+```
+
+### Prompt 扩充清单（各组完整标签与描述规范）
+
+**CATEGORY_PROMPTS（6 类，保持）**：上装/下装/连衣裙/外套/鞋/配饰。描述要点：明确穿着部位与廓形边界（如连衣裙强调"从肩到腿一件式"，配饰强调"非服装的小件"）。
+
+**SUBCATEGORY_GROUPS（约 60 个）**
+
+- 上装（10）：T恤/衬衫/卫衣/毛衣/针织衫/背心/Polo衫/开衫/吊带衫/打底衫
+- 下装（10）：牛仔裤/休闲裤/运动裤/短裤/半身裙/阔腿裤/西装裤/鲨鱼裤/工装裤/喇叭裤
+- 连衣裙（7）：连衣短裙/连衣长裙/吊带裙/衬衫连衣裙/针织连衣裙/雪纺连衣裙/西装连衣裙
+- 外套（9）：夹克/西装外套/风衣/羽绒服/大衣/马甲/牛仔外套/皮衣/棉服
+- 鞋（11）：运动鞋/皮鞋/凉鞋/靴子/帆布鞋/高跟鞋/乐福鞋/外穿拖鞋/玛丽珍鞋/洞洞鞋/马丁靴
+- 配饰（13）：帽子/围巾/腰带/墨镜/项链/手链/包包/耳饰/丝巾/发带/戒指/胸针/手表
+
+描述规范：每条必须包含款式特征词（领型/口袋/闭合方式/鞋面结构等）+ 材质质感词 + 穿着场景词，如针织衫需区分"ribbed knit texture, pullover without buttons"与卫衣的"fleece fabric, hood, kangaroo pocket"。
+
+**COLOR_PROMPTS（30 个）**
+原有 20：黑/白/红/绿/黄/粉/紫/灰/棕/橙/卡其/米/杏/焦糖/藏青/天蓝/军绿/酒红/金/银
+新增 10：玫红/荧光色/墨绿/宝蓝/浅蓝/粉紫/驼色/砖红/藏蓝/浅灰
+
+描述规范：新增颜色需给出色相 + 明度 + 饱和度描述（如宝蓝"bright vivid royal blue, saturated deep bright blue"，浅蓝"light pale blue, soft pastel sky tone"）；金色/银色强调 metallic 金属光泽；荧光色强调 neon 高饱和度。
+
+**STYLE_PROMPTS（25 个）**
+原有 16：休闲/通勤/运动/街头/优雅/甜美/复古/简约/商务正装/轻熟/工装/学院/甜酷/辣妹/度假/新中式
+新增 9：极简风/波西米亚风/朋克风/嘻哈风/森系风/法式风/美式复古风/日系风/韩系风
+
+描述规范：每条包含整体气质 + 典型元素（如波西米亚"flowy fabric, fringe, ethnic embroidery, relaxed silhouette"；朋克"black leather, studs, ripped details, rebellious look"）。
+
+**FIT_PROMPTS（6 个）**：宽松/修身/阔腿/紧身/常规合身/直筒。描述强调廓形与身体关系（hugs body / straight parallel legs / oversized）。
+
+**MATERIAL_PROMPTS（17 个）**
+原有 11：牛仔布/针织/皮质/纯棉/羊毛/丝绸/雪纺/麻料/蕾丝/尼龙/灯芯绒
+新增 6：天鹅绒/缎面/网纱/羊羔绒/PU皮/磨毛棉
+
+描述规范：强调表面质感特征（如天鹅绒"soft plush velvet surface, rich deep sheen"；缎面"smooth glossy satin sheen, silky shine"；网纱"sheer mesh tulle"；羊羔绒"fluffy fleece"；磨毛棉"brushed soft cotton, slightly fuzzy surface"），区分真皮与 PU 皮的光泽差异。
+
+**PATTERN_PROMPTS（19 个）**
+原有 10：纯色/条纹/格纹/印花/刺绣/波点/迷彩/扎染/碎花/字母
+新增 9：千鸟格/菱格纹/人字纹/拼色块/渐变/豹纹/蕾丝花纹/几何图案/logo图案
+
+描述规范：强调图案构成方式（如千鸟格"houndstooth check, small broken zigzag checks"；菱格纹"argyle diamond pattern"；人字纹"herringbone zigzag weave"；拼色块"color blocking, contrasting solid color panels"）。
+
+**新增 THICKNESS_PROMPTS（4 档）**：薄（sheer lightweight summer）/适中（regular medium weight）/厚（thick warm winter）/加厚（heavily padded down, quilted thick insulation）。适用：上装/下装/连衣裙/外套/鞋。
+
+**新增 SLEEVE_TYPE_PROMPTS（8 档）**：无袖/吊带/短袖/中袖/长袖/喇叭袖/泡泡袖/落肩袖。描述强调袖长比例与袖型结构（喇叭袖"flared bell sleeve widening at cuff"，泡泡袖"puffed voluminous sleeve with gathered shoulder"，落肩袖"dropped shoulder seam, relaxed slouchy sleeve"）。适用：上装/连衣裙/外套。
+
+**新增 CLOTHES_TYPE_PROMPTS（5 档）**：短款/常规/中长/长款/超长款。描述以身体参照点界定衣长（短款"ends above waist, cropped"；中长"mid-thigh to knee"；超长"ankle-length or floor-length, maxi"）。适用：上装/下装/连衣裙/外套。
+
+**新增 NECKLINE_PROMPTS（10 档）**：圆领/V领/方领/高领/翻领/立领/一字领/挂脖/连帽/娃娃领。描述强调领口形状与领部结构（方领"square shaped neckline with straight edges"，立领"standing band collar, mandarin collar"，挂脖"halter neck with straps behind neck"，娃娃领"peter pan collar, flat rounded collar"）。适用：上装/连衣裙/外套。
+
+**新增 FORMALITY_PROMPTS（5 档）**：标签（非常休闲/休闲/轻正式/商务正式/非常正式）对应等级 1-5，返回 `formality="1"~"5"` 字符串 + `formality_label` 中文标签。描述用场景锚定（如 5"evening gown, tuxedo, ceremonial formal wear"；1"sporty gym wear, beach casual"）。
+
+**新增 OCCASION_PROMPTS（10 档）**：日常通勤/运动健身/约会聚会/正式商务/居家休闲/度假旅游/户外活动/派对夜店/校园上课/婚礼宴会。取置信度达标的 top-N（如置信度不低于 top1 的 60%）用逗号连接返回 occasions 字符串。
+
+**新增 VISUAL_IMPACT_PROMPTS（5 档）**：标签（低调/平淡/适中/亮眼/高调）对应等级 1-5，返回 `visual_impact="1"~"5"` + `visual_impact_label`。描述锚定视觉特征（如 5"bold neon, glitter, dramatic design"；1"plain neutral minimal"）。
+
+### 响应结构（对齐 model）
+
+```
+{
+  "category_main": "上装",
+  "category_sub": "针织衫",
+  "style": "韩系风",
+  "color_main": "宝蓝",
+  "color_sub": "白色",
+  "thickness": "适中",
+  "version": "修身",
+  "material": "针织",
+  "pattern": "条纹",
+  "sleeve_type": "长袖",
+  "clothes_type": "常规",
+  "neckline_type": "圆领",
+  "formality": "3",
+  "formality_label": "轻正式",
+  "occasions": "日常通勤,约会聚会",
+  "visual_impact": "3",
+  "visual_impact_label": "适中",
+  "details": { "...各组 Top-5 明细，按新字段命名，含置信度..." }
+}
+```
+
+### 实现要点
+
+- **性能**：前向 7 次 → 1 次（约 210 文本，CLIP 单 batch 可承受，CPU 场景收益最大）；避免每组重复 tokenize 开销
+- **等价性**：按组 softmax 与逐组调用结果一致；子类别"组内 top1"与两阶段 argmax 完全一致
+- **健壮性**：`_classify_all` 用 start/end 边界切片防顺序错乱；大类不在适用性表中时安全回退（维度置空、子类别为空）
+- **可维护性**：新增维度只需加 dict 项 + 注册分组，无需改前向逻辑；/healthz 保留；docstring 同步更新
+- **预处理**：仅当图片含 alpha 通道（PNG）才合成白底，JPEG 直接转 RGB
+
+## 目录结构
+
+```
+thirdparty/
+└── classification_server/
+    └── main.py   # [MODIFY] 唯一改动文件
+                   # 1. 扩充 6 组已有 prompt（颜色30/子类别60/风格25/版型6/材质17/图案19）
+                   # 2. 新增 7 组维度 prompt + DIMENSION_APPLICABILITY + 副色阈值常量
+                   # 3. 新增 _classify_all 单次批量前向（替代逐组 _classify_group 循环）
+                   # 4. 重写 /classify 接口：批量前向、副色提取、适用性置空、响应对齐 model
+                   # 5. 优化图片预处理：检测 alpha 后才合成白底
+```