설치

Diffusers는 Python 3.10 이상을 요구하며 PyTorch 2.6+로 테스트되었습니다. 시스템 및 설정에 따라 PyTorch를 설치하세요.

독립된 프로젝트 관리를 용이하게 하고 의존성 간 호환성 문제를 방지하기 위해 가상 환경을 생성하세요. Rust 기반의 Python 패키지 및 프로젝트 매니저인 uv를 사용하여 가상 환경을 생성하고 Diffusers를 설치합니다.

uv venv my-env
source my-env/bin/activate

다음 방법 중 하나로 Diffusers를 설치하세요.

pip

NVIDIA Spark (ARM64)

conda

source

필요할 때 extras와 함께 설치하세요. diffusers["torch"]는 PyTorch와 Accelerate를 가져옵니다. 기타 extras는 양자화 백엔드, 학습, 문서화를 지원합니다. 전체 목록은 setup.py를 참조하세요.

디바이스

Diffusers는 PyTorch가 지원하는 모든 가속기에서 실행됩니다. 문서 전반의 예제는 가장 일반적인 설정인 "cuda"를 사용하지만, CUDA에 특화된 내용은 없습니다. Intel GPU의 경우 "xpu", Apple silicon의 경우 "mps", 또는 "cpu"처럼 하드웨어에 맞는 디바이스 문자열로 교체하면 됩니다.

device = "cuda"  # or "mps", "xpu", "cpu"
pipeline.to(device)

하드코딩 대신 런타임에 장치를 선택하려면 torch.accelerator를 사용하세요.

import torch

device = torch.accelerator.current_accelerator().type if torch.accelerator.is_available() else "cpu"

수정 가능한 설치

개발 워크플로우를 사용하거나 소스 코드의 main 버전을 사용하는 경우 편집 가능한 설치(editable install)를 권장합니다. 클론된 저장소와 Python 라이브러리 경로 사이에 특수 링크가 생성됩니다. 이를 통해 모든 변경 사항 이후에 패키지를 다시 설치할 필요가 없습니다.

다음 명령을 사용하여 저장소를 클론하고 Diffusers를 설치합니다.

git clone https://github.com/huggingface/diffusers.git
cd diffusers
uv pip install -e ".[torch]"

editable install로 라이브러리를 계속 사용하려면 diffusers 폴더를 유지해야 합니다.

… 명령어로 클론한 저장소를 Diffusers의 최신 버전으로 업데이트하세요.

cd ~/diffusers/
git pull

캐시

모델 가중치와 파일은 Hub에서 캐시로 다운로드되며, 이 캐시는 일반적으로 홈 디렉터리에 위치합니다. HF_HOME 또는 HF_HUB_CACHE 환경 변수를 변경하거나 from_pretrained()와 같은 메서드에서 cache_dir 매개변수를 설정하여 캐시 위치를 변경할 수 있습니다.

환경 변수

from_pretrained

캐시된 파일을 사용하면 Diffusers를 오프라인으로 사용할 수 있습니다. Diffusers가 인터넷에 연결하지 않도록 HF_HUB_OFFLINE 환경 변수를 1으로 설정하세요.

export HF_HUB_OFFLINE=1

캐시를 관리하고 정리하는 방법에 대한 자세한 내용은 캐싱 이해하기 가이드를 참고하세요.

Telemetry 로깅

Diffusers gathers telemetry information during from_pretrained() requests. The data gathered includes the Diffusers and PyTorch version, the requested model or pipeline class, and the path to a pretrained checkpoint if it is hosted on the Hub.

이 사용 데이터는 문제를 디버깅하고 새로운 기능을 우선순위에 두는 데 도움이 됩니다. 텔레메트리는 Hub에서 모델과 파이프라인을 로드할 때만 전송되며, 로컬 파일을 로드하는 경우 수집되지 않습니다.

HF_HUB_DISABLE_TELEMETRY 환경 변수를 사용하여 텔레메트리 수집을 옵트아웃하고 비활성화할 수 있습니다.

Linux/macOS

Windows

Update on GitHub