人像抠图 lemonhall/birefnet-cutout-skill

portrait-cutout

把人物从照片里抠出来。附带一份实测出来的能力边界 —— 哪一代模型、什么分辨率、什么显卡跑得动什么。

起因：想把一张 2970×4096 的真人照抠成透明背景做贴图。试了三代模型、两条流水线，顺手量出了「发丝到底能保住多少」这件平时只能靠眼睛吵的事。

30 秒上手

① 快：GPU + rembg + 2024 的人像模型（秒级，日常够用）
uv run --python 3.13 --with rembg --with pillow
--with "onnxruntime-gpu==1.22.0" --with "nvidia-cudnn-cu12<9.10" --with nvidia-cublas-cu12
python scripts/cutout_gpu.py input.jpg out.webp

② 发丝：官方 BiRefNet_HR-matting @2048（软 alpha，发丝在） $env:CUTOUT_FORCE_CPU='1' # 8GB 显卡跑不了 2048，见下
uv run --python 3.13 --with pillow --with numpy
--with "onnxruntime-gpu==1.22.0" --with "nvidia-cudnn-cu12<9.10" --with nvidia-cublas-cu12
python scripts/cutout_hr.py input.jpg out.webp

第二次起依赖都在缓存里，秒开。

三条最值钱的结论

一、别抄 rembg 的默认值。 它默认 u2net —— 2020 年的模型。抠人物要用 birefnet-portrait（2024）。而且注意 u2net_human_seg 虽然名字像"人像特化"，它跟 u2net 同龄，换了等于没换。

二、发丝糊的根因是分辨率，不是模型。 rembg 把输入固定压到 1024×1024 （源码里写死的），1200 万像素压下去再放大 —— 发丝在那一步就没了。官方的正解是换 2048 训练的 BiRefNet_HR-matting，它输出连续软 alpha。切块没用（那个 ONNX 输入形状写死 2048）。

三、8GB 显卡装不下 2048。 某一层要申请单个 3.28GB 的缓冲，三次实测同样 OOM，加显存策略开关也没用。所以要么走 CPU（95 秒/张），要么换 lite 模型，要么升显卡。

怎么客观量"发丝保住了多少"

发丝在数学上就是 alpha 介于 0 和 255 之间的像素。量它：

| 流水线 | 半透明档 |
| u2net（1024） | ≈ 0 ✗ 硬边 |
| 官方 HR-matting（2048） | 24.0% ✓ 整幅 2970×4096 全留住 |

比"你觉得好不好看"可靠得多，也不会吵。

装到你的智能体里

这个仓库的 SKILL.md 是通用格式，DSH 和 Codex 都能吃：

- DSH：宿主插件里注册一下（ctx.skills.register({ content: readFileSync('SKILL.md') })），或者直接把 SKILL.md 的内容粘进你的 AGENTS.md。
- Codex：把 SKILL.md 里「一、先结论」到「五、8GB 显卡跑不了 2048」这几节粘进 AGENTS.md；脚本按上面的命令直接用。

环境要点（踩过的坑）

Python 钉 3.13（uv 默认 3.14，很多包没 cp314 轮子）
pip 源 清华镜像 + NO_PROXY 直连（同一批包：代理 40 分钟 → 镜像 17 秒）
onnxruntime-gpu 1.22.0（对应 CUDA 12；1.30 要 CUDA 13） cuDNN <9.10（9.27 对 Turing 太新，会 HEURISTIC_QUERY_FAILED） DLL 挂载 必须遍历 sys.path（uv 用 archive 覆盖层，getsitepackages 看不到）验证 nvidia-smi 抓 python 进程 + 输出里没有 "Falling back to CPU" （onnxruntime 缺 DLL 时是静默回退，不验就不知道跑在哪）模型下载 ghfast.top 加速 + curl -C -（972MB 实测 29 秒）

目录

SKILL.md 方法论（给智能体看的） scripts/cutout_gpu.py GPU 快路线：rembg + birefnet-portrait scripts/cutout_hr.py 官方 2048 HR-matting（CPU 可跑通）

License

MIT