BGfilter/README_ZH.md

BgFilter

English: README.md

面向"纯色背景 AI 生成图"的离线人物抠图。背景色会从图像边框自动探测(绿色、 淡彩、任意纯色);也可用 --screen-color 显式指定。

RGB 输入
  -> chroma 背景置信度(按自动探测或指定的颜色打分)
  -> [可选] 语义分割 mask
  -> trimap -> ViTMatte -> alpha 清理
  -> 交叉模型否决(对背景色调残留做第二意见)
  -> pymatting 前景估计 -> despill 去溢色 -> RGBA PNG -> QA 预览

管线

两条管线,由配置里的 segmentation.enabled 选择:

• 仅 Chroma(enabled: false)—— Chroma + ViTMatte,无分割模型。最轻/最快; 完全靠颜色键决定拓扑。
• 单分割器(enabled: true,默认)—— 一个分割模型定 trimap 拓扑(镂空、发丝), ViTMatte 再细化软边。后端可切换:birefnet(默认,通用显著目标——文字、logo、 照片;需 trust_remote_code)或 anime-seg(ONNX,专为动漫角色调优)。运行时用 --seg-backend anime-seg 切换(会同时选好对应权重)。

两条管线都共用 pymatting 前景估计和一次颜色 de-spill。没有染绿修复 / recolour 层——源图干净时它没必要,已移除。

两条管线默认都跑交叉模型否决:第二个、无需 trimap 的抠图模型 (ZhengPeng7/BiRefNet_HR-matting)只能降低 alpha,且只作用于主结果自信、 但偏背景色调的亮像素——用来清掉卡在发丝间、被 chroma、分割器和 ViTMatte 都误判为 前景的偏色背景残留。代价是多下一个模型(~0.9 GB)+ 每图一次额外推理;用 --no-cross-check 关闭(见 cross_check 配置段,分析见 docs/hair_gap_artifacts.md)。

开启交叉否决时,那趟 HR-matting 前向可以选择性地兼作分割 mask (--cross-check-as-seg),从而完全跳过主分割模型(少加载一个模型,CPU 上每图约快 20 s,GPU 上省约 1 GB 显存)。已试点验证(TestImage3 / FixImage1):trimap 99.8% 一致, 手指、发丝、细线无结构性变化。默认关闭:专用分割器保留自己的前向,否决作为独立 的第二信号。该复用是同族替换,故仅对 birefnet 后端生效:用 --seg-backend anime-seg 时动漫分割器始终保留自己的前向。

分割 trimap 默认走 directional 模式(chroma + seg + 色调方向切分:保留白衬衫这类 背景色系的衣物,同时丢弃卡在发丝间的偏背景色残留如蓝色)。可切换 --trimap-mode seg(仅拓扑,无色调切分)或 directional-hard-bg(激进——硬删偏背景 色像素;可能吃掉冷色/阴影下的白布)。

背景色

默认(screen_color: null)背景色从图像边框自动探测:边框条带的主导纯色成为键色。 若边框不是单一干净纯色——渐变、纹理、或主体占满画面——探测会报错;此时请显式传 --screen-color。

要自己指定,给一个十六进制先验:

... --screen-color "#CFEFFF"

或在配置里写 screen_color: "#CFEFFF"。无论哪种,chroma 键都按到该颜色的感知 (Lab/RGB)距离给像素打分,de-spill 沿该颜色方向压掉色度。(显式给的 hex 会用附近边框 像素做微调;自动探测的颜色直接使用。)

环境

任意 Python 3.11–3.13 环境（venv 或 conda）均可：

pip install -r requirements.txt
python -m bgfilter.cli --help

服务器安装（CPU wheel 版 torch、离线权重、systemd）请直接按 DEPLOY_ZH.md 走——同样的依赖，但把生产环境的取舍都写明了。

单张图

python -m bgfilter.cli \
  --input Samples/TestImage.png \
  --output Outputs/TestImage_rgba.png \
  --debug-dir Outputs/TestImage_debug

无需 --config——内置默认值与 configs/default.yaml 完全一致。只有当你编辑了该文件 去调细节参数时,才需要 --config configs\default.yaml。运行时选择留在命令行: --device(默认 CPU;GPU 用 --device cuda)、--precision(默认 fp32;bf16 给三个模型加速、并把抠图模型的激活显存减半,alpha 视觉上一致——需 bf16 硬件,否则回落 fp32;大输入还会默认对 ViTMatte 全局注意力按 query 分块——精确、逐比特相同,把 2048x2048 的内存尖峰从 ~19 GB 压到 ~4 GB,见 model.attn_query_chunk)、--seg-backend (默认 birefnet;动漫角色用 anime-seg)、--screen-color(默认:自动探测纯背景)、 以及 --trimap-mode。

批量

python -m bgfilter.cli \
  --input-dir Samples \
  --output-dir Outputs \
  --debug-dir Outputs/debug

性能

量级参考：快速桌面 CPU（bf16、cross-check 开）约 33–53 s/图，现代 GPU 约 1–2 s/图。全部实测数据——CPU 各 lane、GPU 显存占用、内存上限及相关旋钮—— 见 DEPLOY_ZH.md §11（容量与性能）。

Chroma-alpha 调试模式

--matting-method chroma 跳过 ViTMatte,直接用 chroma 置信度作为 alpha 种子。适合快速 检查 chroma 置信度、trimap 和 despill。(不同于上面的仅 Chroma 管线,后者仍跑 ViTMatte。)

python -m bgfilter.cli \
  --input-dir Samples \
  --output-dir Outputs/chroma \
  --debug-dir Outputs/chroma_debug \
  --matting-method chroma \
  --device cpu

输出

每处理一张图,CLI 写一张 RGBA PNG 和可选的调试文件:

bg_confidence.png
trimap.png
seg_mask.png          # 仅分割管线
alpha.png
foreground_rgb.png    # 去溢色后的前景颜色
color_mask.png        # 逐像素 despill 权重
preview_black.png
preview_white.png
preview_gray.png
preview_red.png
preview_blue.png
qa_grid.png
metadata.json

HTTP 服务

一个 HTTP 封装(app.py + bgfilter/service.py)把管线暴露为常驻 FastAPI 服务。模型 只加载一次、跨请求复用。部署到 Linux 服务器(依赖、权重、systemd、离线模式、鉴权)见 DEPLOY_ZH.md。

python -m uvicorn app:app --host 127.0.0.1 --port 18083 --workers 1

单 worker 运行(--workers 1)—— 每个 worker 各自加载一份模型。

端点

• GET /healthz —— 存活 + 配置 JSON,例如 {"ok":true,"service":"bgfilter","version":"0.1.0","defaultSegModel":"birefnet","device":"cpu","crossCheck":true}。 始终免鉴权。
• POST /remove-background —— 入参 multipart/form-data,返回 image/png(RGBA)。

鉴权

可选、按需开启,由环境变量 BGFILTER_AUTH_TOKEN 控制。设置后,/remove-background 要求 header X-Genarrative-Image-Token: <token>(常量时间比较);缺失或错误返回 401。不设时端点开放(预期由前置代理鉴权)。/healthz 始终开放。见 DEPLOY_ZH.md §10。

请求字段(POST /remove-background,multipart/form-data)

字段	必填	取值	含义
file	file/image_url 二选一	图片文件	以上传方式提供源图(字段名固定为 file)。
image_url	file/image_url 二选一	http(s)://…	以 URL 提供源图,服务端自行 fetch(受大小/超时限制,跟随 ≤3 跳重定向)。file 与 image_url 必须恰好提供一个。无 SSRF 过滤:端点信任已鉴权的调用方,请保持鉴权开启且调用方可信。
background_mode	否	flat(默认)/ complex	flat = 纯色背景(走色键管线)。complex = 非纯色/实景背景:无色键,完全由分割器驱动抠图;此模式下 screen_color 被忽略,发丝细节通常弱于纯色模式。
screen_color	否	#RRGGBB,或留空/auto	背景色先验;留空则从边框自动探测。background_mode=complex 时忽略。
seg_model	否	birefnet(默认)/ anime-seg	分割后端。
cross_check	否	1/0(也接受 true/false/yes/no/on/off)	按请求覆盖交叉否决;留空在 flat 模式 = 服务端默认,但在 complex 模式默认关闭(传 on 启用其无色相门控)。

响应头(200 时)

头	示例	含义
X-BGFilter-Elapsed-Ms	2372	服务端处理耗时(ms)。
X-BGFilter-Seg-Model	birefnet	实际使用的分割器。
X-BGFilter-Screen-Color	#CFEFFF / auto	实际使用的背景色。
X-BGFilter-Cross-Check	on / off	本次实际的 cross-check 状态。
X-BGFilter-Background-Mode	flat / complex	本次实际的背景模式。
X-Request-ID	42efe4e0d76f4b83	关联 id（你若传入 X-Request-ID 则回显,否则自动生成）。报障时报这个 id 即可对上服务端日志。每个响应都返回,含错误响应。

状态码

码	何时
200	成功——响应体是 RGBA PNG。
400	输入有误:图片无法解码,file/image_url 不是恰好其一,image_url 非法/fetch 失败,screen_color/seg_model/cross_check/background_mode 非法,或自动探测失败(请传 screen_color)。
401	鉴权已开且 token 缺失或错误。
413	图片超过 BGFILTER_MAX_IMAGE_PIXELS(默认约 4 MP),或 image_url 响应体超过 BGFILTER_FETCH_MAX_BYTES(默认约 25 MB)。
500	推理失败。
503	服务仍在加载模型(未就绪)。

示例

# 默认(birefnet + 自动背景色);若服务要求鉴权则加上 auth header
curl -sS -F "file=@input.png" \
  -H "X-Genarrative-Image-Token: <token>" \
  http://127.0.0.1:18083/remove-background -o output.png

# 显式背景色 + 动漫分割器,本次关闭 cross-check
curl -sS \
  -F "file=@input.png" \
  -F "screen_color=#CFEFFF" \
  -F "seg_model=anime-seg" \
  -F "cross_check=off" \
  http://127.0.0.1:18083/remove-background -o output.png

# 非纯色/实景背景(无色键);此模式 cross-check 默认关闭,
# 需要时加 cross_check=on 启用无色相残留否决
curl -sS \
  -F "file=@scene.jpg" \
  -F "background_mode=complex" \
  http://127.0.0.1:18083/remove-background -o output.png

# 用 URL 代替上传(服务端自行 fetch;image_url 与 file 二选一,不可同时给)
curl -sS \
  -F "image_url=https://example.com/input.png" \
  -F "screen_color=#CFEFFF" \
  -H "X-Genarrative-Image-Token: <token>" \
  http://127.0.0.1:18083/remove-background -o output.png

运行时配置(配置文件、device、尺寸上限、预加载、鉴权 token、流水线 worker 数)全部 通过 BGFILTER_* 环境变量——完整表格见 DEPLOY_ZH.md §6。

与 CLI 一样,服务默认开启交叉模型否决;/healthz 以 crossCheck 报告生效的默认值, 按请求的 cross_check 表单字段可任意覆盖(全服务关闭用 BGFILTER_CROSS_CHECK=0)。 cross_check.reuse_as_seg(仅配置文件可设,默认关——见上方"管线")没有请求级开关; 改它意味着改配置并重启服务。

质量检查

质量检查器在半透明边缘像素上度量 alpha 有效性和边缘溢色。

python -m bgfilter.quality_cli \
  Outputs/TestImage_rgba.png \
  --max-edge-green-excess-p95 0.30

跑内置样本冒烟检查:

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

备注

• Samples/ 和 Outputs/ 被 Git 忽略。
• ViTMatte 和分割权重在首次使用时从 Hugging Face 加载。anime-seg (skytnt/anime-seg)是普通 ONNX 下载;birefnet(ZhengPeng7/BiRefNet)自带 自定义建模代码,故需 trust_remote_code=True 外加 timm / einops / kornia。
• 权重准备——离线 HF 缓存、models/ 纯文件夹(BGFILTER_WEIGHTS_DIR)、一键下载 脚本 scripts/fetch_weights.py、以及国内网络的镜像 workaround——见 DEPLOY_ZH.md §5。
• 前景颜色估计用 pymatting 的 estimate_foreground_ml,在 de-spill 前把干净前景色 传播进半透明边缘。设 foreground.method: unmix 回落到旧的启发式方法。
• docs/green_screen_matting_workflow.md 是最初的第一阶段绿幕规格;本 README 反映当前 的、泛化后的架构。