Make cross-check and reuse-as-seg the service default

Cross-check + reuse-as-seg are already the config/CLI default; align the HTTP
service with them instead of forcing cross-check off. The earlier off-by-default
was to avoid the extra inference, but reuse-as-seg now makes that forward double
as the seg mask (birefnet backend) -- it replaces the primary seg model rather
than adding to it, so the cost concern is gone.

- app.py: honour the config default (on); BGFILTER_CROSS_CHECK still forces
  either way, unset = config.
- service.py preload: warm the cross-check HR-matting model, and skip the now-
  redundant primary segmenter when reuse covers segmentation.
- README / DEPLOY(_ZH): document cross-check as default-on, BiRefNet_HR-matting
  as required (not optional), BGFILTER_CROSS_CHECK=0 to disable.

Verified: service defaults cross_check on, env forces both ways, preload picks
cross-checker and skips the primary segmenter.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
2026-07-06 16:11:43 +08:00
parent c19a35de80
commit ad445611ad
5 changed files with 52 additions and 41 deletions
+10 -11
View File
@@ -147,18 +147,17 @@ hf download ZhengPeng7/BiRefNet_HR-matting --local-dir models/BiRefNet_HR-
用 `BGFILTER_WEIGHTS_DIR` 可改基目录。`models/` 已被 gitignore。
### cross-check 否决(可选,服务里默认关闭)
### cross-check 否决(默认开启)
管线可以再跑一个高分辨率 matting 模型(`ZhengPeng7/BiRefNet_HR-matting`,约 425 MB)
作为"第二意见",专门清理发丝间残留的背景色。在 **HTTP 服务里默认是关的**、且懒加载,
所以不开启就不需要这个模型:
管线会再跑一个高分辨率 matting 模型(`ZhengPeng7/BiRefNet_HR-matting`,约 425 MB)
作为"第二意见",清理发丝间残留的背景色。**CLI 和 HTTP 服务都默认开启**,而且开了
reuse-as-seg 之后,在 birefnet 后端这同一次前向还兼作分割掩码——它是**替换**了 primary
分割模型,而不是额外叠加。因此**必须备好这个模型**(上面方案 A 或 B):
- 服务级开启:`BGFILTER_CROSS_CHECK=1`;或按请求:表单字段 `cross_check=true`。
- ⚠️ **离线服务器(`HF_HUB_OFFLINE=1`)必须先备好 `BiRefNet_HR-matting`**(上面方案 A 或 B),
否则第一个 cross-check 请求会失败——运行时它无法联网下载模型。
- 每张图多一次 2048 分辨率推理(CPU 上约 35s/张),延迟大约翻倍。
- 注意:配置默认(`configs/default.yaml`)里 `cross_check.enabled: true`,**CLI 会遵循它**;
只有 HTTP 服务强制关闭,除非设了 `BGFILTER_CROSS_CHECK=1`。
- ⚠️ **离线服务器(`HF_HUB_OFFLINE=1`)必须在第一个请求前就备好它**,否则每个默认请求都会
失败——运行时它无法联网下载模型。
- 服务级关闭:`BGFILTER_CROSS_CHECK=0`;或按请求覆盖:表单字段 `cross_check`(`true`/`false`)。
- 服务启动时会随暖机集一起预载它;在 birefnet 后端,冗余的 primary 分割模型会被跳过。
### 墙内下载(国内网络)
@@ -182,7 +181,7 @@ export HF_HUB_DISABLE_XET=1 # 这些 repo 是 Xet 存储;强
| `BGFILTER_DEVICE` | `cpu` | 同时覆盖 model 和 segmentation 的 device(GPU 用 `cuda`)|
| `BGFILTER_MAX_IMAGE_PIXELS` | `4194304` | 超过则返回 `413`(约 4 MP)|
| `BGFILTER_PRELOAD` | `1` | 启动时预加载默认模型(首个请求不用冷加载)|
| `BGFILTER_CROSS_CHECK` | `0` | 启用 cross-check 否决(需 `BiRefNet_HR-matting`;延迟约 ×2)|
| `BGFILTER_CROSS_CHECK` | 配置(`on`)| 强制开/关 cross-check 否决(`0` 关闭;需 `BiRefNet_HR-matting`)|
| `BGFILTER_WEIGHTS_DIR` | `models` | 本地权重文件夹的查找目录(方案 B)|
| `HF_HOME` | — | HF 缓存位置(方案 A)|
| `HF_HUB_OFFLINE` / `TRANSFORMERS_OFFLINE` | — | 权重缓存好后,生产设为 `1` |