Add per-request cross_check toggle to the HTTP service (lazy-loaded)

POST /remove-background gains an optional cross_check form field
(1/0/true/false/yes/no/on/off; empty = service default). The effective
state is reported in the X-BGFilter-Cross-Check response header.

The cross-check model is now never preloaded at startup: the first
request that enables it pays the one-time load (measured ~8 s on top of
the ~50 s cc inference), after which the instance is cached and shared.

Verified with a functional test against PipelineManager: cc-off requests
never load the model, cc=1 lazy-loads then reuses the cached instance,
and omitting the field falls back to the service default.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
2026-07-04 22:34:08 +08:00
parent 11c591e5b5
commit 8417653598
3 changed files with 51 additions and 11 deletions
+13 -3
View File
@@ -154,6 +154,9 @@ Two endpoints:
- `file` (required) — the source image. The field name is fixed as `file`.
- `screen_color` (optional) — `#RRGGBB` prior; omit/empty for auto-detect.
- `seg_model` (optional) — `birefnet` (default) or `anime-seg`.
- `cross_check` (optional) — `1`/`0` (also `true`/`false`/`yes`/`no`/`on`/`off`);
per-request override of the cross-model veto. Omit/empty to use the service
default. The response reports the effective state in `X-BGFilter-Cross-Check`.
```bash
# default (birefnet + auto background colour)
@@ -166,6 +169,10 @@ curl -sS \
-F "screen_color=#CFEFFF" \
-F "seg_model=anime-seg" \
http://127.0.0.1:18083/remove-background -o output.png
# enable the cross-model veto for this request only (see below; slow on CPU)
curl -sS -F "file=@input.png" -F "cross_check=1" \
http://127.0.0.1:18083/remove-background -o output.png
```
Config comes from `BGFILTER_CONFIG` (defaults to `configs/default.yaml` when present);
@@ -174,9 +181,12 @@ caps input size (default ~4MP → `413`); `BGFILTER_PRELOAD=1` loads the default
startup. Run a single worker (`--workers 1`) — each worker loads its own copy of the models.
Unlike the CLI, the service defaults the **cross-model veto to off** — it adds one
extra large-model inference (~35 s/image on CPU, 14 s → 49 s total). Opt in with
`BGFILTER_CROSS_CHECK=1` (worth it on GPU or when hair-gap residue matters more than
latency); `/healthz` reports the effective state as `crossCheck`.
extra large-model inference (~35 s/image on CPU, 14 s → 49 s total). Enable it
per request with the `cross_check` form field, or flip the service default with
`BGFILTER_CROSS_CHECK=1` (worth it on GPU or when hair-gap residue matters more
than latency); `/healthz` reports the default as `crossCheck`. The cross-check
model is lazy-loaded: it is never preloaded at startup, so the first request that
enables it also pays the one-time model load (~1 GB) on top of the inference.
## Quality Check