chore: 预下载离线模型权重+字体，补充内网部署清单
- 下载 BiSeNet(79999_iter.pth 53MB) + resnet18骨干(45MB) + Noto Sans CJK SC字体(16MB) 到 face_analysis/weights 与 fonts（大文件 .gitignore 不入库，靠文件拷贝带入内网） - 新增 OFFLINE_ASSETS.md：文件清单+sha256校验+resnet18骨干离线放置说明+来源URL - 字体由 SourceHanSansSC 改为 NotoSansCJKsc(同一套字体)，同步更新两份文档引用 - 文档补充内网/离线注意事项(resnet18联网下载坑、权重已预置)
This commit is contained in:
@@ -2,3 +2,12 @@ venv/
|
||||
__pycache__/
|
||||
*.pyc
|
||||
.env
|
||||
|
||||
# 离线资产（大文件，手动拷贝到内网机，不入 git；清单见 OFFLINE_ASSETS.md）
|
||||
face_analysis/weights/*.pth
|
||||
face_analysis/fonts/*.otf
|
||||
|
||||
# 生成的标注图、测试输出
|
||||
static/annotations/*
|
||||
!static/annotations/.gitkeep
|
||||
tests/output/
|
||||
|
||||
@@ -0,0 +1,66 @@
|
||||
# 离线资产清单（内网部署用）
|
||||
|
||||
开发/部署机在内网无法联网，以下模型权重与字体**已预先下载**放在仓库对应目录。
|
||||
这些文件**不进 git**（见 `.gitignore`），通过文件拷贝（U盘/内网共享）随项目一起带到内网机即可。
|
||||
|
||||
> 拷贝到内网机后，用本文件末尾的 sha256 校验完整性，确认未损坏。
|
||||
|
||||
## 文件清单
|
||||
|
||||
| 文件 | 路径 | 大小 | 用途 |
|
||||
|------|------|------|------|
|
||||
| BiSeNet 主权重 | `face_analysis/weights/79999_iter.pth` | 53,289,463 B (~53MB) | 人脸解析分割（方案 B，取真实发际线/头顶） |
|
||||
| resnet18 骨干 | `face_analysis/weights/resnet18-5c106cde.pth` | 46,827,520 B (~45MB) | BiSeNet 的骨干网络，**内网必需**（见下） |
|
||||
| 中文字体 | `face_analysis/fonts/NotoSansCJKsc-Regular.otf` | 16,437,364 B (~16MB) | 标注图中文渲染（= 思源黑体，同一套字体） |
|
||||
|
||||
## sha256 校验
|
||||
|
||||
```
|
||||
468e13ca13a9b43cc0881a9f99083a430e9c0a38abd935431d1c28ee94b26567 face_analysis/weights/79999_iter.pth
|
||||
5c106cde386e87d4033832f2996f5493238eda96ccf559d1d62760c4de0613f8 face_analysis/weights/resnet18-5c106cde.pth
|
||||
2c76254f6fc379fddfce0a7e84fb5385bb135d3e399294f6eeb6680d0365b74b face_analysis/fonts/NotoSansCJKsc-Regular.otf
|
||||
```
|
||||
|
||||
校验命令：
|
||||
```bash
|
||||
# Linux/macOS
|
||||
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
|
||||
```
|
||||
```powershell
|
||||
# Windows PowerShell
|
||||
Get-FileHash face_analysis\weights\79999_iter.pth -Algorithm SHA256
|
||||
```
|
||||
|
||||
> 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
|
||||
```
|
||||
|
||||
## 还差什么（pip 依赖）
|
||||
|
||||
模型已就位，但**内网机还需要 Python 依赖的离线 wheel 包**（`mediapipe`/`opencv-python`/`torch` CPU 版等），否则 `pip install` 在内网无法联网安装。这部分**与目标机的操作系统和 Python 版本强相关**，需确认后单独打包：见仓库提交说明或联系下载方补充 `wheels/` 目录。
|
||||
|
||||
---
|
||||
|
||||
> 创建日期：2026-06-14 ｜ 配套：技术方案 v2.0 / 任务书 v1.3
|
||||
@@ -27,7 +27,7 @@
|
||||
2. **新增逻辑全部放在 `face_analysis/` 包内**，`app.py` 只做编排（读图→校验→调用→返回），保持单文件 app 的薄控制器风格。
|
||||
3. **依赖锁版本**：`numpy<2`（用 1.26.4）。torch 用 CPU 版。安装走 `pip.conf` 里的腾讯云镜像（torch 需用官方 CPU index）。
|
||||
4. **模型权重不入 git**：`face_analysis/weights/*.pth` 写进 `.gitignore`，由 §2 的下载脚本拉取。
|
||||
5. **中文字体入 git**：`face_analysis/fonts/SourceHanSansSC-Regular.otf`。
|
||||
5. **中文字体**：`face_analysis/fonts/NotoSansCJKsc-Regular.otf`（= 思源黑体，已预下载，见 `OFFLINE_ASSETS.md`）。
|
||||
6. **每个模块都要能单独 import 且有 `if __name__ == "__main__"` 自测入口**，方便分阶段验证。
|
||||
7. 代码风格、注释密度与 `app.py` 保持一致；注释用中文。
|
||||
8. **不要 mock 兜底**：算法失败时返回对应错误码，**不得**回退成硬编码示例数据。
|
||||
@@ -42,7 +42,12 @@
|
||||
`./venv/bin/pip install torch==2.2.2 torchvision==0.17.2 --index-url https://download.pytorch.org/whl/cpu`
|
||||
其余走现有 `pip.conf` 镜像。
|
||||
3. 创建目录骨架：`face_analysis/{__init__.py,fonts/,weights/}`、`static/annotations/`。
|
||||
4. 写 `scripts/download_weights.sh`：下载 BiSeNet face-parsing 权重 `79999_iter.pth`（来源：face-parsing.PyTorch 仓库 release）到 `face_analysis/weights/`，下载思源黑体到 `face_analysis/fonts/`（若已手动放置则跳过）。
|
||||
4. **权重/字体已预下载到位**（内网无需联网，见根目录 `OFFLINE_ASSETS.md` 的 sha256 清单）：
|
||||
- `face_analysis/weights/79999_iter.pth`（BiSeNet 主权重 ~53MB）
|
||||
- `face_analysis/weights/resnet18-5c106cde.pth`（骨干 ~45MB）
|
||||
- `face_analysis/fonts/NotoSansCJKsc-Regular.otf`（中文字体 ~16MB）
|
||||
仍需写 `scripts/download_weights.sh`（供联网环境/生产机重建），但内网执行时跳过此步、直接用已有文件。
|
||||
⚠️ **resnet18 骨干**：BiSeNet 初始化会尝试联网下载骨干，内网会失败——需把 `resnet18-5c106cde.pth` 拷到 `~/.cache/torch/hub/checkpoints/` 或改 BiSeNet 代码从 `weights/` 本地加载。
|
||||
5. 更新 `.gitignore`：忽略 `face_analysis/weights/*.pth`、`static/annotations/*`（保留 `.gitkeep`）。
|
||||
|
||||
**交付物**
|
||||
@@ -56,8 +61,8 @@
|
||||
print('numpy', numpy.__version__); print('mediapipe', mediapipe.__version__)"
|
||||
```
|
||||
- 必须无 import 错误；`numpy.__version__` 以 `1.26` 开头。
|
||||
- `ls face_analysis/weights/79999_iter.pth` 存在且 >40MB。
|
||||
- `ls face_analysis/fonts/SourceHanSansSC-Regular.otf` 存在。
|
||||
- `ls face_analysis/weights/79999_iter.pth` 存在且 >40MB；`resnet18-5c106cde.pth` 存在。
|
||||
- `ls face_analysis/fonts/NotoSansCJKsc-Regular.otf` 存在。
|
||||
|
||||
**完成标准**：上述命令全部通过，无报错。
|
||||
|
||||
|
||||
@@ -60,7 +60,11 @@ pip install mediapipe opencv-python pillow numpy -i https://pypi.tuna.tsinghua.e
|
||||
- **真实发际线** = 沿面部中轴线（用 §4 的 `brow_center_x` 作为 x），从上往下扫描，**头发区域 → 皮肤区域**的第一个交界 y 坐标。
|
||||
- **头顶** = 头发 mask 的**最高点**（最小 y）。
|
||||
|
||||
> 权重需单独下载（`79999_iter.pth`，~50 MB），放入 `face_analysis/weights/`，不入 git（写进 `.gitignore`），由部署脚本拉取。
|
||||
> 权重需单独下载，放入 `face_analysis/weights/`，不入 git（写进 `.gitignore`）：
|
||||
> - `79999_iter.pth`（~53 MB）— BiSeNet 主权重。
|
||||
> - `resnet18-5c106cde.pth`（~45 MB）— BiSeNet 用的 resnet18 骨干。**离线/内网环境必须预放**：BiSeNet 初始化时会尝试用 `torch.utils.model_zoo` 联网下载该骨干，内网会失败。需把它放进 torch hub 缓存（`~/.cache/torch/hub/checkpoints/`）或改代码从本地路径加载。
|
||||
>
|
||||
> **本仓库已预先下载好上述权重 + 字体**（见根目录 `OFFLINE_ASSETS.md` 的 sha256 清单），内网机器无需联网，直接使用。
|
||||
|
||||
---
|
||||
|
||||
@@ -432,8 +436,8 @@ def create_annotated_image(input_image_path, vertical_result, eye_result, px_per
|
||||
|
||||
# ⚠️ 字体：PingFangSC 是 macOS 字体，Linux 服务器没有；且 ImageFont.load_default()
|
||||
# 不渲染中文（会出现方块/空白）。必须随仓库打包一个中文 TTF 并用绝对路径加载。
|
||||
# 建议放 face_analysis/fonts/SourceHanSansSC-Regular.otf（思源黑体）或 Noto Sans CJK。
|
||||
FONT_PATH = os.path.join(os.path.dirname(__file__), "fonts", "SourceHanSansSC-Regular.otf")
|
||||
# 已打包 Noto Sans CJK SC（= 思源黑体，同一套字体）：face_analysis/fonts/NotoSansCJKsc-Regular.otf
|
||||
FONT_PATH = os.path.join(os.path.dirname(__file__), "fonts", "NotoSansCJKsc-Regular.otf")
|
||||
font = ImageFont.truetype(FONT_PATH, 10) # 字体缺失时直接抛错，避免静默降级成乱码
|
||||
|
||||
line_color = (255, 255, 255, 255) # #FFFFFF 100%
|
||||
@@ -624,9 +628,10 @@ hair/
|
||||
│ ├── annotation.py # 标注图片生成（numpy 渐变线 + 中文字体）
|
||||
│ ├── face_mesh_landmarks.py # 关键点索引常量
|
||||
│ ├── fonts/
|
||||
│ │ └── SourceHanSansSC-Regular.otf # 打包的中文字体（入 git）
|
||||
│ │ └── NotoSansCJKsc-Regular.otf # 打包的中文字体（= 思源黑体）
|
||||
│ └── weights/ # 模型权重（不入 git，部署脚本拉取）
|
||||
│ └── 79999_iter.pth # BiSeNet face-parsing 权重 ~50MB
|
||||
│ ├── 79999_iter.pth # BiSeNet face-parsing 权重 ~53MB
|
||||
│ └── resnet18-5c106cde.pth # BiSeNet 骨干权重 ~45MB（离线必需，见下）
|
||||
├── static/
|
||||
│ └── annotations/ # 生成的标注 PNG 存放目录
|
||||
├── .gitignore # 忽略 face_analysis/weights/*.pth
|
||||
|
||||
Reference in New Issue
Block a user