xslandCursor
9fb5b486c0
- worker /api/v1/face/features 不再返回假成功数据，直接告知仅网关实现， 避免本机误打 :8187 被 Mock 结果误导。 - 网关 ark_api_key 加载优先级改为 gateway/config.json 优先（原先误读 worker_config.json 里的失效 key）。 - 接口4 face_shape 不再采信豆包结果，改用本机 face/face_shape_classifier.py （MediaPipe 7 类）计算覆盖；其余 5 项特征仍走豆包。 - 修复 face_shape_classifier 共享 FaceMesh 实例的线程安全问题（加锁）， 避免网关侧接口4 并发请求时崩溃/结果错乱。 - 新增 /api/v1/debug/face-shape 调试接口 + static/test_face_shape.html 单图调试页（worker 侧）。 - 更新文档：网关机现在也需要 mediapipe/opencv-python/numpy<2。 ⚠️ 部署前提醒：网关机需先安装 mediapipe==0.10.14 / opencv-python==4.10.0.84 / numpy==1.26.4，否则接口4 会返回 1007「分析服务异常」。 Co-authored-by: Cursor <cursoragent@cursor.com>
93 lines
4.4 KiB
Markdown
93 lines
4.4 KiB
Markdown
# 离线资产清单（内网部署用）
|
||
|
||
## 已入库文件（git clone 后自动到位）
|
||
|
||
以下文件体积适中，已直接提交进 git，clone 仓库即可：
|
||
|
||
| 文件 | 路径 | 大小 | 用途 |
|
||
|------|------|------|------|
|
||
| BiSeNet 主权重 | `face_analysis/weights/79999_iter.pth` | ~53MB | 人脸解析分割（接口1方案B，取真实发际线/头顶） |
|
||
| resnet18 骨干 | `face_analysis/weights/resnet18-5c106cde.pth` | ~45MB | BiSeNet 骨干网络 |
|
||
| 中文字体 | `face_analysis/fonts/NotoSansCJKsc-Regular.otf` | ~16MB | 标注图中文渲染 |
|
||
| MediaPipe 模型 | `hairline/models/face_landmarker.task` | ~3.7MB | 468点人脸关键点检测（接口2） |
|
||
|
||
## 需手动下载文件（体积过大，不入 git）
|
||
|
||
### SegFormer 人脸分割模型（接口2必需）
|
||
|
||
| 文件 | 路径 | 大小 |
|
||
|------|------|------|
|
||
| model.safetensors | `hairline/models/face-parsing/model.safetensors` | 338,580,732 B (~323MB) |
|
||
|
||
下载命令（国内用 hf-mirror 镜像，快很多）：
|
||
```bash
|
||
# 国内镜像（推荐）
|
||
curl -L -o hairline/models/face-parsing/model.safetensors \
|
||
"https://hf-mirror.com/jonathandinu/face-parsing/resolve/main/model.safetensors"
|
||
# 官方源
|
||
# curl -L -o hairline/models/face-parsing/model.safetensors \
|
||
# "https://huggingface.co/jonathandinu/face-parsing/resolve/main/model.safetensors"
|
||
```
|
||
|
||
sha256 校验：
|
||
```
|
||
c2bec795a8c243db71bd95be538fd62559003566466c71237e45c99b920f4b62 hairline/models/face-parsing/model.safetensors
|
||
```
|
||
|
||
```bash
|
||
sha256sum hairline/models/face-parsing/model.safetensors
|
||
```
|
||
|
||
## sha256 校验（已入库文件）
|
||
|
||
```
|
||
468e13ca13a9b43cc0881a9f99083a430e9c0a38abd935431d1c28ee94b26567 face_analysis/weights/79999_iter.pth
|
||
5c106cde386e87d4033832f2996f5493238eda96ccf559d1d62760c4de0613f8 face_analysis/weights/resnet18-5c106cde.pth
|
||
2c76254f6fc379fddfce0a7e84fb5385bb135d3e399294f6eeb6680d0365b74b face_analysis/fonts/NotoSansCJKsc-Regular.otf
|
||
```
|
||
|
||
```bash
|
||
sha256sum -c <<'EOF'
|
||
468e13ca13a9b43cc0881a9f99083a430e9c0a38abd935431d1c28ee94b26567 face_analysis/weights/79999_iter.pth
|
||
5c106cde386e87d4033832f2996f5493238eda96ccf559d1d62760c4de0613f8 face_analysis/weights/resnet18-5c106cde.pth
|
||
2c76254f6fc379fddfce0a7e84fb5385bb135d3e399294f6eeb6680d0365b74b face_analysis/fonts/NotoSansCJKsc-Regular.otf
|
||
EOF
|
||
```
|
||
|
||
> resnet18 文件名内嵌的 `5c106cde` 即其官方 sha256 前 8 位（torchvision 命名惯例），与上表一致 = 官方权重无误。
|
||
|
||
## ⚠️ resnet18 骨干的离线处理（重要）
|
||
|
||
BiSeNet 初始化时会调用 `torch.utils.model_zoo` / `torchvision` **联网下载** resnet18 骨干，内网会失败报错。两种解法任选其一：
|
||
|
||
1. **放进 torch 缓存目录**（推荐，零改代码）：
|
||
```bash
|
||
mkdir -p ~/.cache/torch/hub/checkpoints/
|
||
cp face_analysis/weights/resnet18-5c106cde.pth ~/.cache/torch/hub/checkpoints/
|
||
```
|
||
（Windows 路径：`%USERPROFILE%\.cache\torch\hub\checkpoints\`）
|
||
2. **改 BiSeNet 代码**，把骨干加载改成从 `face_analysis/weights/resnet18-5c106cde.pth` 本地读取（`load_state_dict(torch.load(本地路径))`，并去掉联网下载分支）。
|
||
|
||
## 下载来源（联网环境重建用）
|
||
|
||
```
|
||
79999_iter.pth https://huggingface.co/ManyOtherFunctions/face-parse-bisent/resolve/main/79999_iter.pth
|
||
resnet18-5c106cde.pth https://download.pytorch.org/models/resnet18-5c106cde.pth
|
||
NotoSansCJKsc-Regular.otf https://github.com/notofonts/noto-cjk/raw/main/Sans/OTF/SimplifiedChinese/NotoSansCJKsc-Regular.otf
|
||
model.safetensors https://huggingface.co/jonathandinu/face-parsing/resolve/main/model.safetensors
|
||
```
|
||
|
||
## 还差什么（pip 依赖）
|
||
|
||
模型已就位，但**内网机还需要 Python 依赖的离线 wheel 包**，否则 `pip install` 在内网无法联网安装。这部分**与目标机的操作系统、Python 版本、CUDA 版本强相关**，需确认后单独打包：
|
||
|
||
- **worker（GPU 机）**：`mediapipe` / `opencv-python` / `numpy<2` / `Pillow` / **`torch`+`torchvision` 的 CUDA 版**（按 GPU 的 CUDA 版本选 cu118/cu121 等）/ `transformers`（接口2 SegFormer）+ FastAPI/uvicorn 全家桶。
|
||
- **网关机**：FastAPI/uvicorn/httpx 等代理依赖 + **接口4 现需 `mediapipe`/`opencv-python`/`numpy<2`**（脸型本机计算），
|
||
仍**不需要 torch**（无 GPU 推理需求）。
|
||
|
||
> 架构已拆分（见 `docs/实现说明.md`）：算法依赖只装在 worker，网关保持轻量。
|
||
|
||
---
|
||
|
||
> 创建日期：2026-06-14 ｜ 配套：技术方案 v2.0 / 任务书 v1.3
|