undress-service代码分析：CLIP+K-Means如何自动解析衣物照片（类别、主色与风格）

undress-service 是一个可自托管的 AI 衣橱平台，上传衣物照片后，它会自动完成类别识别、主色提取、季节与风格打标。本文将深入其核心模块 ai_tagging.py，分析CLIP与K-Means两种经典算法是如何被组合起来，把一张普通衣物照片解析成结构化元数据的。

📁 项目速览：AI 打标服务在哪里

整个解析流程的入口非常简单：

1. 用户上传照片 → 接口 wardrobe.py 保存文件并生成缩略图
2. 立即调用AITaggingService.analyze_image()进行 AI 分析
3. 把返回的类别、颜色、季节、风格等字段写入 SQLite 数据库

照片上传 → 预处理 → CLIP 分类 / K-Means 取色 → 季节 & 风格启发式 → 入库

相关配置集中在 config.py，例如 CLIP 模型默认使用openai/clip-vit-large-patch14，可通过.env覆盖。依赖声明在 requirements.txt 中（transformers、scikit-learn、numpy、pillow）。

🎨 主色提取：K-Means 把 1 万个像素压成 3 种颜色

主色提取是纯传统机器学习，与 CLIP 无关。核心逻辑在_extract_colors()方法（ai_tagging.py）：

为什么选 K-Means？颜色本质上是 RGB 三维空间中的点，"找出衣服上最突出的几团颜色"恰好是聚类问题的标准形态。n_init=10表示随机初始化 10 次取最优，避免陷入局部极值；random_state=42则保证结果可复现。

第⑤步的_hex_to_name()（ai_tagging.py）内置了 20 个常用色名映射表，用pairwise_distances计算聚类中心与表内颜色的欧氏距离，取最近者命名——所以 "海军蓝" 会被归入 "Navy"，而不是模糊的 "Blue"。

🧠 类别识别：CLIP 零样本分类的巧妙用法

类别识别在_detect_category()（ai_tagging.py）中，是CLIP 零样本分类的教科书式应用：

1. 构造文本提示：准备 10 条英文描述，如"a photo of a shirt or top"、"a photo of a dress"、"a photo of shoes"……
2. 联合编码：CLIPProcessor同时处理图片与文本，输出图像 embedding 和文本 embedding
3. 相似度比较：模型计算图像向量与 10 条文本向量的余弦相似度，softmax后取概率最高项
4. 映射输出：返回top/bottom/dress/outerwear/shoes/accessory等标签

💡零样本的关键：不需要任何标注数据集训练。只需改变文本提示列表，就能"重新定义"分类器——把"a photo of shoes"换成"a photo of a hat"，分类器立刻就会识别帽子。

优雅降级设计：CLIP 模型加载失败时（首次运行未下载模型），代码自动退化为文件名启发式——检查shirt、jean、dress、shoe等关键词，保证服务始终可用。

🍂 季节与风格：从颜色出发的启发式规则

这两项不涉及深度学习，而是基于前两步结果的轻量规则：

季节推断（_detect_season，ai_tagging.py）：

• 暖色系（Red/Orange/Brown/Beige…）计分 → 偏暖则返回autumn,spring
• 冷色系（Blue/Navy/Green/Purple…）计分 → 偏冷则返回winter,summer
• 打平 →all_season

风格标签（_detect_style，ai_tagging.py）：

此外还保留了fabric（面料）与pattern（花纹）两个占位方法，源码注释表明未来将替换为专门的纹理/花纹分类模型，这是明确的扩展点。

🔗 一次调用的完整数据流

POST /api/v1/wardrobe/upload │ ▼ save_upload_file() → 原图 + 400px 缩略图 │ ▼ analyze_image() ├─ _extract_colors() KMeans 聚类 → 3 个主色 + 占比 ├─ _detect_category() CLIP 零样本 → dress / top / shoes … ├─ _detect_season() 暖冷色计分 → autumn,spring └─ _detect_style() 亮度/颜色规则 → [casual, classic] │ ▼ WardrobeItemDB 入库（SQLite）

最终这些标签被 outfit 推荐引擎（outfits.py）消费，实现"按场合 + 天气 + 颜色理论"的智能搭配——自动打标是整个推荐链条的地基。

✅ 总结：这套方案值得借鉴的 3 点

1. 算法选型精准：颜色提取是空间聚类问题 → K-Means；图文匹配是语义对齐问题 → CLIP。没有过度使用深度学习，K-Means 在 1 万像素上毫秒级完成
2. 零样本 + 启发式双保险：CLIP 提示词即配置，模型缺失时文件名兜底，服务永不因模型问题中断
3. 职责拆分清晰：AITaggingService只负责"照片 → 元数据"，入库、推荐、可视化各归各的 Router/Service，新人也能快速定位问题

想动手验证？本地启动后打开 Swagger 文档（http://localhost:8080/docs），对POST /api/v1/wardrobe/upload传一张衣服照片，响应 JSON 里就能看到 CLIP 和 K-Means 的解析结果。