docs: document background_mode in DEPLOY.md / DEPLOY_ZH.md

Sync the deployment guides with the c56e58a HTTP change: add a
"Background mode (flat vs complex)" subsection and a complex-mode curl
example. Notes that complex reuses existing weights, ignores screen_color,
defaults the cross-check veto off, and returns X-BGFilter-Background-Mode;
points to README for the full field/header reference.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
2026-07-14 14:41:06 +08:00
parent c56e58affe
commit 6baf6ae541
2 changed files with 39 additions and 0 deletions
+21
View File
@@ -178,6 +178,23 @@ and HTTP service). **You must provision this model** (Option A or B above):
CPU, ~1 GB less VRAM; the redundant primary segmenter is then skipped at
startup). Off by default so the veto stays an independent signal.
### Background mode (flat vs complex)
The `/remove-background` `background_mode` form field selects the pipeline:
- `flat` (**default**, also when omitted): the colour-keyed pipeline for a solid
flat background — unchanged behaviour.
- `complex`: non-flat / scene background. No colour key: segmentation alone drives
the trimap and the colour-keyed stages (background auto-detect, hue split, chroma
suppression, despill) are bypassed. `screen_color` is ignored; expect flat
backgrounds to stay stronger on hair-level detail.
No extra weights: `complex` reuses the already-provisioned BiRefNet segmenter +
ViTMatte. The cross-check veto still works in `complex` (via a hue-free gate) but
**defaults off** there — pass `cross_check=on` to enable it. The response echoes the
mode used in the `X-BGFilter-Background-Mode: flat|complex` header. Full field/header
reference is in `README.md` → *HTTP service*.
### Downloading behind a firewall (CN networks)
If direct HuggingFace access is blocked, use the mirror **with the local proxy
@@ -310,6 +327,10 @@ curl -s http://127.0.0.1:18083/healthz
curl -sS -F "file=@input.png" -F "screen_color=#CFEFFF" \
http://127.0.0.1:18083/remove-background -o out.png
# non-flat / scene background (no colour key; cross-check defaults off here)
curl -sS -F "file=@scene.jpg" -F "background_mode=complex" \
http://127.0.0.1:18083/remove-background -o out.png
```
## 10. Exposing the service
+18
View File
@@ -165,6 +165,20 @@ hf download ZhengPeng7/BiRefNet_HR-matting --local-dir models/BiRefNet_HR-
1 GB 显存;此时冗余的 primary 分割模型在启动时会被跳过)。默认关闭是为了让否决
保持为独立信号。
### 背景模式(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 服务*。
### 墙内下载(国内网络)
若直连 HuggingFace 被墙,用镜像 **并绕过本地代理、禁用 Xet**——这是稳定可用的组合:
@@ -286,6 +300,10 @@ curl -s http://127.0.0.1:18083/healthz
curl -sS -F "file=@input.png" -F "screen_color=#CFEFFF" \
http://127.0.0.1:18083/remove-background -o out.png
# 非纯色/实景背景(无色键;此模式 cross-check 默认关)
curl -sS -F "file=@scene.jpg" -F "background_mode=complex" \
http://127.0.0.1:18083/remove-background -o out.png
```
## 10. 对外暴露