Default reuse-as-seg OFF; default expandable_segments on Linux/WSL

Two default flips for server-edition:

1. cross_check.reuse_as_seg now defaults to false (settings + default.yaml + CLI help): the dedicated segmenter keeps its own forward and the cross-check veto stays an independent second signal. The reuse remains available via --cross-check-as-seg / config; measured cost of off vs on: ~20 s/image on CPU, +0.1-0.25 s and +0.9-1.3 GB VRAM on GPU (13.3 vs 12.0 GB reserved under expandable segments -- still fits a 16 GB card).

2. bgfilter/__init__.py defaults PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True on non-Windows platforms, before torch loads (setdefault: an explicit env value wins; native Windows is excluded because torch warns and ignores it there). Measured: reserved 15.3 -> 12.0 GB and ~10% faster on the RTX 5070 Ti; no effect on CPU-only runs.

README/DEPLOY(_ZH) synced: reuse documented as opt-in, GPU profile numbers updated for both reuse states, perf table labeled with the config it was measured under.

Verified: defaults resolve off/set as intended on Windows and WSL; explicit PYTORCH_CUDA_ALLOC_CONF override wins.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

bgfilter/__init__.py

@@ -1,6 +1,7 @@
 """Flat-background character matting pipeline."""
 
 import os
+import sys
 
 # Windows PyTorch allocates CPU tensors through a bundled mimalloc whose lazy
 # purge keeps ~10 GB of already-freed forward activations committed after a
@@ -11,4 +12,13 @@ import os
 # bgfilter.memtune.release_freed_memory(); see DEPLOY for jemalloc as an alt.
 os.environ.setdefault("MIMALLOC_PURGE_DELAY", "0")
 
+# Expandable segments defuse the CUDA caching allocator's fragmentation: the
+# full bf16 pipeline's reserved VRAM drops 15.3 -> 12.0 GB on a 16 GB card and
+# runs ~10% faster (measured, RTX 5070 Ti). Read at CUDA-allocator init, so it
+# must be set before torch loads; a no-op for CPU-only runs. Native Windows
+# does not support it (torch warns and ignores), so it is only defaulted where
+# it works (Linux/WSL2); setdefault keeps any explicit user setting in charge.
+if not sys.platform.startswith("win"):
+    os.environ.setdefault("PYTORCH_CUDA_ALLOC_CONF", "expandable_segments:True")
+
 __version__ = "0.1.0"

bgfilter/cli.py

@@ -32,7 +32,7 @@ def main(
     fg_safe_radius_ratio: float | None = typer.Option(None, "--fg-safe-radius-ratio", min=0.0),
     despill: bool | None = typer.Option(None, "--despill/--no-despill"),
     cross_check: bool | None = typer.Option(None, "--cross-check/--no-cross-check", help="Second-opinion veto of background-hued residue between hair strands (default: on; costs one extra model inference)"),
-    cross_check_as_seg: bool | None = typer.Option(None, "--cross-check-as-seg/--no-cross-check-as-seg", help="Reuse the cross-check forward as the segmentation mask, skipping the primary seg model (default: on; saves ~20s on CPU; needs cross-check on)"),
+    cross_check_as_seg: bool | None = typer.Option(None, "--cross-check-as-seg/--no-cross-check-as-seg", help="Reuse the cross-check forward as the segmentation mask, skipping the primary seg model (default: off; saves ~20s on CPU; needs cross-check on)"),
     trimap_mode: str | None = typer.Option(None, "--trimap-mode", help="Trimap mode (segmentation pipeline): directional | seg | directional-hard-bg"),
     seg_backend: str | None = typer.Option(None, "--seg-backend", help="Segmentation backend: birefnet (default) | anime-seg"),
 ) -> None:

bgfilter/settings.py

@@ -76,12 +76,13 @@ class CrossCheckSettings:
     input_size: int = 2048
     # Reuse the cross-check forward as the segmentation mask: one HR-matting
     # inference serves both trimap topology and the second opinion, skipping the
-    # primary seg model entirely (saves its load + forward). Pilot-validated on
-    # TestImage3/FixImage1: trimap 99.8% identical, no structural change. Only
-    # applies to the birefnet segmentation backend (a same-family swap); with
-    # anime-seg the chosen segmenter keeps its own forward and the cross-check
-    # runs independently. Needs cross_check and segmentation both enabled.
-    reuse_as_seg: bool = True
+    # primary seg model entirely (saves its load + forward; measured ~20 s/image
+    # on CPU, ~0.9-1.3 GB VRAM on GPU). Pilot-validated on TestImage3/FixImage1:
+    # trimap 99.8% identical. Default OFF on server-edition: the dedicated
+    # segmenter keeps its own forward and the veto stays an independent signal;
+    # opt in with --cross-check-as-seg. Only applies to the birefnet backend
+    # (a same-family swap); needs cross_check and segmentation both enabled.
+    reuse_as_seg: bool = False
     # Compute precision of the cross-check forward: "fp32" or "bf16" (autocast;
     # needs bf16-capable hardware, else falls back to fp32 with a warning).
     precision: str = "fp32"