lhk229/BGfilter
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Restructure docs: README = what/how-to-call, DEPLOY = how-to-run

Browse Source 
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:
孔令弘
2026-07-17 04:35:17 +00:00
parent 755e5fda44
commit 35d8bf9b02
4 changed files with 206 additions and 224 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+49 -86
View File
@@ -65,7 +65,7 @@ frame — detection **fails with an error**; pass `--screen-color` explicitly in
To set it yourself, give a hex prior:
```powershell
```bash
... --screen-color "#CFEFFF"
```
@@ -76,26 +76,24 @@ auto-detected colour is used directly.)
## Environment
Use the conda environment `lightML`.
Any Python 3.11–3.13 environment (venv or conda) works:
```powershell
conda activate lightML
```bash
pip install -r requirements.txt
python -m bgfilter.cli --help
```
If the shell is not activated, call the environment Python directly:
```powershell
D:\MiniConda\envs\lightML\python.exe -m bgfilter.cli --help
```
For a server install — CPU-wheel torch, offline weights, systemd — follow
[DEPLOY.md](DEPLOY.md) instead; it covers the same dependencies with the
production choices spelled out.
## Single Image
```powershell
D:\MiniConda\envs\lightML\python.exe -m bgfilter.cli `
--input Samples\TestImage.png `
--output Outputs\TestImage_rgba.png `
--debug-dir Outputs\TestImage_debug
```bash
python -m bgfilter.cli \
--input Samples/TestImage.png \
--output Outputs/TestImage_rgba.png \
--debug-dir Outputs/TestImage_debug
```
No `--config` is needed — the built-in defaults are identical to
@@ -112,34 +110,19 @@ auto-detect the flat background), and `--trimap-mode`.
## Batch
```powershell
D:\MiniConda\envs\lightML\python.exe -m bgfilter.cli `
--input-dir Samples `
--output-dir Outputs `
--debug-dir Outputs\debug
```bash
python -m bgfilter.cli \
--input-dir Samples \
--output-dir Outputs \
--debug-dir Outputs/debug
```
## Performance (CPU reference numbers)
## Performance
Measured on a Ryzen 9700X (Zen 5, native bf16), 32 GB RAM, with cross-check on,
**`--cross-check-as-seg` enabled** and chunked global attention on. (Reuse is
off by default on this branch; without it, add the primary BiRefNet@1024
forward — roughly +20 s/image at these sizes.)
| input | precision | warm / image | peak memory |
|---|---|---|---|
| 1024x1536 | fp32 | ~45 s | — |
| 1024x1536 | bf16 | ~33 s | — |
| 2048x2048 | bf16 | ~53 s | 11.4 GB (batch), 8.1 GB (single image) |
The memory ceiling is the cross-check BiRefNet_HR forward (fixed
`input_size` 2048 regardless of the image size) — genuine live activations
of a full-resolution dense prediction net. Before chunked attention and the
mimalloc fix, the same 2048x2048 bf16 run peaked at 25.2 GB; a fully
un-optimized fp32 run would need an estimated 55-60 GB (ViTMatte's un-chunked
N^2 attention alone ~39 GB). CPUs without native bf16 (e.g. Zen 2) auto-fall
back to fp32 — on such machines prefer `--no-cross-check` if memory or
latency is tight.
Rough orders of magnitude: **~33–53 s/image** on a fast desktop CPU (bf16,
cross-check on), **~1–2 s/image** on a modern GPU. All measured numbers — CPU
lanes, GPU VRAM footprints, memory ceilings and the knobs that move them — live
in [DEPLOY.md](DEPLOY.md) §11 (*Capacity & performance*).
## Chroma-alpha debug mode
@@ -147,12 +130,12 @@ latency is tight.
alpha seed. Useful for fast inspection of chroma confidence, trimap, and despill.
(Distinct from the chroma-only *pipeline* above, which still runs ViTMatte.)
```powershell
D:\MiniConda\envs\lightML\python.exe -m bgfilter.cli `
--input-dir Samples `
--output-dir Outputs\chroma `
--debug-dir Outputs\chroma_debug `
--matting-method chroma `
```bash
python -m bgfilter.cli \
--input-dir Samples \
--output-dir Outputs/chroma \
--debug-dir Outputs/chroma_debug \
--matting-method chroma \
--device cpu
```
@@ -267,39 +250,36 @@ curl -sS \
http://127.0.0.1:18083/remove-background -o output.png
```
Config comes from `BGFILTER_CONFIG` (defaults to `configs/default.yaml` when present);
`BGFILTER_DEVICE` overrides both model and segmentation device; `BGFILTER_MAX_IMAGE_PIXELS`
caps input size (default ~4MP → `413`); `BGFILTER_PRELOAD=1` loads the default models at
startup; `BGFILTER_AUTH_TOKEN` gates the endpoint (see Authentication above).
Runtime configuration (config file, device, size caps, preload, auth token,
pipelining workers) is all via `BGFILTER_*` environment variables — the full table
is [DEPLOY.md](DEPLOY.md) §6.
Like the CLI, the service runs the **cross-model veto by default** (config
default: on); its HR-matting model is preloaded with the rest of the warm set.
Set `BGFILTER_CROSS_CHECK=0` to turn it off service-wide, or use the per-request
`cross_check` form field to override either way; `/healthz` reports the default
as `crossCheck`. With `cross_check.reuse_as_seg: true` in the config (off by
default) the HR-matting forward replaces the primary seg forward instead of
adding to it, and the then-redundant primary segmenter is skipped at startup.
Like the CLI, the service runs the **cross-model veto by default**; `/healthz`
reports the effective default as `crossCheck` and the per-request `cross_check`
field overrides it either way (service-wide kill switch: `BGFILTER_CROSS_CHECK=0`).
`cross_check.reuse_as_seg` (config-only, default off — see *Pipelines* above) has
no per-request switch; changing it means editing the config and restarting.
## Quality Check
The quality checker measures alpha validity and edge spill on semi-transparent edge
pixels.
```powershell
D:\MiniConda\envs\lightML\python.exe -m bgfilter.quality_cli `
Outputs\TestImage_rgba.png `
```bash
python -m bgfilter.quality_cli \
Outputs/TestImage_rgba.png \
--max-edge-green-excess-p95 0.30
```
Run the bundled sample smoke check:
```powershell
D:\MiniConda\envs\lightML\python.exe scripts\smoke_samples.py `
--samples-dir Samples `
--output-dir Outputs\smoke_samples `
--config configs\default.yaml `
--device cpu `
--fallback-to-chroma-alpha `
```bash
python scripts/smoke_samples.py \
--samples-dir Samples \
--output-dir Outputs/smoke_samples \
--config configs/default.yaml \
--device cpu \
--fallback-to-chroma-alpha \
--max-edge-green-excess-p95 0.30
```
@@ -310,26 +290,9 @@ D:\MiniConda\envs\lightML\python.exe scripts\smoke_samples.py `
`anime-seg` (`skytnt/anime-seg`) is a plain ONNX download; `birefnet`
(`ZhengPeng7/BiRefNet`) ships custom modelling code so it needs
`trust_remote_code=True` plus `timm` / `einops` / `kornia`.
- Downloading the weights behind a firewall — the reliable combination is the
`hf-mirror.com` mirror **with the local proxy bypassed** and **Xet disabled**:
```powershell
$env:HF_ENDPOINT = "https://hf-mirror.com" # domestic mirror
$env:NO_PROXY = "*" # bypass the proxy; the mirror is direct
$env:HF_HUB_DISABLE_XET = "1" # these repos are Xet-backed; force classic HTTP
```
Two gotchas this avoids: (1) mirror + an overseas proxy makes the mirror's `resolve`
bounce back to `huggingface.co`, which recent `huggingface_hub` rejects with
`FileMetadataError`; (2) with `hf-xet` installed the Xet download path fails instantly.
Once the weights are cached, run offline with `HF_HUB_OFFLINE=1 TRANSFORMERS_OFFLINE=1`
(as the service does in production).
- Bundling weights in the project — instead of the HF cache, drop each model into a
plain folder named after the repo basename under `models/`:
`models/vitmatte-base-composition-1k`, `models/BiRefNet`, `models/anime-seg`,
`models/BiRefNet_HR-matting` (cross-check second opinion, default on). The loader
prefers a matching local folder and falls back to the HF repo id / cache when absent, so
it is opt-in. Populate them with e.g. `hf download ZhengPeng7/BiRefNet --local-dir
models/BiRefNet`. Override the base directory with `BGFILTER_WEIGHTS_DIR`. `models/` is
gitignored.
- **Provisioning weights** — offline HF cache, plain `models/` folders
(`BGFILTER_WEIGHTS_DIR`), the `scripts/fetch_weights.py` one-shot downloader,
and the CN-network mirror workaround — is covered in [DEPLOY.md](DEPLOY.md) §5.
- Foreground colour estimation uses pymatting's `estimate_foreground_ml` to propagate
clean foreground colour into semi-transparent edges before de-spill. Set
`foreground.method: unmix` to fall back to the legacy heuristic.