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
+14 -14
View File
@@ -158,20 +158,20 @@ Override the base directory with `BGFILTER_WEIGHTS_DIR`. `models/` is gitignored
### Cross-check veto (optional, off by default in the service)
The pipeline can run a second, high-resolution matting model
(`ZhengPeng7/BiRefNet_HR-matting`, ~425 MB) as a "second opinion" that only clears
background residue trapped between hair strands. In the **HTTP service it is OFF by
default** and lazy-loaded, so you don't need this model unless you turn it on:
The pipeline runs a second, high-resolution matting model
(`ZhengPeng7/BiRefNet_HR-matting`, ~425 MB) as a "second opinion" that clears
background residue trapped between hair strands. It is **ON by default** (both CLI
and HTTP service) and, with reuse-as-seg, that same forward doubles as the
segmentation mask on the birefnet backend — so it replaces the primary seg model
rather than adding to it. **You must provision this model** (Option A or B above):
- Enable service-wide with `BGFILTER_CROSS_CHECK=1`, or per request with the
`cross_check=true` form field.
- ⚠️ **On an offline server (`HF_HUB_OFFLINE=1`) you must provision
`BiRefNet_HR-matting` first** (Option A or B above) — otherwise the first
cross-check request fails, because it cannot download the model at runtime.
- It adds one extra 2048-px inference (~35 s/image on CPU), roughly doubling latency.
- Note the config default (`configs/default.yaml`) has `cross_check.enabled: true`,
which the **CLI** honours; only the HTTP service forces it off unless
`BGFILTER_CROSS_CHECK=1`.
- ⚠️ **On an offline server (`HF_HUB_OFFLINE=1`) it must be present before the
first request** — otherwise every default request fails, since it cannot
download the model at runtime.
- Turn it off service-wide with `BGFILTER_CROSS_CHECK=0`, or override per request
with the `cross_check` form field (`true`/`false`).
- The service preloads it at startup with the rest of the warm set; on the
birefnet backend the redundant primary segmenter is skipped.
### Downloading behind a firewall (CN networks)
@@ -196,7 +196,7 @@ redirect back to `huggingface.co`, which recent `huggingface_hub` rejects with
| `BGFILTER_DEVICE` | `cpu` | Overrides **both** model and segmentation device (`cuda` for GPU) |
| `BGFILTER_MAX_IMAGE_PIXELS` | `4194304` | Reject larger inputs with `413` (~4 MP) |
| `BGFILTER_PRELOAD` | `1` | Load default models at startup (first request isn't cold) |
| `BGFILTER_CROSS_CHECK` | `0` | Enable the cross-check veto (needs `BiRefNet_HR-matting`; ~2× latency) |
| `BGFILTER_CROSS_CHECK` | config (`on`) | Force the cross-check veto on/off (`0` disables; needs `BiRefNet_HR-matting`) |
| `BGFILTER_WEIGHTS_DIR` | `models` | Where local weight folders are looked up (Option B) |
| `HF_HOME` | — | HF cache location (Option A) |
| `HF_HUB_OFFLINE` / `TRANSFORMERS_OFFLINE` | — | Set to `1` in production once weights are cached |