【免费下载链接】undress-service
Dress AI Sponsor
undress-service是一个自托管的AI 穿搭生成服务（Dress AI），用FastAPI + SQLAlchemy构建：上传衣物照片即可自动打标签、按场合/天气推荐穿搭、并用生成式 AI 可视化整套搭配。本文带你巡礼它清晰的分层项目结构，并讲明"插件系统"在代码中落地的真实位置，帮你快速上手二次开发。
一、项目定位：一个能干活的 AI 衣橱
在动手改代码前，先弄清它"负责什么"，才知道该往哪里加功能。undress-service把一件衣服的生命周期拆成了四步：
- 📸衣橱数字化：上传衣物照片，AI 自动识别品类、主色、面料、季节
- 🧠智能推荐：基于场合、天气、风格偏好组合出穿搭方案
- 🎨AI 可视化：把推荐方案渲染成"真人穿着效果图"
- 🌤️天气感知：结合实时天气建议合适的层次与面料
💡 二次开发前记住一句话：所有 HTTP 能力都在
routers/，所有"聪明逻辑"都在services/，所有"存什么"都在database.py。找准这三层，改哪都不慌。
二、目录结构总览：一眼看懂骨架
整个仓库由两大块组成：app/（Web 服务主体）和coomertool/（内嵌的独立命令行工具包）。
undress-service/ ├── app/ # FastAPI 服务主体（分层架构） │ ├── main.py # 应用入口：实例化 FastAPI、注册路由、挂载静态文件 │ ├── config.py # Pydantic Settings 全局配置 │ ├── database.py # SQLAlchemy 引擎、ORM 模型、会话管理 │ ├── models.py # Pydantic 请求/响应模型 + 枚举 │ ├── routers/ # 路由层（HTTP 接口） │ │ ├── wardrobe.py # 衣橱增删查、图片上传 │ │ ├── outfits.py # 穿搭推荐、可视化、收藏 │ │ ├── generate.py # 直接的图像生成接口 │ │ └── health.py # 健康检查 │ └── services/ # 服务层（业务/推荐/生图逻辑） │ └── ai_tagging.py # AI 自动打标签（CLIP + 启发式） ├── coomertool/ # 独立的 CLI 下载工具（可复用的扩展范式） ├── requirements.txt # 依赖清单 ├── Dockerfile # 生产镜像 └── docker-compose.yml # 一键编排部署这种"入口 → 路由 → 服务 → 数据"的单向依赖，是它易于扩展的根本原因：想加一个新能力，通常只需新增一个 router 文件，再在main.py里注册一行即可。
三、入口层：FastAPI 是怎么"组装"起来的
打开 app/main.py，你会发现整个服务就是一个"装配车间"。核心动作分四步：
- 实例化应用：app/main.py#L28-L35 创建
FastAPI，并指定/docs、/redoc两个文档地址； - 生命周期钩子：用
lifespan在启动时初始化数据库、创建上传与模型目录； - 中间件与静态资源：注册 CORS 中间件，并挂载
/static、/uploads两个静态目录； - 路由注册：app/main.py#L51-L54 把
health、wardrobe、outfits、generate四个 router 统一挂到/api/v1前缀下。
🔑二次开发关键点：想加一组新接口？写好
app/routers/xxx.py导出一个router对象，然后在上面这 4 行里补一条app.include_router(...)，就完成了路由接入——这是全项目成本最低的扩展方式。
四、配置层：一个文件管住所有可调项
app/config.py 基于pydantic_settings定义了一个Settings类，把服务的所有"旋钮"集中收口：
| 配置组 | 代表字段 | 作用 |
|---|---|---|
| 服务器 | host/port/debug | 监听地址与端口 |
| 数据库 | database_url | 默认sqlite:///data/wardrobe.db |
| AI 模型 | clip_model/sdxl_model_path | CLIP 与生图模型路径 |
| 生图参数 | num_inference_steps/guidance_scale | 生成质量与步数 |
| 可选集成 | enable_ollama/enable_weather | 本地 LLM 与天气开关 |
| 存储安全 | max_upload_size/cors_origins | 上传限制与跨域 |
所有字段都能通过.env覆盖（见 app/config.py#L57-L60）。做二次开发时，凡是"可能会变的值"，都应新增到这里，而不是写死在业务代码里——这是该项目最值得继承的工程习惯。
五、数据层：SQLAlchemy 的 ORM 建模方式
app/database.py 同时承担了"引擎初始化"和"表结构定义"两件事：
- 引擎与会话：app/database.py#L8-L14 用
create_engine建立连接（对 SQLite 自动附加check_same_thread=False），并用sessionmaker创建会话工厂； - 两张核心表：
WardrobeItemDB（衣物）与OutfitDB（穿搭方案），两者通过中间表outfit_items构成多对多关系； - 依赖注入：app/database.py#L71-L76 的
get_db()是 FastAPI 的依赖函数，每个请求拿一个会话、用完自动关闭； - 建表：
init_db()调用Base.metadata.create_all(...)在启动时自动建表。
💡设计取舍：颜色、标签这类"列表型"数据在数据库里用
Text存 JSON 字符串，在返回前再json.loads反序列化。优点是表结构简单、迁移成本低；缺点是难以按标签做 SQL 级过滤。若你要做"按颜色筛选衣橱"这类查询，建议引入独立的关联表（item_tags已预留了该范式）。
而 API 的入参/出参约束则放在 app/models.py，用 Pydantic 的Enum（如ClothingCategory、Season、Occasion）保证接口的取值合法，做到了"数据库模型"与"接口模型"分离。
六、路由与服务层：一次"上传"请求的完整旅程
以 app/routers/wardrobe.py 的POST /wardrobe/upload为例，一个请求穿过三层的协作非常典型：
- 路由层（app/routers/wardrobe.py#L43-L73）：接收文件，校验格式与大小，落盘并生成缩略图；
- 服务层：调用 app/services/ai_tagging.py 的
AITaggingService.analyze_image()，返回品类、主色、季节、风格等结构化标签； - 数据层：把标签写入
WardrobeItemDB并提交。
AITaggingService的设计很有代表性：app/services/ai_tagging.py#L109-L140 会优先用 CLIP 模型判断品类，一旦模型不可用就优雅降级到基于文件名的启发式规则。这种"AI 优先、规则兜底"的写法，让你的服务在没有 GPU 的环境也能跑起来。
七、"插件系统"到底在哪？——扩展推荐引擎的真实入口
README 把Plugin System（插件系统）列为高级特性，宣称"可用自定义推荐引擎扩展"。理解它的关键，是看清项目的扩展边界设计：
- 推荐引擎是可替换的：app/routers/outfits.py 在模块顶部实例化
OutfitEngine与ImageGenerationService。也就是说，"如何推荐"和"如何生图"都被抽成了独立服务对象——你要做的"插件"，本质就是替换/继承这两个服务，实现同样的输入输出约定，再在 router 里换一个注入对象即可。 - 内嵌的
coomertool就是最好的"插件范式"：它作为 coomertool/ 独立包存在，自带 api.py、cli.py、downloader.py，并通过 setup.py 注册为coomertool命令行入口。它示范了如何在一个大仓库里内嵌一个职责单一、可独立运行的子包。
🧩二次开发建议：
- 想换推荐算法 → 新建
app/services/my_engine.py，对齐OutfitEngine.generate_outfits()的入参出参；- 想加生图后端 → 替换
ImageGenerationService.generate()的实现；- 想加全新能力 → 新增
app/routers/xxx.py+ 在main.py注册路由。 这三条路覆盖了 90% 的扩展需求，且互不干扰。
八、部署与运行：从克隆到启动
项目提供了完整的容器化方案，本地与生产都能一键拉起：
# 克隆仓库 git clone https://gitcode.com/gh_mirrors/co/undress-service cd undress-service # 本地开发 python -m venv venv && source venv/bin/activate pip install -r requirements.txt uvicorn app.main:app --host 0.0.0.0 --port 8080 --reload依赖清单见 requirements.txt：FastAPI/uvicorn 负责 Web，SQLAlchemy/Alembic 负责数据，torch/transformers/diffusers 负责 AI，Pillow/OpenCV 负责图像处理。
部署方面，Dockerfile 基于python:3.11-slim，内置了非 root 用户与HEALTHCHECK（定期调用/api/v1/health）；docker-compose.yml 还准备了docker-compose.gpu.yml（NVIDIA GPU）与docker-compose.ollama.yml（本地 LLM）两套叠加配置，按需-f组合即可。
九、二次开发自查清单
把下面这张表贴在你的工作区，改动时对照着走，基本不会迷路：
| 我想…… | 该去改哪里 |
|---|---|
| 加一个新接口 | app/routers/ 新建文件 + app/main.py 注册 |
| 加一个新的可调参数 | app/config.py 的Settings |
| 加一张新表 / 改字段 | app/database.py 的 ORM 模型 |
| 改接口入参/出参校验 | app/models.py 的 Pydantic 模型 |
| 换推荐 / 生图算法 | app/services/ 下的引擎类 |
| 改 AI 打标签逻辑 | app/services/ai_tagging.py |
| 加一个独立工具子包 | 参考 coomertool/ + setup.py |
写在最后
undress-service最大的价值，不在于它已经实现了多少功能，而在于它把"可扩展性"做成了结构本身：入口统一装配、路由薄而清晰、服务可替换、数据与接口模型分离、还内嵌了一个可独立运行的工具包范本。读懂这套 FastAPI + SQLAlchemy 的分层骨架，你不仅能在这个项目上做二次开发，也能把同一套范式迁移到自己手头的任何 AI Web 服务里。
【免费下载链接】undress-service
Dress AI Sponsor
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
