Diffusers documentation
파이프라인
파이프라인
Pipelines는 여러 독립적으로 학습된 모델, 스케줄러, 프로세서와 같은 모든 필수 구성 요소를 하나의 끝에서 끝(end-to-end) 클래스로 묶어, 최첨단 diffusion 모델을 추론(inference)으로 실행하는 간단한 방법을 제공합니다. Pipelines는 유연하며, 다른 스케줄러 또는 심지어 모델 구성 요소를 사용하도록 조정할 수 있습니다.
모든 파이프라인은 모든 구성 요소를 로드, 다운로드 및 저장하는 기본 기능을 제공하는 기본 DiffusionPipeline 클래스로 구성됩니다. from_pretrained()로 로드되는 특정 파이프라인 유형(예: StableDiffusionPipeline)은 자동으로 감지되며, 파이프라인 구성 요소가 로드되어 해당 파이프라인의 __init__ 함수에 전달됩니다.
DiffusionPipeline 클래스는 학습에 사용해서는 안 됩니다. diffusion 파이프라인의 개별 구성 요소(예: UNet2DModel 및 UNet2DConditionModel)는 일반적으로 개별적으로 학습되므로, 대신 해당 구성 요소에 직접 작업하는 것을 권장합니다.
Pipelines에는 학습 기능이 제공되지 않습니다. 파이프라인은 학습에 사용되지 않아야 하므로,
torch.no_grad데코레이터로__call__()메서드를 장식하여 PyTorch의 autograd가 비활성화됨을 확인할 수 있습니다. 학습에 관심이 있으시다면 Training 가이드를 참고해 주세요!
사이드바의 API > 파이프라인을 사용하여 모달리티별 모든 파이프라인 참조를 탐색할 수 있습니다. 작업 중심 워크플로우의 경우 빠른 시작 또는 텍스트-이미지 변환, 이미지-이미지 변환, 인페인팅, 비디오 생성과 같은 가이드로 시작하세요.
DiffusionPipeline
모든 파이프라인의 베이스 클래스입니다.
DiffusionPipeline는 diffusion 파이프라인의 모든 구성 요소(모델, 스케줄러, 프로세서)를 저장하고 모델의 로딩, 다운로드 및 저장을 위한 메서드를 제공합니다. 또한 다음 메서드를 포함합니다:
- PyTorch 모듈을 원하는 장치로 모두 이동
- denoising 반복에 대한 진행 표시줄을 활성화/비활성화합니다
클래스 속성:
- config_name (
str) — 모든 diffusion pipeline 구성 요소의 클래스 및 모듈 이름을 저장하는 구성 파일 이름입니다. - _optional_components (
List[str]) — 파이프라인이 작동하기 위해 전달할 필요가 없는 모든 선택적 컴포넌트의 목록 (서브클래스에서 오버라이드해야 합니다).
장치
< source >( ) → torch.device
반환값
torch.device
파이프라인이 위치한 torch 디바이스입니다. 구성 요소가 여러 디바이스에 걸쳐 분할된 경우(예: 텍스트 인코더는 CPU에, 디노이징 백본은 가속기에서 실행되는 경우)에는 가속기 디바이스가 반환됩니다.
(으)로
< source >( *args**kwargs ) → DiffusionPipeline
Performs Pipeline dtype and/or device conversion. A torch.dtype and torch.device are inferred from the
arguments of self.to(*args, **kwargs).
> 파이프라인에 이미 올바른 torch.dtype와 torch.device가 있는 경우, 그대로 반환됩니다. 그렇지 않은 경우, > 반환되는 파이프라인은 원하는 torch.dtype와 torch.device를 가진 self의 복사본입니다.
to를 호출하는 방법은 다음과 같습니다:
to(dtype, silence_dtype_warnings=False) → DiffusionPipeline를 사용하여 지정된dtype을 가진 파이프라인을 반환합니다to(device, silence_dtype_warnings=False) → DiffusionPipeline를 호출하여 지정된device를 가진 파이프라인을 반환합니다to(device=None, dtype=None, silence_dtype_warnings=False) → DiffusionPipeline를 호출하여 지정된device와dtype를 가진 파이프라인을 반환합니다.
self.components 속성은 추가 메모리를 재할당하지 않고 동일한 가중치와 구성으로 다른 파이프라인을 실행하는 데 유용할 수 있습니다.
dict 반환:
파이프라인 초기화에 필요한 모든 모듈을 포함하는 사전입니다.
예:
>>> from diffusers import (
... StableDiffusionPipeline,
... StableDiffusionImg2ImgPipeline,
... StableDiffusionInpaintPipeline,
... )
>>> text2img = StableDiffusionPipeline.from_pretrained("stable-diffusion-v1-5/stable-diffusion-v1-5")
>>> img2img = StableDiffusionImg2ImgPipeline(**text2img.components)
>>> inpaint = StableDiffusionInpaintPipeline(**text2img.components)슬라이스된 어텐션 계산 기능을 비활성화합니다. enable_attention_slicing가 이전에 호출된 경우, 어텐션은 한 번에 계산됩니다.
xFormers에서 메모리 효율적 어텐션을 비활성화합니다.
다운로드
< source >( pretrained_model_name**kwargs ) → os.PathLike
매개변수
- pretrained_model_name (
str또는os.PathLike, 선택 사항) — Hub에 호스팅된 사전 학습된 파이프라인의 리포지토리 ID(예:CompVis/ldm-text2im-large-256)를 나타내는 문자열입니다. - custom_pipeline (
str, 선택 사항) — 다음 중 하나일 수 있습니다: Hub에 호스팅된 사전 학습된 파이프라인의 저장소 ID(예: CompVis/ldm-text2im-large-256)를 나타내는 문자열. 이 저장소에는 커스텀 파이프라인을 정의하는 pipeline.py 파일이 포함되어야 합니다. GitHub의 Community 아래에 호스팅된 커뮤니티 파이프라인의 파일 이름을 나타내는 문자열. 유효한 파일 이름은 파이프라인 스크립트가 아닌 파일 이름과 일치해야 합니다(clip_guided_stable_diffusion.py가 아닌 clip_guided_stable_diffusion). 커뮤니티 파이프라인은 항상 GitHub의 현재 main 브랜치에서 로드됩니다. 커스텀 파이프라인을 포함하는 디렉터리(./my_pipeline_directory/)의 경로. 이 디렉터리에는 커스텀 파이프라인을 정의하는 pipeline.py 파일이 포함되어야 합니다. > 🧪 이는 실험적 기능이며 향후 변경될 수 있습니다. 커스텀 파이프라인을 로드하고 만드는 방법에 대한 자세한 내용은 How to contribute a community pipeline을 참고하세요.-
Hub에 호스팅된 사전 학습된 파이프라인의 repository id(예:
CompVis/ldm-text2im-large-256)를 나타내는 문자열입니다. 저장소에는 커스텀 파이프라인을 정의하는pipeline.py라는 파일이 포함되어야 합니다. -
문자열이며, GitHub의 Community 아래에 호스팅된 커뮤니티 파이프라인의 파일 이름입니다. 유효한 파일 이름은 파이프라인 스크립트가 아닌 파일 이름과 일치해야 합니다(
clip_guided_stable_diffusion.py가 아닌clip_guided_stable_diffusion). 커뮤니티 파이프라인은 항상 GitHub의 현재main브랜치에서 로드됩니다. -
커스텀 파이프라인을 포함하는 디렉터리(
./my_pipeline_directory/)의 경로입니다. 디렉터리에는 커스텀 파이프라인을 정의하는pipeline.py라는 파일이 포함되어야 합니다.
> 🧪 이는 실험적 기능이며 향후 변경될 수 있습니다.
커스텀 파이프라인을 로드하고 만드는 방법에 대한 자세한 내용은 커뮤니티 파이프라인 기여하기를 참고하세요.
-
- force_download (
bool, 선택 사항, 기본값False) — 모델 가중치 및 구성 파일의 (재)다운로드를 강제할지 여부입니다. 캐시된 버전이 존재하는 경우 이를 무시합니다. - proxies (
Dict[str, str], 선택) — 프로토콜 또는 엔드포인트별로 사용할 프록시 서버의 사전입니다. 예를 들어,{'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}와 같습니다. 각 요청 시 프록시가 사용됩니다. - output_loading_info(
bool, optional, 기본값False) — 누락된 키, 예상치 못한 키 및 오류 메시지를 포함하는 사전도 함께 반환할지 여부. - local_files_only (
bool, 선택 사항, 기본값False) — 로컬 모델 가중치 및 구성 파일만 로드할지 여부를 지정합니다.True로 설정하면 Hub에서 모델을 다운로드하지 않습니다. - token (
str또는 bool, 선택 사항) — 원격 파일에 대한 HTTP bearer 인증으로 사용할 토큰입니다.True인 경우,diffusers-cli login에서 생성된 토큰(~/.huggingface에 저장됨)이 사용됩니다. - revision (
str, 선택 사항, 기본값"main") — 사용할 특정 모델 버전입니다. Git에서 허용하는 브랜치 이름, 태그 이름, 커밋 ID 또는 기타 식별자일 수 있습니다. - custom_revision (
str, 선택 사항, 기본값"main") — 사용할 특정 모델 버전입니다. Hub에서 커스텀 파이프라인을 로드할 때revision과 유사하게 브랜치 이름, 태그 이름 또는 커밋 ID일 수 있습니다. GitHub에서 커스텀 파이프라인을 로드할 때는 🤗 Diffusers 버전일 수 있으며, Hub에서 로드하는 경우 기본값은"main"입니다. - mirror (
str, 선택 사항) — 중국에서 모델을 다운로드할 때 접근성 문제를 해결하기 위한 미러 소스입니다. 소스의 적시성이나 안전성을 보장하지 않으며, 자세한 정보는 해당 미러 사이트를 참고하세요. - variant (
str, 선택 사항) —"fp16"또는"ema"와 같이 지정된 variant 파일 이름에서 가중치를 로드합니다. - use_safetensors (
bool, 선택 사항, 기본값None) —None으로 설정하면, safetensors 가중치가 사용 가능하고 그리고 safetensors 라이브러리가 설치된 경우에만 safetensors 가중치가 다운로드됩니다.True로 설정하면 모델이 safetensors 가중치에서 강제 로드됩니다.False로 설정하면 safetensors 가중치가 로드되지 않습니다. - use_onnx (
bool, 선택 사항, 기본값False) —True로 설정하면 ONNX 가중치가 존재하는 경우 항상 다운로드됩니다.False로 설정하면 ONNX 가중치는 절대 다운로드되지 않습니다. 기본적으로use_onnx는_is_onnx클래스 속성의 기본값을 따르며, 이는 ONNX가 아닌 파이프라인의 경우False, ONNX 파이프라인의 경우True입니다. ONNX 가중치에는.onnx및.pb로 끝나는 두 가지 파일이 모두 포함됩니다. - trust_remote_code (
bool, 선택 사항, 기본값False) — Hub에서 자체 파일로 정의된 사용자 정의 파이프라인 및 구성 요소를 허용할지 여부입니다. 이 옵션은 Hub에 존재하는 코드가 로컬 머신에서 실행되므로, 신뢰할 수 있는 저장소에서만True로 설정하고 해당 코드를 읽은 경우에만 사용해야 합니다. - use_flashpack (
bool, 선택 사항, 기본값False) —True로 설정하면 FlashPack 가중치가 존재하는 경우 항상 다운로드됩니다.False로 설정하면 FlashPack 가중치는 절대 다운로드되지 않습니다.
반환값
os.PathLike
다운로드된 파이프라인의 경로입니다.
PyTorch diffusion 파이프라인을 사전 학습된 파이프라인 가중치에서 다운로드하고 캐시합니다.
> 비공개 또는 게이트된 모델을 사용하려면 `hf > auth login`으로 로그인하세요
enable_attention_slicing
< source >( slice_size: str | int = 'auto' )
슬라이스된 어텐션 계산을 활성화합니다. 이 옵션이 활성화되면 어텐션 모듈은 입력 텐서를 슬라이스로 나누어 여러 단계에 걸쳐 어텐션을 계산합니다. 어텐션 헤드가 하나 이상인 경우, 각 헤드를 순차적으로 계산합니다. 이는 속도가 약간 감소하는 대신 메모리를 절약하는 데 유용합니다.
> ⚠️ PyTorch > 2.0 또는 xFormers의
scaled_dot_product_attention(SDPA)를 이미 사용 중이라면 attention slicing을 활성화하지 마세요. 이러한 attention 계산은 이미 메모리 효율성이 매우 높아 이 기능을 활성화할 필요가 없습니다. SDPA 또는 xFormers와 함께 attention slicing을 활성화하면 심각한 성능 저하가 발생할 수 있습니다!
예:
>>> import torch
>>> from diffusers import StableDiffusionPipeline
>>> pipe = StableDiffusionPipeline.from_pretrained(
... "stable-diffusion-v1-5/stable-diffusion-v1-5",
... dtype=torch.float16,
... use_safetensors=True,
... )
>>> prompt = "a photo of an astronaut riding a horse on mars"
>>> pipe.enable_attention_slicing()
>>> image = pipe(prompt).images[0]enable_group_offload
< source >( onload_device: deviceoffload_device: device = torch.device()offload_type: str = 'block_level'num_blocks_per_group: int | None = Nonenon_blocking: bool = Falseuse_stream: bool = Falserecord_stream: bool = Falselow_cpu_mem_usage = Falseoffload_to_disk_path: str | None = Noneexclude_modules: str | list[str] | None = None )
매개변수
- onload_device (
torch.device) — 모듈 그룹이 onload되는 장치입니다. - offload_device (
torch.device, 기본값torch.device("cpu")) — 모듈 그룹이 오프로드되는 장치입니다. 일반적으로 CPU여야 합니다. 기본값은 CPU입니다. - offload_type (
str또는GroupOffloadingType, 기본값 “block_level”) — 적용할 오프로딩의 유형입니다. “block_level” 또는 “leaf_level” 중 하나일 수 있습니다. 기본값은 “block_level”입니다. - offload_to_disk_path (
str, 선택 사항, 기본값None) — 파라미터가 오프로드될 디렉터리의 경로입니다. RAM이 제한된 환경에서 합리적인 속도-메모리 트레이드오프가 필요한 경우 이 옵션을 설정하는 것이 유용할 수 있습니다. - num_blocks_per_group (
int, 선택 사항) — offload_type=“block_level”을 사용할 때 그룹당 블록 수입니다. offload_type=“block_level”을 사용할 때 필수입니다. - non_blocking (
bool, 기본값False) — True인 경우, 오프로딩과 온로딩이 비차단 데이터 전송으로 수행됩니다. - use_stream (
bool, 기본값False) — True인 경우, CUDA stream을 사용하여 오프로딩과 온로딩을 비동기적으로 수행합니다. 이는 계산과 데이터 전송을 오버랩하는 데 유용할 수 있습니다. - record_stream (
bool, 기본값False) —use_stream와 함께 활성화되면 현재 tensor가 해당 stream에서 사용되었음을 표시합니다. 메모리 사용량이 약간 증가하는 대신 더 빠른 성능을 제공합니다. 자세한 내용은 PyTorch 공식 문서를 참조하세요. - low_cpu_mem_usage (
bool, 기본값False) — True인 경우, 텐서를 미리 고정하는 대신 필요할 때 즉시 고정하여 CPU 메모리 사용량을 최소화합니다. 이 옵션은 스트림된 CPU 오프로딩(즉,use_stream=True)을 사용할 때만 의미가 있습니다. CPU 메모리가 병목 현상을 일으키는 경우 유용할 수 있지만, 스트림 사용의 이점을 상쇄할 수도 있습니다. - exclude_modules (
Union[str, List[str]], 기본값None) — 오프로딩에서 제외할 모듈 목록입니다.
torch.nn.Module의 내부 레이어에 group offloading을 적용합니다. group offloading이 무엇인지, 그리고 어떤 상황에서 이점이 있는지 이해하려면, 먼저 다른 지원되는 offloading 방식이 어떻게 작동하는지에 대한 배경을 제공해야 합니다.
일반적으로 오프로딩은 두 단계에서 수행됩니다:
- Module-level: Diffusers에서는
ModelMixin::enable_model_cpu_offload()메서드를 사용하여 이를 활성화할 수 있습니다. 이 메서드는 파이프라인의 각 구성 요소를 저장하기 위해 CPU로 오프로딩하고, 계산이 필요할 때 가속기 디바이스로 온로딩하는 방식으로 작동합니다. 이 메서드는 모든 구성 요소를 가속기에 유지하는 것보다 메모리 효율이 높지만, 여전히 메모리 요구량이 상당히 높습니다. 이 메서드가 작동하려면 런타임 데이터 타입 기준 모델 크기 + 가장 큰 중간 활성화 텐서 크기에 해당하는 메모리가 있어야 포워드 패스를 완료할 수 있습니다. - Leaf-level: Diffusers에서는
ModelMixin::enable_sequential_cpu_offload()메서드를 사용하여 이를 활성화할 수 있습니다. 이는 계산 그래프의 가장 낮은 leaf-level 파라미터를 CPU로 offload하여 저장하고, 계산 시 leaf만 accelerator device로 onloading하는 방식으로 작동합니다. 이 방식은 accelerator 메모리 사용량이 가장 적지만, 과도한 수의 device 동기화 때문에 속도가 느려질 수 있습니다.
Group offloading은 두 가지 방법의 중간 단계입니다. 내부 레이어 그룹(torch.nn.ModuleList 또는 torch.nn.Sequential)을 offload하는 방식으로 작동합니다. 이 방법은 모듈 수준 offloading보다 메모리 사용량이 적습니다. 또한 장치 동기화 횟수가 줄어들기 때문에 leaf 수준/순차적 offloading보다 빠릅니다.
CUDA 디바이스에서 비동기 데이터 전송 스트림을 지원하는 경우, 또 다른 지원되는 기능은 순차적 오프로딩과 비교하여 전체 실행 시간을 줄이기 위해 데이터 전송과 계산을 겹치게 하는 능력입니다. 이는 스트림을 사용한 레이어 프리페칭으로 활성화되며, 즉 현재 레이어가 실행되는 동안 다음으로 실행될 레이어가 가속기 디바이스로의 온로딩을 시작합니다. 이 방식은 메모리 요구 사항을 약간 증가시킵니다. 참고로 이 구현은 리프 레벨 오프로딩도 지원하지만, 스트림을 사용할 때 훨씬 더 빨라질 수 있습니다.
예:
>>> from diffusers import DiffusionPipeline
>>> import torch
>>> pipe = DiffusionPipeline.from_pretrained("Qwen/Qwen-Image", dtype=torch.bfloat16)
>>> pipe.enable_group_offload(
... onload_device=torch.device("cuda"),
... offload_device=torch.device("cpu"),
... offload_type="leaf_level",
... use_stream=True,
... )
>>> image = pipe("a beautiful sunset").images[0]enable_model_cpu_offload
< source >( gpu_id: int | None = Nonedevice: typing.Union[torch.device, str] = None )
accelerate를 사용하여 모든 모델을 CPU로 오프로드하여 성능에 미치는 영향은 적으면서 메모리 사용량을 줄입니다. enable_sequential_cpu_offload와 비교하면, 이 메서드는 forward 메서드가 호출될 때 한 번에 하나의 모델을 가속기로 이동시키고, 다음 모델이 실행될 때까지 해당 모델이 가속기에 유지됩니다. enable_sequential_cpu_offload에 비해 메모리 절감 효과는 낮지만, unet의 반복적 실행 덕분에 성능이 훨씬 좋습니다.
enable_sequential_cpu_offload
< source >( gpu_id: int | None = Nonedevice: typing.Union[torch.device, str] = None )
🤗 Accelerate를 사용하여 모든 모델을 CPU로 오프로드하여 메모리 사용량을 크게 줄입니다. 호출 시 self._exclude_from_cpu_offload에 포함된 것을 제외한 모든 torch.nn.Module 구성 요소의 상태 딕트가 CPU에 저장된 후 torch.device('meta')로 이동되며, 해당 서브모듈의 forward 메서드가 호출될 때에만 가속기로 로드됩니다. 오프로딩은 서브모듈 단위로 수행됩니다. enable_model_cpu_offload를 사용할 때보다 메모리 절감 효과가 크지만 성능은 낮습니다.
enable_xformers_memory_efficient_attention
< source >( attention_op: typing.Optional[typing.Callable] = None )
매개변수
- attention_op (
Callable, 선택 사항) — xFormers의memory_efficient_attention()함수의op인수로 사용될None기본 연산자를 재정의합니다.
xFormers에서 메모리 효율적인 어텐션을 활성화합니다. 이 옵션을 활성화하면 추론 시 GPU 메모리 사용량이 감소하고 속도가 향상될 수 있습니다. 학습 시 속도 향상은 보장되지 않습니다.
> ⚠️ memory efficient attention과 sliced attention이 모두 활성화된 경우, memory efficient attention이 > 우선합니다.
예:
>>> import torch
>>> from diffusers import DiffusionPipeline
>>> from xformers.ops import MemoryEfficientAttentionFlashAttentionOp
>>> pipe = DiffusionPipeline.from_pretrained("stabilityai/stable-diffusion-2-1", dtype=torch.float16)
>>> pipe = pipe.to("cuda")
>>> pipe.enable_xformers_memory_efficient_attention(attention_op=MemoryEfficientAttentionFlashAttentionOp)
>>> # Workaround for not accepting attention shape using VAE for Flash Attention
>>> pipe.vae.enable_xformers_memory_efficient_attention(attention_op=None)from_pipe
< source >( pipeline**kwargs ) → DiffusionPipeline
주어진 pipeline에서 새로운 pipeline을 생성합니다. 이 메서드는 기존 pipeline 구성 요소를 사용하여 추가 메모리를 할당하지 않고 새로운 pipeline을 생성하는 데 유용합니다.
from_pretrained
< source >( pretrained_model_name_or_path: str | os.PathLike**kwargs )
매개변수
- pretrained_model_name_or_path (
str또는os.PathLike, 선택 사항) — 다음 중 하나일 수 있습니다:- Hub에 호스팅된 사전 학습된 파이프라인의 repo id(예:
CompVis/ldm-text2im-large-256) 문자열 - save_pretrained()를 사용하여 저장된 파이프라인 가중치가 포함된 디렉터리의 경로(예:
./my_pipeline_directory/)
- Hub에 호스팅된 사전 학습된 파이프라인의 repo id(예:
- dtype (
torch.dtype또는dict[str, Union[str, torch.dtype]], 선택 사항) — 기본torch.dtype를 재정의하여 다른 dtype로 모델을 로드합니다. 서브모델을 서로 다른 dtype로 로드하려면dict를 전달합니다(예:{'transformer': torch.bfloat16, 'vae': torch.float16}). 지정되지 않은 구성 요소의 기본 dtype는default로 설정합니다(예:{'transformer': torch.bfloat16, 'default': torch.float16}). 구성 요소가 지정되지 않았고 기본값도 설정되지 않은 경우,torch.float32가 사용됩니다. - custom_pipeline (
str, 선택 사항) —> 🧪 이는 실험적 기능이며 향후 변경될 수 있습니다.
다음 중 하나일 수 있습니다:
- Hub에 호스팅된 커스텀 파이프라인의 repo id(예:
hf-internal-testing/diffusers-dummy-pipeline)를 나타내는 문자열입니다. 저장소에는 커스텀 파이프라인을 정의하는 pipeline.py 파일이 포함되어야 합니다. - 문자열이며, GitHub의 Community 아래에 호스팅된 커뮤니티 파이프라인의 파일 이름입니다. 유효한 파일 이름은 파이프라인 스크립트가 아닌 파일 이름과 일치해야 합니다(
clip_guided_stable_diffusion.py가 아닌clip_guided_stable_diffusion). 커뮤니티 파이프라인은 항상 GitHub의 현재 main 브랜치에서 로드됩니다. - 커스텀 파이프라인이 포함된 디렉터리(
./my_pipeline_directory/)의 경로입니다. 해당 디렉터리에는 커스텀 파이프라인을 정의하는pipeline.py파일이 포함되어 있어야 합니다.
커스텀 파이프라인을 로드하고 만드는 방법에 대한 자세한 내용은 커스텀 파이프라인 로드 및 추가를 참고하세요.
- Hub에 호스팅된 커스텀 파이프라인의 repo id(예:
- force_download (
bool, 선택 사항, 기본값False) — 모델 가중치 및 구성 파일의 (재)다운로드를 강제할지 여부입니다. 캐시된 버전이 존재하는 경우 이를 무시합니다. - cache_dir (
Union[str, os.PathLike], 선택) — 표준 캐시를 사용하지 않을 경우, 다운로드된 사전 학습 모델 구성이 캐시되는 디렉터리의 경로입니다. - proxies (
Dict[str, str], 선택) — 프로토콜 또는 엔드포인트별로 사용할 프록시 서버의 사전입니다. 예를 들어,{'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}와 같습니다. 각 요청 시 프록시가 사용됩니다. - output_loading_info(
bool, optional, 기본값False) — 누락된 키, 예상치 못한 키 및 오류 메시지를 포함하는 사전도 함께 반환할지 여부. - local_files_only (
bool, 선택 사항, 기본값False) — 로컬 모델 가중치 및 구성 파일만 로드할지 여부를 지정합니다.True로 설정하면 Hub에서 모델을 다운로드하지 않습니다. - token (
str또는 bool, 선택 사항) — 원격 파일에 대한 HTTP bearer 인증으로 사용할 토큰입니다.True인 경우,diffusers-cli login에서 생성된 토큰(~/.huggingface에 저장됨)이 사용됩니다. - revision (
str, 선택 사항, 기본값"main") — 사용할 특정 모델 버전입니다. Git에서 허용하는 브랜치 이름, 태그 이름, 커밋 ID 또는 기타 식별자일 수 있습니다. - custom_revision (
str, 선택 사항) — 사용할 특정 모델 버전입니다. Hub에서 커스텀 파이프라인을 로드할 때revision과 유사하게 브랜치 이름, 태그 이름 또는 커밋 ID를 사용할 수 있습니다. 기본값은 최신 안정 버전의 🤗 Diffusers입니다. - mirror (
str, 선택 사항) — 중국에서 모델을 다운로드할 때 접근성 문제를 해결하기 위한 미러 소스입니다. 소스의 적시성이나 안전성을 보장하지 않으며, 자세한 정보는 해당 미러 사이트를 참고하세요. - device_map (
str, 선택 사항) — pipeline의 각 구성 요소를 사용 가능한 장치에 배치하는 방식을 결정하는 전략입니다. 현재 “balanced”device_map만 지원됩니다. 자세한 내용은 여기를 참고하세요. - max_memory (
Dict, 선택 사항) — 최대 메모리에 대한 디바이스 식별자를 나타내는 사전입니다. 설정되지 않으면 각 GPU의 사용 가능한 최대 메모리와 사용 가능한 CPU RAM이 기본값으로 사용됩니다. - offload_folder (
str또는os.PathLike, 선택 사항) —"disk"값을 포함하는 device_map의 경우, 가중치를 오프로드할 경로입니다. - offload_state_dict (
bool, 선택 사항) —True인 경우, CPU state dict의 가중치와 체크포인트의 가장 큰 샤드가 함께 CPU RAM에 맞지 않을 때 RAM 부족을 방지하기 위해 CPU state dict를 임시로 하드 드라이브로 오프로드합니다. 디스크 오프로드가 있는 경우 기본값은True입니다. - low_cpu_mem_usage (
bool, 선택 사항, torch 버전이 1.9.0 이상이면 기본값은True, 그 외에는False) — 가중치를 초기화하지 않고 사전 학습된 가중치만 로드하여 모델 로딩 속도를 높입니다. 또한 모델 로딩 중 CPU 메모리(피크 메모리 포함)를 모델 크기의 1배를 초과하지 않도록 시도합니다. PyTorch 1.9.0 이상에서만 지원됩니다. PyTorch의 이전 버전을 사용하는 경우 이 인수를True로 설정하면 오류가 발생합니다. - use_safetensors (
bool, 선택 사항, 기본값None) —None으로 설정하면, safetensors 가중치가 사용 가능하고 그리고 safetensors 라이브러리가 설치된 경우에만 safetensors 가중치가 다운로드됩니다.True로 설정하면 모델이 safetensors 가중치에서 강제 로드됩니다.False로 설정하면 safetensors 가중치가 로드되지 않습니다. - use_onnx (
bool, 선택 사항, 기본값None) —True로 설정하면 ONNX 가중치가 존재하는 경우 항상 다운로드됩니다.False로 설정하면 ONNX 가중치는 절대 다운로드되지 않습니다. 기본적으로use_onnx는_is_onnx클래스 속성의 기본값을 따르며, 이는 ONNX가 아닌 파이프라인의 경우False, ONNX 파이프라인의 경우True입니다. ONNX 가중치에는.onnx및.pb로 끝나는 두 가지 파일이 모두 포함됩니다. - kwargs (나머지 키워드 인자 사전, 선택 사항) —
특정 파이프라인 클래스의 파이프라인 구성 요소인 로드 및 저장 가능 변수를 덮어쓸 수 있습니다. 덮어쓴 구성 요소는 파이프라인의
__init__메서드에 직접 전달됩니다. 자세한 내용은 아래 예시를 참조하세요. - variant (
str, 선택 사항) —"fp16"또는"ema"와 같이 지정된 variant 파일 이름에서 가중치를 로드합니다. - disable_mmap (‘bool’, 선택 사항, 기본값 ‘False’) — Safetensors 모델을 로드할 때 mmap을 비활성화할지 여부입니다. 네트워크 마운트나 하드 드라이브에 모델이 있는 경우 mmap의 seek 동작을 잘 처리하지 못할 수 있으므로, 이 옵션을 사용하면 성능이 더 좋아질 수 있습니다.
PyTorch 확산 파이프라인을 사전 학습된 파이프라인 가중치에서 초기화합니다.
파이프라인은 기본적으로 평가 모드(model.eval())로 설정됩니다.
아래와 같은 오류 메시지가 표시되면 다운스트림 작업을 위해 가중치를 미세 조정해야 합니다:
Some weights of UNet2DConditionModel were not initialized from the model checkpoint at stable-diffusion-v1-5/stable-diffusion-v1-5 and are newly initialized because the shapes did not match:
- conv_in.weight: found shape torch.Size([320, 4, 3, 3]) in the checkpoint and torch.Size([320, 9, 3, 3]) in the model instantiated
You should probably TRAIN this model on a down-stream task to be able to use it for predictions and inference.> 비공개 또는 게이트된 모델을 사용하려면
hf > auth login으로 로그인하세요.
예:
>>> from diffusers import DiffusionPipeline
>>> # Download pipeline from huggingface.co and cache.
>>> pipeline = DiffusionPipeline.from_pretrained("CompVis/ldm-text2im-large-256")
>>> # Download pipeline that requires an authorization token
>>> # For more information on access tokens, please refer to this section
>>> # of the documentation](https://huggingface.co/docs/hub/security-tokens)
>>> pipeline = DiffusionPipeline.from_pretrained("stable-diffusion-v1-5/stable-diffusion-v1-5")
>>> # Use a different scheduler
>>> from diffusers import LMSDiscreteScheduler
>>> scheduler = LMSDiscreteScheduler.from_config(pipeline.scheduler.config)
>>> pipeline.scheduler = scheduler다음과 같은 작업을 수행하는 메서드입니다:
- 모든 구성 요소를 오프로드합니다.
enable_model_cpu_offload을 사용할 때 추가된 모든 모델 훅을 제거한 후 다시 적용합니다. 모델이 오프로드되지 않은 경우, 이 함수는 아무 동작도 하지 않습니다.register_hook()으로 추가된 경우, denoiser 구성 요소의 상태ful diffusers 훅을 초기화합니다.
enable_model_cpu_offload를 적용할 때 올바르게 작동하도록 하려면 이 함수를 파이프라인의 __call__ 함수 끝에 추가하세요.
NumPy 이미지 또는 이미지 배치를 PIL 이미지로 변환합니다.
enable_sequential_cpu_offload 또는 enable_model_cpu_offload을 사용할 때 추가된 모든 훅을 제거합니다.
None으로 디바이스 맵(있는 경우)을 초기화합니다.
save_pretrained
< source >( save_directory: str | os.PathLikesafe_serialization: bool = Truevariant: str | None = Nonemax_shard_size: int | str | None = Nonepush_to_hub: bool = Falseuse_flashpack: bool = False**kwargs )
매개변수
- save_directory (
str또는os.PathLike) — 파이프라인을 저장할 디렉터리입니다. 존재하지 않으면 생성됩니다. - safe_serialization (
bool, 선택 사항, 기본값True) —safetensors를 사용하여 모델을 저장할지, 아니면pickle을 사용한 전통적인 PyTorch 방식으로 저장할지를 결정합니다. - variant (
str, 선택 사항) — 지정된 경우, 가중치는pytorch_model.<variant>.bin형식으로 저장됩니다. - max_shard_size (
int또는str, 기본값None) — 샤딩되기 전 체크포인트의 최대 크기입니다. 샤딩된 각 체크포인트의 크기는 이 크기보다 작아집니다. 문자열로 표현할 경우, 숫자 뒤에 단위(예:"5GB")가 따라와야 합니다. 정수로 표현할 경우, 단위는 바이트입니다. 2024년 10월부터 특정 기간이 지난 후 이 한도가 낮아질 수 있으며, 이는 사용자가diffusers의 최신 버전으로 업그레이드할 수 있도록 하기 위한 것입니다. 이는 Hugging Face 생태계의 다른 라이브러리(예:transformers,accelerate)에서 이 인수의 공통 기본 크기를 설정하기 위한 것입니다. - push_to_hub (
bool, 선택 사항, 기본값False) — 모델을 저장한 후 Hugging Face 모델 허브에 푸시할지 여부입니다.repo_id를 사용하여 푸시할 저장소를 지정할 수 있으며, 지정하지 않으면 네임스페이스 내save_directory의 이름이 기본값으로 사용됩니다. - kwargs (
Dict[str, Any], 선택) — push_to_hub() 메서드에 함께 전달되는 추가 키워드 인자입니다.
파이프라인의 저장 가능한 모든 변수를 디렉터리에 저장합니다. 클래스에 저장 및 로드 메서드가 모두 구현되어 있으면 해당 파이프라인 변수를 저장하고 로드할 수 있습니다. from_pretrained() 클래스 메서드를 사용하면 파이프라인을 쉽게 다시 로드할 수 있습니다.
diffusers.StableDiffusionMixin.enable_freeu
< source >( s1: floats2: floatb1: floatb2: float )
매개변수
- s1 (
float) — 1단계의 스케일링 계수로, 스킵 특징의 기여도를 감쇠시키는 데 사용됩니다. 이는 강화된 노이즈 제거 과정에서 “과도한 매끄러움 효과(oversmoothing effect)”를 완화하기 위한 것입니다. - s2 (
float) — 2단계의 스케일링 계수로, 스킵 특징의 기여도를 감쇠시키는 데 사용됩니다. 이는 강화된 노이즈 제거 과정에서 “과도한 매끄러움 효과(oversmoothing effect)”를 완화하기 위한 것입니다. - b1 (
float) — 백본 특징의 기여도를 증폭하기 위한 1단계의 스케일링 계수. - b2 (
float) — 백본 특징의 기여도를 증폭하기 위한 2단계의 스케일링 계수.
https://huggingface.co/papers/2309.11497에 설명된 FreeU 메커니즘을 활성화합니다.
스케일링 인자 뒤에 붙는 접미사는 해당 인자가 적용되는 단계를 나타냅니다.
Stable Diffusion v1, v2, Stable Diffusion XL과 같은 다양한 파이프라인에서 잘 작동하는 것으로 알려진 값 조합에 대해서는 공식 저장소를 참고하세요.
활성화된 경우 FreeU 메커니즘을 비활성화합니다.
PushToHubMixin
Hugging Face Hub에 모델, 스케줄러 또는 파이프라인을 푸시하기 위한 Mixin입니다.
push_to_hub
< source >( repo_id: strcommit_message: str | None = Noneprivate: bool | None = Nonetoken: str | None = Nonecreate_pr: bool = Falsesafe_serialization: bool = Truevariant: str | None = Nonesubfolder: str | None = None )
매개변수
- repo_id (
str) — 모델, 스케줄러 또는 파이프라인 파일을 푸시할 저장소의 이름입니다. 조직에 푸시할 경우 조직 이름을 포함해야 합니다.repo_id는 로컬 디렉토리의 경로일 수도 있습니다. - commit_message (
str, 선택 사항) — 푸시할 때 커밋할 메시지. 기본값은"Upload {object}"입니다. - private (
bool, 선택 사항) — 리포지토리를 비공개로 만들지 여부를 지정합니다.None(기본값)인 경우, 조직의 기본 설정이 비공개가 아닌 한 리포지토리는 공개됩니다. 이미 리포지토리가 존재하면 이 값은 무시됩니다. - token (
str, 선택 사항) — 원격 파일에 대한 HTTP bearer 인증으로 사용할 토큰입니다.hf auth login실행 시 생성된 토큰(~/.huggingface에 저장됨)입니다. - create_pr (
bool, 선택 사항, 기본값False) — 업로드된 파일로 PR을 생성할지 아니면 직접 커밋할지 여부. - safe_serialization (
bool, 선택 사항, 기본값True) — 모델 가중치를safetensors형식으로 변환할지 여부입니다. - variant (
str, 선택 사항) — 지정된 경우, 가중치는pytorch_model.<variant>.bin형식으로 저장됩니다.
모델, 스케줄러 또는 파이프라인 파일을 🤗 Hugging Face Hub에 업로드합니다.
예:
from diffusers import UNet2DConditionModel
unet = UNet2DConditionModel.from_pretrained("stabilityai/stable-diffusion-2", subfolder="unet")
# Push the `unet` to your namespace with the name "my-finetuned-unet".
unet.push_to_hub("my-finetuned-unet")
# Push the `unet` to an organization with the name "my-finetuned-unet".
unet.push_to_hub("your-org/my-finetuned-unet")콜백
클래스 diffusers.callbacks.PipelineCallback
< source >( cutoff_step_ratio = 1.0cutoff_step_index = None )
파이프라인에서 사용되는 모든 공식 콜백의 베이스 클래스입니다. 이 클래스는 사용자 정의 콜백을 구현하기 위한 구조를 제공하며, 모든 콜백이 일관된 인터페이스를 갖도록 보장합니다.
다음과 같이 구현하세요: tensor_inputs: 이 메서드는 콜백에 특화된 텐서 입력 목록을 반환해야 합니다. 파이프라인 클래스의 ._callback_tensor_inputs 속성에 나열된 변수만 포함할 수 있습니다. callback_fn: 이 메서드는 콜백의 핵심 기능을 정의합니다.
class diffusers.callbacks.SDCFGCutoffCallback
< source >( cutoff_step_ratio = 1.0cutoff_step_index = None )
Stable Diffusion 파이프라인용 콜백 함수입니다. 특정 단계 수( cutoff_step_ratio 또는 cutoff_step_index로 설정) 이후에 이 콜백은 CFG를 비활성화합니다.
Note: 이 콜백은 카utoff 단계 이후 _guidance_scale 속성을 0.0으로 변경하여 파이프라인을 변경합니다.
class diffusers.callbacks.SDXLCFGCutoffCallback
< source >( cutoff_step_ratio = 1.0cutoff_step_index = None )
기본 Stable Diffusion XL 파이프라인의 콜백 함수입니다. 특정 단계 수(이 값은 cutoff_step_ratio 또는 cutoff_step_index로 설정됨) 이후에 이 콜백은 CFG를 비활성화합니다.
Note: 이 콜백은 카utoff 단계 이후 _guidance_scale 속성을 0.0으로 변경하여 파이프라인을 변경합니다.
클래스 diffusers.callbacks.SDXLControlnetCFGCutoffCallback
< source >( cutoff_step_ratio = 1.0cutoff_step_index = None )
Controlnet Stable Diffusion XL 파이프라인용 콜백 함수입니다. 특정 단계 수(이 값은 cutoff_step_ratio 또는 cutoff_step_index로 설정됨) 이후에 이 콜백은 CFG를 비활성화합니다.
Note: 이 콜백은 카utoff 단계 이후 _guidance_scale 속성을 0.0으로 변경하여 파이프라인을 변경합니다.
class diffusers.callbacks.IPAdapterScaleCutoffCallback
< source >( cutoff_step_ratio = 1.0cutoff_step_index = None )
IPAdapterMixin을 상속하는 모든 파이프라인에 대한 콜백 함수입니다. 특정 단계 수(이 값은 cutoff_step_ratio 또는 cutoff_step_index로 설정됨) 이후에 이 콜백은 IP Adapter 스케일을 0.0으로 설정합니다.
Note: 이 콜백은 cutoff 단계 이후 scale을 0.0으로 설정하여 IP Adapter attention processors를 변경합니다.
class diffusers.callbacks.SD3CFGCutoffCallback
< source >( cutoff_step_ratio = 1.0cutoff_step_index = None )
Stable Diffusion 3 파이프라인용 콜백 함수입니다. 특정 단계 수(이것은 cutoff_step_ratio 또는 cutoff_step_index로 설정됨) 이후에 이 콜백은 CFG를 비활성화합니다.
Note: 이 콜백은 카utoff 단계 이후 _guidance_scale 속성을 0.0으로 변경하여 파이프라인을 변경합니다.