Communitygithub.com

OpenGHz/rembg-bg-removal

Agent 스킬: CUDA 버전과 일치하는 격리된 환경에서 rembg를 사용해 이미지 배경을 제거합니다. 단일 이미지 또는 전체 폴더에 대해 투명 PNG 컷아웃을 생성합니다.

rembg-bg-removal란 무엇인가요?

이 스킬은 rembg를 활용한 이미지 배경 제거 작업을 간소화합니다. 일반적인 '배경 제거'는 간단하지만, 사용자의 머신에 설치된 CUDA 버전과 호환되는 GPU 백엔드를 갖춘 독립적인 실행 환경을 구축하는 것이 실제로 까다로운 부분입니다. 이 스킬은 이러한 설정을 한 번의 스크립트로 자동화하고, 이후에는 간단한 래퍼(wrapper)로 실행할 수 있게 해줍니다. conda 또는 venv를 통해 완전히 격리된 환경을 생성하며, nvidia-smi로 CUDA 버전을 감지하여 onnxruntime-gpu의 적절한 버전을 설치합니다. CUDA 12.x와 13.x 간의 호환성 문제를 해결하고, LD_LIBRARY_PATH를 자동으로 설정하며, 모델 파일을 사전 다운로드하여 안정성을 높입니다. 사용자는 단일 파일이나 폴더를 인자로 전달하기만 하면 되며, 출력 경로를 생략하면 자동으로 파일명 뒤에 '_rembg' 접미사를 붙여 결과물을 저장합니다. `birefnet-general`, `u2net`, `isnet-anime` 등 여러 모델을 지원하고, `-ppm` 및 알파 매팅(alpha matting)과 같은 추가 플래그를 통해 품질을 세밀하게 조정할 수 있습니다. 이 스킬은 Claude Code, Cursor, Codex와 같은 AI 에이전트 환경에서 원활하게 사용할 수 있도록 설계되었습니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add OpenGHz/rembg-bg-removal

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

rembg 배경 제거

rembg를 사용하여 이미지 배경을 제거합니다. 어려운 부분은 제거 자체가 아니라, 머신의 CUDA 버전과 일치하는 GPU 백엔드를 갖춘 격리된 작업 환경을 구축하는 것입니다. 이 스킬은 해당 설정을 한 번만 실행하는 스크립트로 묶고, 이후에는 간단한 실행 래퍼(wrapper)를 제공합니다.

워크플로우

  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 <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 휠을 설치합니다. 이는 중요합니다: 최신 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 작동) 사용자가 직접 export할 필요가 없습니다.
  • 모델 사전 다운로드. birefnet-general(~928MB) 및 u2net을 wget -c 재개 기능과 md5 검증으로 다운로드합니다. 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부터 시작한 후 더 강력한 모델, 그다음 -a 알파 매팅과 -ae 침식 튜닝).

문제 해결

  • No onnxruntime backend found — GPU 휠 임포트 실패(보통 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에 미리 다운로드하세요(설치기가 이 작업을 수행합니다).

관련 스킬