Communitygithub.com

OpenGHz/rembg-bg-removal

Agent 技能:在隔离的、与 CUDA 匹配的环境中,使用 rembg 移除图像背景——为单张图片或整个文件夹生成透明 PNG 剪影。

rembg-bg-removal 是什么?

该技能解决了在 GPU 环境下部署 rembg 进行背景移除的核心痛点:环境隔离与 CUDA 版本匹配。技能通过一个专有的安装脚本自动检测系统 CUDA 版本,为 onnxruntime-gpu 安装精确匹配的依赖(例如 CUDA 12.x 使用 onnxruntime-gpu 1.22.0),避免因版本不兼容导致的运行时错误。它支持 conda 和 venv 两种虚拟环境,并自动配置 LD_LIBRARY_PATH 以确保 GPU 后端正常加载。运行时,用户可通过一个统一的封装脚本处理单张图片或整个文件夹,输出路径可选(默认在输入旁添加 `_rembg` 后缀)。技能还预下载了 birefnet-general 和 u2net 模型,并支持通过环境变量覆盖模型选择、代理设置、环境重建等。适用于 Cursor、Codex 等支持 shell 命令执行的 AI 代理平台,帮助开发者快速、可靠地集成背景移除功能。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add OpenGHz/rembg-bg-removal

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

rembg 背景移除

使用 rembg 移除图像背景。 难点不在于移除本身,而在于搭建一个可工作的、隔离的环境,以及一个与机器 CUDA 版本匹配的 GPU 后端。本技能将这一设置过程打包成一次性脚本,然后提供一个轻量级的运行封装。

工作流

  1. 确保环境已存在。 在运行任何操作之前检查环境:

    # conda(当 conda 存在时为默认方式):
    conda env list | grep -q '\brembg\b' && echo 已存在
    # venv 备选方案:
    test -x ~/.venvs/rembg/bin/rembg && echo 已存在
    

    如果环境不存在,请运行设置脚本(见下文)。如果已存在,则直接进入运行步骤。

  2. 通过封装进行背景移除(自动检测文件或文件夹):

    bash <skill>/scripts/run_rembg.sh <input> <output> [-m MODEL] [flags]
    
  3. 报告输出位置和使用的模型。如果用户关心质量,请提示他们可用的调优选项。

设置(仅首次运行)

运行捆绑的安装程序。它会创建一个专用环境,并且只在该环境内安装——绝不会修改用户的当前活动环境或基础环境。

bash <skill>/scripts/setup_env.sh

它的作用及原因:

  • 隔离。 创建一个名为 rembg 的专用 conda 环境(如果 conda 不可用,则在 ~/.venvs/rembg 创建 venv)。它会计算显式的解释器路径,并使用 <that-python> -m pip 进行安装,因此不会影响任何当前激活的环境。
  • 与 CUDA 匹配的后端。 从 nvidia-smi 读取驱动程序的 CUDA 版本。对于 CUDA 12.x,它会安装 onnxruntime-gpu==1.22.0 以及匹配的 nvidia-cudnn-cu12 / cublas / cuda-runtime wheel 包。这一点很重要:最新的 onnxruntime-gpu(1.23+)是为 CUDA 13 构建的,在 CUDA-12 的机器上导入时会失败,出现 libcudart.so.13: cannot open shared object file 错误。对于 CUDA ≥13,它使用最新的 GPU 构建版本;如果没有 GPU,则使用 CPU 版本。
  • 加载器路径。 onnxruntime-gpu 需要 pip 安装的 NVIDIA 库位于 LD_LIBRARY_PATH 中。安装程序会添加一个 conda activate.d 钩子,运行封装也会设置它(以便 venv 也能工作),因此用户无需手动导出任何环境变量。
  • 模型预下载。 使用 wget -c 断点续传和 md5 验证下载 birefnet-general(约 928MB)和 u2net 模型,因为 GitHub 发布版的链接经常中断。

有用的覆盖变量(环境变量):ENV_TYPE=venv、ENV_PATH=~/.venvs/rembg、FORCE_CPU=1、PROXY=http://127.0.0.1:7890(通过代理路由下载;默认空)、RECREATE=1(从零重建)、MODELS="birefnet-general isnet-anime"。

运行

封装脚本对单文件和处理文件夹的方式相同——传入文件则得到文件,传入目录则得到剪影目录。输出路径是可选的:省略时,封装会在输入旁写入带有 _rembg 后缀的文件(photo.jpg → photo_rembg.png、icons/ → icons_rembg/),因此您无需额外指定。

# 单张图片,自动输出 -> photo_rembg.png
bash <skill>/scripts/run_rembg.sh photo.jpg

# 显式输出
bash <skill>/scripts/run_rembg.sh photo.jpg photo_cutout.png

# 整个文件夹,自动输出 -> icons_rembg/
bash <skill>/scripts/run_rembg.sh ./icons -m birefnet-general -ppm

# 选择模型 / 传递 rembg 参数(参数可直接跟在输入后)
MODEL=isnet-anime bash <skill>/scripts/run_rembg.sh char.png -ppm

封装会首先取消任何 socks:// 代理(它会破坏 rembg 的 gradio 导入)。默认不使用代理;设置 PROXY 可通过 http 代理路由按需的模型下载。

选择模型与调整质量

默认为 birefnet-general(最佳通用边缘)。如果用户对边缘不满意、提到毛发/软边缘、动漫、人物肖像,或想要纯色背景,请阅读 references/models_and_flags.md 获取完整的模型表和参数调优顺序(从 -ppm 开始,然后尝试更强的模型,接着是带有 -ae 腐蚀参数调优的 -a alpha 抠图)。

故障排除

  • No onnxruntime backend found —— GPU wheel 导入失败(通常是 CUDA 主要版本不匹配)。重新运行 setup_env.sh;它会选择匹配的后端。
  • libcudart.so.13: cannot open shared object file —— onnxruntime-gpu 是为 CUDA 13 构建的,但机器上运行的是 CUDA 12。这正是 setup_env.sh 中版本锁定要解决的问题。
  • Unknown scheme for proxy URL 'socks://...' —— socks:// 类型的 all_proxy 会破坏 gradio/httpx。运行封装会取消它;如果手动运行 rembg,请先执行 unset all_proxy ALL_PROXY。
  • The CLI dependencies are not installed —— rembg 未安装 [cli] 附加组件。setup_env.sh 安装的是 rembg[cpu,cli];请重新运行它。
  • 模型下载卡住 / SSL EOF —— 设置一个可用的 PROXY,或者使用 wget -c 预先下载到 ~/.u2net/<name>.onnx(安装程序已执行此操作)。

相关技能