Restructure docs: README = what/how-to-call, DEPLOY = how-to-run
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:
+54
-78
@@ -54,7 +54,7 @@ RGB 输入
|
||||
|
||||
要自己指定,给一个十六进制先验:
|
||||
|
||||
```powershell
|
||||
```bash
|
||||
... --screen-color "#CFEFFF"
|
||||
```
|
||||
|
||||
@@ -64,26 +64,23 @@ RGB 输入
|
||||
|
||||
## 环境
|
||||
|
||||
使用 conda 环境 `lightML`。
|
||||
任意 Python 3.11–3.13 环境（venv 或 conda）均可：
|
||||
|
||||
```powershell
|
||||
conda activate lightML
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
python -m bgfilter.cli --help
|
||||
```
|
||||
|
||||
若未激活 shell,直接调用该环境的 Python:
|
||||
|
||||
```powershell
|
||||
D:\MiniConda\envs\lightML\python.exe -m bgfilter.cli --help
|
||||
```
|
||||
服务器安装（CPU wheel 版 torch、离线权重、systemd）请直接按 [DEPLOY_ZH.md](DEPLOY_ZH.md)
|
||||
走——同样的依赖，但把生产环境的取舍都写明了。
|
||||
|
||||
## 单张图
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
无需 `--config`——内置默认值与 `configs/default.yaml` 完全一致。只有当你编辑了该文件
|
||||
@@ -97,42 +94,30 @@ fp32;大输入还会默认对 ViTMatte 全局注意力按 query 分块——精
|
||||
|
||||
## 批量
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
## 性能(CPU 参考数据)
|
||||
## 性能
|
||||
|
||||
在 Ryzen 9700X(Zen 5,原生 bf16)、32 GB 内存上实测,cross-check 开启、
|
||||
**`--cross-check-as-seg` 开启**、分块全局注意力开启。(本分支默认关闭复用;不开的话要
|
||||
加上主 BiRefNet@1024 前向——在这些尺寸下每图约 +20 s。)
|
||||
|
||||
| 输入 | 精度 | warm / 每图 | 峰值内存 |
|
||||
|---|---|---|---|
|
||||
| 1024x1536 | fp32 | ~45 s | — |
|
||||
| 1024x1536 | bf16 | ~33 s | — |
|
||||
| 2048x2048 | bf16 | ~53 s | 11.4 GB(批处理)、8.1 GB(单图) |
|
||||
|
||||
内存上限来自 cross-check 的 BiRefNet_HR 前向(无论图多大都固定 `input_size` 2048)——
|
||||
一个全分辨率密集预测网络的真实活跃激活。在分块注意力和 mimalloc 修复之前,同一个
|
||||
2048x2048 bf16 run 峰值 25.2 GB;完全未优化的 fp32 run 估计要 55-60 GB(单是 ViTMatte
|
||||
未分块的 N^2 注意力就 ~39 GB)。无原生 bf16 的 CPU(如 Zen 2)会自动回落 fp32——这类
|
||||
机器上若内存或延迟紧张,优先 `--no-cross-check`。
|
||||
量级参考：快速桌面 CPU（bf16、cross-check 开）约 **33–53 s/图**，现代 GPU 约
|
||||
**1–2 s/图**。全部实测数据——CPU 各 lane、GPU 显存占用、内存上限及相关旋钮——
|
||||
见 [DEPLOY_ZH.md](DEPLOY_ZH.md) §11（容量与性能）。
|
||||
|
||||
## Chroma-alpha 调试模式
|
||||
|
||||
`--matting-method chroma` 跳过 ViTMatte,直接用 chroma 置信度作为 alpha 种子。适合快速
|
||||
检查 chroma 置信度、trimap 和 despill。(不同于上面的仅 Chroma *管线*,后者仍跑 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
|
||||
```
|
||||
|
||||
@@ -209,9 +194,9 @@ python -m uvicorn app:app --host 127.0.0.1 --port 18083 --workers 1
|
||||
| 码 | 何时 |
|
||||
| --- | --- |
|
||||
| `200` | 成功——响应体是 RGBA PNG。 |
|
||||
| `400` | 输入有误:图片无法解码,`screen_color`/`seg_model`/`cross_check`/`background_mode` 非法,或自动探测失败(请传 `screen_color`)。 |
|
||||
| `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)。 |
|
||||
| `413` | 图片超过 `BGFILTER_MAX_IMAGE_PIXELS`(默认约 4 MP),或 `image_url` 响应体超过 `BGFILTER_FETCH_MAX_BYTES`(默认约 25 MB)。 |
|
||||
| `500` | 推理失败。 |
|
||||
| `503` | 服务仍在加载模型(未就绪)。 |
|
||||
|
||||
@@ -237,38 +222,42 @@ 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
|
||||
```
|
||||
|
||||
配置来自 `BGFILTER_CONFIG`(存在时默认 `configs/default.yaml`);`BGFILTER_DEVICE` 同时
|
||||
覆盖 model 和 segmentation 的 device;`BGFILTER_MAX_IMAGE_PIXELS` 限制输入尺寸
|
||||
(默认约 4MP → `413`);`BGFILTER_PRELOAD=1` 启动时预加载默认模型;`BGFILTER_AUTH_TOKEN`
|
||||
控制端点鉴权(见上方"鉴权")。
|
||||
运行时配置(配置文件、device、尺寸上限、预加载、鉴权 token、流水线 worker 数)全部
|
||||
通过 `BGFILTER_*` 环境变量——完整表格见 [DEPLOY_ZH.md](DEPLOY_ZH.md) §6。
|
||||
|
||||
与 CLI 一样,服务**默认开启交叉模型否决**(配置默认:on);其 HR-matting 模型随暖机集
|
||||
一起预加载。用 `BGFILTER_CROSS_CHECK=0` 全服务关闭,或用按请求的 `cross_check` 表单
|
||||
字段任意覆盖;`/healthz` 以 `crossCheck` 报告默认值。若配置里 `cross_check.reuse_as_seg:
|
||||
true`(默认关闭),HR-matting 前向会替代主分割前向而非叠加,那个冗余的主分割器会在启动
|
||||
时跳过。
|
||||
与 CLI 一样,服务**默认开启交叉模型否决**;`/healthz` 以 `crossCheck` 报告生效的默认值,
|
||||
按请求的 `cross_check` 表单字段可任意覆盖(全服务关闭用 `BGFILTER_CROSS_CHECK=0`)。
|
||||
`cross_check.reuse_as_seg`(仅配置文件可设,默认关——见上方"管线")没有请求级开关;
|
||||
改它意味着改配置并重启服务。
|
||||
|
||||
## 质量检查
|
||||
|
||||
质量检查器在半透明边缘像素上度量 alpha 有效性和边缘溢色。
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
跑内置样本冒烟检查:
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
@@ -278,22 +267,9 @@ D:\MiniConda\envs\lightML\python.exe scripts\smoke_samples.py `
|
||||
- ViTMatte 和分割权重在首次使用时从 Hugging Face 加载。`anime-seg`
|
||||
(`skytnt/anime-seg`)是普通 ONNX 下载;`birefnet`(`ZhengPeng7/BiRefNet`)自带
|
||||
自定义建模代码,故需 `trust_remote_code=True` 外加 `timm` / `einops` / `kornia`。
|
||||
- 防火墙后下载权重——可靠组合是 `hf-mirror.com` 镜像 **+ 绕过本地代理** **+ 禁用 Xet**:
|
||||
```powershell
|
||||
$env:HF_ENDPOINT = "https://hf-mirror.com" # 国内镜像
|
||||
$env:NO_PROXY = "*" # 绕过代理;镜像是直连
|
||||
$env:HF_HUB_DISABLE_XET = "1" # 这些仓库是 Xet 后端;强制走经典 HTTP
|
||||
```
|
||||
规避两个坑:(1) 镜像 + 海外代理会让镜像的 `resolve` 弹回 `huggingface.co`,新版
|
||||
`huggingface_hub` 会以 `FileMetadataError` 拒绝;(2) 装了 `hf-xet` 时 Xet 下载路径会
|
||||
立即失败。权重缓存好后,用 `HF_HUB_OFFLINE=1 TRANSFORMERS_OFFLINE=1` 离线运行
|
||||
(生产环境即如此)。
|
||||
- 把权重打包进项目——不走 HF 缓存,而是把每个模型放进 `models/` 下、以仓库 basename
|
||||
命名的纯文件夹:`models/vitmatte-base-composition-1k`、`models/BiRefNet`、
|
||||
`models/anime-seg`、`models/BiRefNet_HR-matting`(交叉否决第二意见,默认开启)。加载器
|
||||
优先匹配本地文件夹,缺失时回落到 HF 仓库 id / 缓存,故为可选。用例如
|
||||
`hf download ZhengPeng7/BiRefNet --local-dir models/BiRefNet` 填充。用
|
||||
`BGFILTER_WEIGHTS_DIR` 改基目录。`models/` 已被 gitignore。
|
||||
- **权重准备**——离线 HF 缓存、`models/` 纯文件夹(`BGFILTER_WEIGHTS_DIR`)、一键下载
|
||||
脚本 `scripts/fetch_weights.py`、以及国内网络的镜像 workaround——见
|
||||
[DEPLOY_ZH.md](DEPLOY_ZH.md) §5。
|
||||
- 前景颜色估计用 pymatting 的 `estimate_foreground_ml`,在 de-spill 前把干净前景色
|
||||
传播进半透明边缘。设 `foreground.method: unmix` 回落到旧的启发式方法。
|
||||
- `docs/green_screen_matting_workflow.md` 是最初的第一阶段绿幕规格;本 README 反映当前
|
||||
|
||||
Reference in New Issue
Block a user