Communitygithub.com

OpenGHz/rembg-bg-removal

AI 代理技能:在隔離且匹配 CUDA 的環境中,使用 rembg 移除圖片背景 — 支援單張圖片或整個資料夾,輸出透明 PNG 圖檔。

rembg-bg-removal 是什麼?

這個技能封裝了 rembg (https://github.com/danielgatis/rembg) 的背景移除功能,解決了最棘手的部分:建立一個隔離、可運作的 GPU 後端環境,並自動匹配機器的 CUDA 版本。它透過一個一次性設定腳本建立專屬環境(conda 或 venv),然後提供一個輕量的執行包裝器。支援單張圖片或整個資料夾的批次處理,可自動產生輸出檔名(例如 photo.jpg → photo_rembg.png)。主要透過 CLI 操作,可在 Claude Code、Cursor 或任何支援 bash 腳本的 AI 代理平台上使用。特色包括自動偵測 CUDA 版本並安裝對應的 onnxruntime-gpu、下載模型時支援中斷續傳與 MD5 驗證,以及提供多種模型選擇(預設為 birefnet-general)與品質調校選項。

相容平台~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 EXISTS
    # venv 備用方案:
    test -x ~/.venvs/rembg/bin/rembg && echo EXISTS
    

    如果環境不存在,請執行設定腳本(見下文)。如果存在,則直接跳到執行步驟。

  2. 執行背景移除 透過包裝器(自動偵測檔案或資料夾):

    bash <skill>/scripts/run_rembg.sh <輸入> <輸出> [-m 模型] [旗標]
    
  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 wheels。這很重要:最新的 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 hook,而執行包裝器也會設定它(以便 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 erode 調校的 -a alpha matting)。

疑難排解

  • 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] extra 的情況下安裝。setup_env.sh 會安裝 rembg[cpu,cli];請重新執行它。
  • 模型下載停滯 / SSL EOF — 設定一個可用的 PROXY,或使用 wget -c 預先下載到 ~/.u2net/<name>.onnx(安裝程式會執行此操作)。

相關技能