docs: 添加可用发型清单文档

- HAIRSTYLES_AVAILABLE.md: 179个可用发型说明（男93/女86）含本次新发型(中文名)、历史测试(英文名)、生产发型(数字ID)分类附 LoRA 权重位置、测试方法、训练新发型指引 - hairstyles_available.csv: 全量发型清单(hair_id/gender/预览图/LoRA大小) 数据来源 /api/hairstyles 接口实时返回，要求三件齐全(LoRA+ref材质+config)
2026-07-07 22:04:10 +08:00
parent 12c6321d10
commit aa38085867
2 changed files with 318 additions and 0 deletions
@@ -0,0 +1,138 @@
+# 可用发型清单
+
+> 当前共 **179 个发型**可用于换发型功能（hair_flow 训练完成后为 180 个）。
+> 数据来源：`/api/hairstyles` 接口实时返回，要求发型同时具备「LoRA权重 + ref材质 + config.json」三件齐全。
+> 全量清单见同目录 `hairstyles_available.csv`。
+
+---
+
+## 概览
+
+| 类别 | 数量 | 说明 |
+|------|------|------|
+| **总可用发型** | **179** | 三件齐全，可直接换发型 |
+| ├ 男款 (boy) | 93 | 适合男性脸型 |
+| ├ 女款 (girl) | 86 | 适合女性脸型 |
+| ├ 中文名命名 | 7 | 本次按脸型训练的新发型 |
+| ├ 英文名命名 | 15 | 历史测试发型 |
+| └ 数字ID命名 | 157 | 生产环境发型（雪花算法ID） |
+
+**性别说明**：gender 字段决定发型被分到"男款/女款"，但换发型时**男女发型都能用**（只是预览图用对应性别的标准脸）。
+
+---
+
+## LoRA 权重文件位置
+
+每个发型的 LoRA 权重（约 144MB/个，共约 26GB）：
+
+```
+/home/xsl/change_hair/data/train_material/<hair_id>/model/hairstyle_hd_lora.safetensors
+```
+
+换发型时 photo_service 会从该路径动态加载 LoRA。
+
+---
+
+## 一、本次训练的新发型（中文名，按脸型适配）
+
+这 7 个是本次会话按 `<脸型>-<发型>` 规则训练的，可在 `hair_type_images/` 找到原图：
+
+| hair_id | 脸型 | 发型 | gender | 预览图 |
+|---------|------|------|--------|--------|
+| 圆-心形 | 圆脸 | 心形刘海 | girl | ✓ |
+| 圆-椭圆 | 圆脸 | 椭圆 | girl | ✓ |
+| 圆-波浪 | 圆脸 | 波浪卷 | girl | ✓ |
+| 圆-直线 | 圆脸 | 直发 | girl | ✓ |
+| 圆-花瓣 | 圆脸 | 花瓣剪 | girl | ✓ |
+| 心形-心形 | 心形脸 | 心形刘海 | girl | ✓ |
+| 心形-椭圆 | 心形脸 | 椭圆 | girl | ✓ |
+
+> ⏳ 还有 23 个同类发型（方脸/椭圆/菱形/长脸系列）尚未训练完成，可用 `batch_train_hairstyles.py` 继续训练。
+
+---
+
+## 二、历史测试发型（英文名）
+
+| hair_id | gender | 备注 |
+|---------|--------|------|
+| huaban1 | girl | 画板1 |
+| huaban2 | girl | 画板2 |
+| new_test_001 | boy | 测试 |
+| newf_1214 / 12141 / 12314 / 1235314 | girl | 测试系列 |
+| newf_121445553 | boy | 测试 |
+| newf_204 / 216 | girl | 测试 |
+| test001 | boy | 测试 |
+| test002 | girl | 测试 |
+| test003 / 0036 | boy | 测试 |
+| test888 | boy | 测试 |
+
+---
+
+## 三、生产发型（数字ID，157个）
+
+这部分是生产环境训练的发型，使用雪花算法生成的纯数字 ID（如 `1935356131338985473`）。
+
+**男款 76 个，女款 81 个**（具体清单见 `hairstyles_available.csv`）。
+
+部分 ID 段对应的训练批次（推测）：
+- `1905xxx` / `1906xxx`：早期批次
+- `1907xxx`：第2批
+- `1929xxx`：第3批
+- `1935xxx`：第4批（数量最多）
+- `1938xxx` / `1939xxx` / `1940xxx` / `1941xxx`：补充批次
+- `1953xxx` / `1954xxx`：扩展批次
+- `1980xxx`：最新批次
+
+---
+
+## 四、未完成训练的发型
+
+| 状态 | 数量 | 说明 |
+|------|------|------|
+| 有 LoRA 但缺 ref 材质 | 135 | 训练了 LoRA 但没生成换发型材质，**不能用于换发型** |
+| 有 ref 材质但缺 LoRA | 14 | 材质在但 LoRA 丢失 |
+| 训练目录但两样都没有 | 34 | 训练中断或失败 |
+
+> 如需让这 135 个"有 LoRA 缺材质"的发型可用，可对它们单独跑 `train_hairstyle_full.py` 的 step3/step4（生成 ref 材质），无需重新训练 LoRA。
+
+---
+
+## 五、如何测试这些发型
+
+### 1. 简易测试页
+访问 `http://localhost:8888/test_new`（本次新发型）或 `http://localhost:8888/swap`（全部 179 个发型）。
+
+### 2. 调试页（带可视化）
+- `http://localhost:8888/debug` — 全参数调试台
+- `http://localhost:8888/manual` — 手绘 mask 重绘
+- `http://localhost:8888/hairline` — 发际线 mask 实验
+
+### 3. API 调用
+```bash
+# 列出所有可用发型
+curl http://127.0.0.1:8888/api/hairstyles
+
+# 换发型（hair_id 替换为上面的任意发型）
+curl -X POST http://127.0.0.1:8888/api/swap \
+  -H "Content-Type: application/json" \
+  -d '{"img":"<base64图片>","hair_id":"1935356131338985473"}'
+```
+
+---
+
+## 六、训练新发型
+
+参考 `docs/` 和项目根的 `README.md`，使用：
+```bash
+# 单个发型训练
+python batch_train_hairstyles.py --src <发型图目录> --gender girl --only <hair_id>
+
+# 批量训练
+python batch_train_hairstyles.py --src hair_type_images --gender girl
+```
+训练完成会自动生成 LoRA + ref材质 + 模板材质 + 预览图，发型立即可用。
+
+---
+
+*文档生成时间：2026-07-07*
+*发型数据可随时通过 `/api/hairstyles` 接口获取最新状态。*
@@ -0,0 +1,180 @@
+hair_id,gender,预览图,LoRA大小MB
+1905785164224868354,girl,有,144
+1907641420518580226,boy,有,144
+1907641442341543937,boy,有,144
+1907641528173780994,boy,有,144
+1907650883958923266,boy,有,144
+1907650924350070785,boy,有,144
+1907651105032298498,boy,有,144
+1907651244006367233,boy,有,144
+1907651308460236802,girl,有,144
+1907651348528422914,girl,有,144
+1907651413477220354,girl,有,144
+1907651464794529794,girl,有,144
+1907651525024735234,girl,有,144
+1907651578753769473,girl,有,144
+1907651632629604354,girl,有,144
+1907651680352395265,girl,有,144
+1907651747310264321,girl,有,144
+1907805226322419713,boy,有,144
+1929905737381048322,boy,有,144
+1929905770088230914,boy,有,144
+1929906202869100546,boy,有,144
+1929906230224351234,boy,有,144
+1929906315553271809,boy,有,144
+1929906349401305089,boy,有,144
+1929906429839667202,boy,有,144
+1935354779623858177,boy,有,144
+1935354812175851522,boy,有,144
+1935354869738479617,boy,有,144
+1935354938051108865,boy,有,144
+1935355030892027905,boy,有,144
+1935355149217538050,girl,有,144
+1935355188652384257,girl,有,144
+1935355258143612929,girl,有,144
+1935355292960530433,girl,有,144
+1935355361726144514,girl,有,144
+1935355403207811074,girl,有,144
+1935355449991077889,girl,有,144
+1935355504156319745,girl,有,144
+1935355551300296705,girl,有,144
+1935355607394918402,girl,有,144
+1935355698319040514,girl,有,144
+1935355740559876097,girl,有,144
+1935355778526715905,girl,有,144
+1935355868347736065,girl,有,144
+1935355934743568386,girl,有,144
+1935355969141055490,girl,有,144
+1935356042201636865,girl,有,144
+1935356092684279809,girl,有,144
+1935356131338985473,girl,有,144
+1935356178227109890,girl,有,144
+1938489620162781185,boy,有,144
+1938489674713899010,boy,有,144
+1938489739088076801,boy,有,144
+1938489840707674114,boy,有,144
+1938489915521474561,boy,有,144
+1938489994072399874,boy,有,144
+1938490058547240961,boy,有,144
+1938492790033195009,girl,有,144
+1938492830059438081,girl,有,144
+1938841049238970370,girl,有,144
+1938848709308948482,girl,有,144
+1938848730150445058,girl,有,144
+1938848782956732417,girl,有,144
+1939330299344560130,girl,有,144
+1939339435616608258,girl,有,144
+1939351219396255745,boy,有,144
+1939351238526476289,boy,有,144
+1939351319849836545,boy,有,144
+1939351392453238785,girl,有,144
+1939351512506802177,girl,有,144
+1940007538260287490,boy,有,144
+1941163289636872193,boy,有,144
+1941163324332154882,boy,有,144
+1941163373069967362,boy,有,144
+1941163615962112002,boy,有,144
+1941163645464846338,boy,有,144
+1941163754357366785,boy,有,144
+1941163816533729282,boy,有,144
+1941163884078800898,boy,有,144
+1941163952840220673,boy,有,144
+1941164012827156482,boy,有,144
+1941352458711572482,boy,有,144
+1941352541028982786,boy,有,144
+1941352599665352705,boy,有,144
+1943143930804936705,boy,有,144
+1943144007388733441,boy,有,144
+1945789428732895233,boy,有,144
+1953267161121464322,boy,有,144
+1953267288284372994,boy,有,144
+1953270137953230849,girl,有,144
+1953270523594317826,girl,有,144
+1953270724765720577,boy,有,144
+1953271922151432194,boy,有,144
+1953272913265467394,boy,有,144
+1953288800932503554,boy,有,144
+1954536242109784066,boy,有,144
+1954536297776586754,boy,有,144
+1954536402516746241,boy,有,144
+1954536893304840194,boy,有,144
+1954536956919848962,boy,有,144
+1954537022875279362,boy,有,144
+1954537085882114050,boy,有,144
+1954537191729569793,boy,有,144
+1954537709436706817,girl,有,144
+1954537743532204034,girl,有,144
+1954537926731014146,girl,有,144
+1954537961069780994,girl,有,144
+1954538119216013313,girl,有,144
+1954538156499181569,girl,有,144
+1954538259330932738,girl,有,144
+1954538335306555393,girl,有,144
+1980312945301954561,boy,有,144
+1980313052302843905,girl,有,144
+1980313166576656385,girl,有,144
+1980313210109337601,girl,有,144
+1980313433502162946,boy,有,144
+1980313576506957825,girl,有,144
+1980313740403580930,girl,有,144
+1980313819915001858,girl,有,144
+1980314032369082369,girl,有,144
+1980314146483511297,girl,有,144
+1980314209322573825,girl,有,144
+1980314290419441665,girl,有,144
+1980314381058351106,girl,有,144
+1980314477720281090,girl,有,144
+1980314710101499906,boy,有,144
+1980314764421931009,boy,有,144
+1980314868713299969,boy,有,144
+1980315054516772866,boy,有,144
+1980315179934851074,girl,有,144
+1980315238260842497,girl,有,144
+1980361636742209537,girl,有,144
+1980367742952579074,boy,有,144
+1980367781510815746,boy,有,144
+1980367800787836929,boy,有,144
+1980367852847538177,boy,有,144
+1980367968627105793,boy,有,144
+1980368109866098690,boy,有,144
+1980368205752082434,boy,有,144
+1980368368847593473,boy,有,144
+1980368465631158274,boy,有,144
+1980368588293578754,boy,有,144
+1980368787732733953,boy,有,144
+1980368837162606594,boy,有,144
+1980368937435832321,boy,有,144
+1980413320612847618,girl,有,144
+1980415346071609345,girl,有,144
+1980415897056354306,girl,有,144
+1980422351658196994,boy,有,144
+1980422373388886018,boy,有,144
+1981177324700549122,girl,有,144
+1981177378714796034,boy,有,144
+1981177477423546370,boy,有,144
+1981177594750812162,boy,有,144
+1981177742742634497,boy,有,144
+1981177931859607554,boy,有,144
+3325266,girl,有,144
+huaban1,girl,有,144
+huaban2,girl,有,144
+new_test_001,boy,有,144
+newf_1214,girl,有,144
+newf_12141,girl,有,144
+newf_121445553,boy,有,144
+newf_12314,girl,有,144
+newf_1235314,girl,有,144
+newf_204,girl,有,144
+newf_216,girl,有,144
+test001,boy,有,144
+test002,girl,有,144
+test003,boy,有,144
+test0036,boy,有,144
+test888,boy,有,144
+圆-心形,girl,有,144
+圆-椭圆,girl,有,144
+圆-波浪,girl,有,144
+圆-直线,girl,有,144
+圆-花瓣,girl,有,144
+心形-心形,girl,有,144
+心形-椭圆,girl,有,144