Restructure docs: README = what/how-to-call, DEPLOY = how-to-run

Each fact now has exactly one home, with pointers instead of copies:

README (EN+ZH):
- Drop stale workstation env (conda lightML, D:\MiniConda paths); CLI
  examples now use plain `python -m bgfilter.cli` with bash syntax.
- Performance section reduced to orders of magnitude + pointer; the
  measured workstation table moved to DEPLOY §11.
- Notes: HF-mirror workaround and models/-folder layout (both duplicated
  DEPLOY §5 verbatim) replaced with one-line pointers.
- HTTP service: env-var prose replaced with a pointer to DEPLOY §6.
- ZH parity fixes: add the missing image_url curl example; 400/413 rows
  now mention image_url/fetch limits like the EN table.

DEPLOY (EN+ZH):
- §0: supervisord management expanded to a full command set (status/
  restart/stop/start/shutdown, both log paths, manual supervisord rescue
  after a container restart, how supervisord.conf changes are applied).
- §5: cross-check veto and background-mode subsections trimmed to
  deploy-side facts + pointers to README Pipelines/HTTP service.
- §11: absorbs the workstation CPU reference table from README.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
2026-07-17 04:35:17 +00:00
parent 755e5fda44
commit 35d8bf9b02
4 changed files with 206 additions and 224 deletions
+48 -26
View File
@@ -45,14 +45,32 @@ python 在 `/root/miniconda3`。
- **容器重启后**服务不会自动起来——AutoDL 没有 systemd / 开机钩子,自启写在 `~/.bashrc` 里,
需要**开一个交互式 shell(SSH / JupyterLab 终端)** 才会触发拉起。
与 supervisord 打交道(socket 在 `~/bgfilter-supervisor.sock`,配置在 `~/supervisord.conf`):
**服务管理**(supervisorctl 与 python 同目录;socket 在 `~/bgfilter-supervisor.sock`,
supervisord 配置在 `~/supervisord.conf`):
```bash
/root/miniconda3/bin/supervisorctl -c ~/supervisord.conf status bgfilter # 状态
/root/miniconda3/bin/supervisorctl -c ~/supervisord.conf restart bgfilter # 重启
tail -f ~/autodl-tmp/bgfilter.log # 日志(默认 ~/autodl-tmp)
S="/root/miniconda3/bin/supervisorctl -c $HOME/supervisord.conf"
$S status bgfilter # 状态 + 运行时长
$S restart bgfilter # 重启(如改了 configs/*.yaml 之后)
$S stop bgfilter # 停服务(supervisord 本身继续跑)
$S start bgfilter # 再启动
$S shutdown # 全部停掉,包括 supervisord 自己
tail -f ~/autodl-tmp/bgfilter.log # 服务日志(目录由 --log-dir 决定)
tail -f ~/supervisord.log # supervisord 自己的日志(服务起不来时看这个)
```
若 supervisord 本身没在跑——容器刚重启还没开过 shell,或报 socket 残留错误——照
`~/.bashrc` 自启的方式手动拉起:
```bash
rm -f ~/bgfilter-supervisor.sock ~/supervisord.pid
/root/miniconda3/bin/supervisord -c ~/supervisord.conf
```
改 `~/supervisord.conf` 本身(端口、日志路径等)的方式是重跑部署脚本——它会重新生成
该文件并做 `reread + update + restart`。
> 改了 `configs/*.yaml`(比如开 `cross_check.reuse_as_seg`)后,用上面的 `restart bgfilter`
> 让服务重新加载配置——配置只在启动时读入,没有请求级开关。
@@ -201,32 +219,22 @@ hf download ZhengPeng7/BiRefNet_HR-matting --local-dir models/BiRefNet_HR-
### cross-check 否决(默认开启)
管线会再跑一个高分辨率 matting 模型(`ZhengPeng7/BiRefNet_HR-matting`,约 425 MB)
作为"第二意见",清理发丝间残留的背景色。**CLI 和 HTTP 服务都默认开启**,因此**必须
备好这个模型**(上面方案 A 或 B):
管线会再跑一个 matting 模型(`ZhengPeng7/BiRefNet_HR-matting`,约 425 MB)作为独立的
"第二意见"——它做什么、为什么,见 [README_ZH.md](README_ZH.md) → *管线*。部署侧要点:
- ⚠️ **离线服务器(`HF_HUB_OFFLINE=1`)必须在第一个请求前就备好它**,否则每个默认请求都会
失败——运行时它无法联网下载模型。
- 服务级关闭:`BGFILTER_CROSS_CHECK=0`;或按请求覆盖:表单字段 `cross_check`(`true`/`false`)。
- 服务启动时会随暖机集一起预载它。
- 可选:配置里 `cross_check.reuse_as_seg: true`(默认**关**)可让这次前向在 birefnet
后端兼作分割掩码——**替换**而非叠加 primary 分割模型(CPU 快约 20 秒/张、GPU 省约
1 GB 显存;此时冗余的 primary 分割模型在启动时会被跳过)。默认关闭是为了让否决
保持为独立信号。
- **CLI 和 HTTP 服务都默认开启**,因此**必须备好这个模型**(上面方案 A 或 B)。
⚠️ 离线服务器(`HF_HUB_OFFLINE=1`)必须在第一个请求前就备好它,否则每个默认请求都失败。
- 服务级关闭:`BGFILTER_CROSS_CHECK=0`;按请求覆盖:表单字段 `cross_check`。
开启时服务启动即预载。
- 配置里 `cross_check.reuse_as_seg: true`(默认**关**)让这次前向兼作分割掩码:
少载一个模型、CPU 快约 20 秒/张、GPU 省约 1 GB 显存。仅配置文件可设——改动需重启。
### 背景模式(flat vs complex)
`/remove-background` 的 `background_mode` 表单字段选择管线:
- `flat`(**默认**,不传时也是它):纯色背景的色键管线——行为不变。
- `complex`:非纯色/实景背景。无色键:完全由分割器驱动 trimap,色键相关阶段(背景
自动探测、色相劈分、chroma 抑制、despill)全部跳过。`screen_color` 被忽略;发丝
级细节通常弱于纯色模式。
不需要额外权重:`complex` 复用已部署的 BiRefNet 分割器 + ViTMatte。cross-check 否决
在 `complex` 下仍可用(走无色相门控),但**默认关闭**——传 `cross_check=on` 才启用。
响应头 `X-BGFilter-Background-Mode: flat|complex` 回显本次实际模式。完整的字段/响应头
参考见 `README_ZH.md` → *HTTP 服务*。
`background_mode=complex`(非纯色/实景背景)**不需要额外权重**——复用已部署的
BiRefNet 分割器 + ViTMatte,跳过色键相关阶段。cross-check 否决在 complex 模式下
**默认关闭**(传 `cross_check=on` 启用)。字段语义与响应头见
[README_ZH.md](README_ZH.md) → *HTTP 服务*。
### 墙内下载(国内网络)
@@ -395,6 +403,20 @@ curl -H "X-Genarrative-Image-Token: <token>" \
- CPU 吞吐:**`cpu-fast` lane** 约 **14–15 秒/张(1.5 MP)**(base ViTMatte + 一个
BiRefNet@1024,分块注意力)。**默认 lane** 更慢——cross-check 会多跑一次 HR-matting@2048
前向。请求被全局锁串行,单实例按每分钟几张估算。
- **默认 lane,工作站 CPU 参考(Ryzen 9700X,原生 bf16,32 GB;cross-check 开且
`reuse_as_seg` 开,分块注意力):**
| 输入 | 精度 | warm / 每图 | 峰值内存 |
|---|---|---|---|
| 1024×1536 | fp32 | ~45 s | — |
| 1024×1536 | bf16 | ~33 s | — |
| 2048×2048 | bf16 | ~53 s | 11.4 GB(批处理)、8.1 GB(单图) |
不开 `reuse_as_seg` 要加上主 BiRefNet@1024 前向(每图约 +20 s)。内存上限来自
cross-check 的 HR 前向(无论图多大都固定 `input_size` 2048)。分块注意力之前,
同一个 2048² bf16 run 峰值 25.2 GB;完全未优化的 fp32 估计要 55–60 GB。无原生
bf16 的 CPU(如 Zen 2)自动回落 fp32——这类机器上内存或延迟紧张时优先
`--no-cross-check`。
- 要提吞吐:上 GPU(`BGFILTER_DEVICE=cuda`,装 CUDA 版 torch),大约快一个数量级;
和/或多实例 + 负载均衡(每个都 `--workers 1`)。
- **GPU 部署(实测,RTX 5070 Ti 16 GB,完整管线——cross-check 开,bf16):**