Document weight file layout and cross-check in DEPLOY
- Per-model required-file directory tree for the local models/ layout (ViTMatte / BiRefNet / anime-seg), noting which files each loader needs. - Add ZhengPeng7/BiRefNet_HR-matting as the optional 4th model, used only by the cross-check veto; new "cross-check" subsection covering enablement, the offline-provisioning requirement, and the ~2x latency. - Add BGFILTER_CROSS_CHECK to the env-var table and a troubleshooting row for the offline "500 inference failed" case. - Mirror all of the above into DEPLOY_ZH.md. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
@@ -79,8 +79,10 @@ print('torch', torch.__version__, 'cuda=', torch.version.cuda)"
|
||||
|
||||
## 5. Provide the model weights
|
||||
|
||||
Three models are used: `hustvl/vitmatte-base-composition-1k` (matting),
|
||||
Three models are used by default: `hustvl/vitmatte-base-composition-1k` (matting),
|
||||
`ZhengPeng7/BiRefNet` (default segmenter), `skytnt/anime-seg` (optional segmenter).
|
||||
A fourth model, `ZhengPeng7/BiRefNet_HR-matting` (~0.9 GB), is only needed if you
|
||||
enable the **cross-check** veto — see the note at the end of this section.
|
||||
Pick **one** of the two layouts below.
|
||||
|
||||
### Option A — HuggingFace cache + offline mode (recommended)
|
||||
@@ -92,6 +94,7 @@ export HF_HOME=/opt/genarrative-image-host/bgfilter-service/model-cache/hf
|
||||
hf download hustvl/vitmatte-base-composition-1k
|
||||
hf download ZhengPeng7/BiRefNet
|
||||
hf download skytnt/anime-seg
|
||||
hf download ZhengPeng7/BiRefNet_HR-matting # only if using cross-check (see below)
|
||||
```
|
||||
|
||||
At runtime set `HF_HOME` to the same path plus `HF_HUB_OFFLINE=1
|
||||
@@ -118,8 +121,13 @@ finds it (`ZhengPeng7/BiRefNet` → `models/BiRefNet`). Required files per model
|
||||
│ ├── BiRefNet_config.py # custom code — required by trust_remote_code
|
||||
│ ├── birefnet.py # custom code — required by trust_remote_code
|
||||
│ └── model.safetensors # ~424 MB
|
||||
└── anime-seg/ # optional segmenter (seg_model=anime-seg)
|
||||
└── isnetis.onnx # ~168 MB
|
||||
├── anime-seg/ # optional segmenter (seg_model=anime-seg)
|
||||
│ └── isnetis.onnx # ~168 MB
|
||||
└── BiRefNet_HR-matting/ # optional — only for the cross-check veto
|
||||
├── config.json
|
||||
├── BiRefNet_config.py # custom code — required by trust_remote_code
|
||||
├── birefnet.py # custom code — required by trust_remote_code
|
||||
└── model.safetensors # ~0.9 GB
|
||||
```
|
||||
|
||||
Notes:
|
||||
@@ -129,7 +137,8 @@ Notes:
|
||||
to build the model. Keep `config.json` + `model.safetensors` alongside them. (The
|
||||
repo's `handler.py` / `requirements.txt` / `README.md` are not needed.)
|
||||
- **anime-seg**: only `isnetis.onnx` is read; nothing else is required.
|
||||
- `anime-seg` is optional — omit its folder if you never use `seg_model=anime-seg`.
|
||||
- `anime-seg` and `BiRefNet_HR-matting` are optional — omit their folders unless you
|
||||
use `seg_model=anime-seg` / the cross-check veto respectively.
|
||||
|
||||
The easiest way to populate the folders is to let `hf download` fetch them (it also
|
||||
pulls a couple of unused files like `README.md`, which is harmless):
|
||||
@@ -138,10 +147,28 @@ pulls a couple of unused files like `README.md`, which is harmless):
|
||||
hf download hustvl/vitmatte-base-composition-1k --local-dir models/vitmatte-base-composition-1k
|
||||
hf download ZhengPeng7/BiRefNet --local-dir models/BiRefNet
|
||||
hf download skytnt/anime-seg --local-dir models/anime-seg
|
||||
hf download ZhengPeng7/BiRefNet_HR-matting --local-dir models/BiRefNet_HR-matting # cross-check only
|
||||
```
|
||||
|
||||
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`, ~0.9 GB) 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:
|
||||
|
||||
- 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`.
|
||||
|
||||
### Downloading behind a firewall (CN networks)
|
||||
|
||||
If direct HuggingFace access is blocked, use the mirror **with the local proxy
|
||||
@@ -165,6 +192,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_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 |
|
||||
@@ -270,5 +298,6 @@ service has **no authentication**. To reach it from other hosts:
|
||||
| `FileMetadataError: ... not on huggingface.co` while downloading | hf-mirror + a proxy conflict. Bypass the proxy (`NO_PROXY='*'`) and set `HF_HUB_DISABLE_XET=1` (§5). |
|
||||
| `LocalEntryNotFoundError`, 0 bytes | Xet download path failing; set `HF_HUB_DISABLE_XET=1`. |
|
||||
| `503 service not ready` | Models still loading at startup; wait for "Application startup complete". |
|
||||
| `500 inference failed` right after enabling `BGFILTER_CROSS_CHECK` (offline) | `BiRefNet_HR-matting` not provisioned; download it into the cache/`models/` (§5). |
|
||||
| OOM / killed under load | More than one worker, or `MemoryMax` too low. Keep `--workers 1`. |
|
||||
| `400 could not auto-detect background colour` | Input has no clean flat border; pass `screen_color=#RRGGBB`. |
|
||||
|
||||
Reference in New Issue
Block a user