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:
+48
-26
@@ -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):**
|
||||
|
||||
Reference in New Issue
Block a user