Diffusers documentation

컴포넌트 및 구성

Diffusers

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.42.1).

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

컴포넌트 및 구성

ComponentSpec

class diffusers.ComponentSpec

( name: str | None = Nonetype_hint: typing.Optional[typing.Type] = Nonedescription: str | None = Noneconfig: diffusers.configuration_utils.FrozenDict | None = Nonepretrained_model_name_or_path: str | list[str] | None = Nonesubfolder: str | None = ''variant: str | None = Nonerevision: str | None = Nonedefault_creation_method: typing.Literal['from_config', 'from_pretrained'] = 'from_pretrained'repo: str | list[str] | None = None )

매개변수

name — 컴포넌트 이름
type_hint — 구성 요소의 유형 (예: UNet2DConditionModel)
description — 컴포넌트의 선택적 설명
config — init 생성을 위한 선택적 config dict
pretrained_model_name_or_path — from_pretrained 생성을 위한 선택적 pretrained_model_name_or_path 경로
subfolder — pretrained_model_name_or_path 안의 선택적 서브폴더
variant — pretrained_model_name_or_path의 선택적 variant
revision — 선택 사항. pretrained_model_name_or_path의 리비전
default_creation_method — 선호하는 생성 방법 - “from_config” 또는 “from_pretrained”

파이프라인 구성 요소의 사양입니다.

컴포넌트는 두 가지 방식으로 생성할 수 있습니다:

설정 딕셔너리를 사용하여 init로 처음부터
from_pretrained를 사용하여

create

( config: diffusers.configuration_utils.FrozenDict | dict[str, typing.Any] | None = None**kwargs )

from_config를 사용하여 config로 컴포넌트를 생성합니다.

decode_load_id

( load_id: str )

매개변수

load_id — 디코딩할 load_id 문자열, 형식: “pretrained_model_name_or_path|subfolder|variant|revision” 여기서 None 값은 “null”로 표시됩니다

load_id 문자열을 로딩 필드와 값의 사전으로 다시 디코딩합니다.

from_component

( name: strcomponent: Any )

매개변수

name — 컴포넌트 이름
component — 스펙을 생성할 Component 객체

Raises

ValueError

ValueError — 구성 요소가 지원되지 않는 경우 (예: load_id가 없는 nn.Module, non-ConfigMixin)

Component에서 ComponentSpec을 생성합니다.

현재 지원:

ComponentSpec.load() 메서드로 생성된 컴포넌트
ConfigMixin의 하위 클래스이지만 nn.Module은 아닌 컴포넌트(예: 스케줄러, 가이더)

로드

( **kwargs )

from_pretrained를 사용하여 컴포넌트를 로드합니다.

로딩 필드

( )

모든 로딩 관련 필드(즉, field.metadata["loading"]가 True인 필드)의 이름을 반환합니다.

ConfigSpec

class diffusers.ConfigSpec

( name: strdefault: Anydescription: str | None = None )

pipeline 구성 매개변수에 대한 사양입니다.

ComponentsManager

클래스 diffusers.ComponentsManager

( )

여러 파이프라인에 걸친 모델 컴포넌트를 위한 중앙 레지스트리 및 관리 시스템.

ComponentsManager는 UNet, VAE, 텍스트 인코더와 같은 모델 컴포넌트를 다양한 모듈형 파이프라인에 걸쳐 등록, 추적 및 재사용할 수 있는 통합된 방법을 제공합니다. 중복 감지, 메모리 관리 및 컴포넌트 조직 기능을 포함합니다.

> 이는 실험적 기능이며, 향후 변경될 수 있습니다.

예:

from diffusers import ComponentsManager

# Create a components manager
cm = ComponentsManager()

# Add components
cm.add("unet", unet_model, collection="sdxl")
cm.add("vae", vae_model, collection="sdxl")

# Enable auto offloading
cm.enable_auto_cpu_offload()

# Retrieve components
unet = cm.get_one(name="unet", collection="sdxl")

추가

( name: strcomponent: Anycollection: str | None = None ) → str

매개변수

name (str) — 컴포넌트의 이름
component (Any) — 추가할 컴포넌트
collection (str | None) — 구성 요소를 추가할 컬렉션

반환값

str

{name}_{id(component)} 형식으로 생성되는 고유한 컴포넌트 ID입니다. 여기서 id(component)는 Python의 내장 함수로, 해당 객체에 대한 고유 식별자를 반환합니다.

ComponentsManager에 구성 요소를 추가합니다.

disable_auto_cpu_offload

( )

모든 구성 요소에 대한 자동 CPU 오프로딩을 비활성화합니다.

enable_auto_cpu_offload

( device: str | int | torch.device = Nonememory_reserve_margin = '3GB'offload_strategy = None )

매개변수

device (str | int | torch.device) — 모델이 forward pass를 위해 이동되는 실행 장치
memory_reserve_margin (str) — 사용할 메모리 리저브 마진입니다. 기본값은 3GB입니다. 이는 모델 실행 중(예: 중간 활성화, 그래디언트 등) 메모리 부족을 방지하기 위해 디바이스에서 비워둘 메모리 양입니다.
offload_strategy — (hooks, model_id, model, execution_device) -> hooks 시그니처를 가진 임의의 호출 가능 객체(callable)로, 새로 로드될 모델이 로드되기 전에 오프로드할 상주(resident) 모델을 반환합니다. 기본값은 AutoOffloadStrategy이며, 최소한의 충분한 조합을 해제합니다.

모든 구성 요소에 대해 자동 CPU 오프로딩을 활성화합니다.

알고리즘은 다음과 같이 작동합니다:

모든 모델은 기본적으로 CPU에서 시작됩니다
모델의 forward pass가 호출되면 실행 장치로 이동됩니다
메모리가 부족하면 해당 장치의 다른 모델은 CPU로 다시 이동됩니다
시스템은 충분한 메모리를 확보할 수 있는 가장 작은 모델 조합을 오프로드하도록 시도합니다
Models은 다른 모델이 메모리를 필요로 하여 이전을 강제할 때까지 실행 장치에 유지됩니다

A group offloaded model은 이 과정에 참여하지만 스스로 위치를 지정합니다. 다른 모델을 옆으로 이동시켜 공간을 확보할 수 있지만, 다른 모델을 위해 이동되지는 않습니다. 순서는 어느 쪽이든 작동합니다 — 이 기능을 활성화하기 전에 또는 후에 group offload를 수행할 수 있습니다. AutoOffloadStrategy는 모델의 메모리 사용량에 따라 결정을 내리지만, 이는 한 번에 하나의 그룹만 보유하는 모델을 설명하지 않으므로, 워크플로에 따라 결정을 내리는 offload_strategy를 전달하세요.

get_components_by_ids

( ids: list[str]return_dict_with_names: bool | None = True ) → dict[str, Any]

매개변수

ids (list[str]) — 구성 요소 ID 목록
return_dict_with_names (bool | None) — 구성 요소 이름을 키로 하는 사전(dict)을 반환할지 여부:

반환값

dict[str, Any]

구성 요소 사전.

return_dict_with_names=True인 경우, 키는 구성 요소 이름입니다.
If return_dict_with_names=False, keys are component IDs.

Raises

ValueError

ValueError — return_dict_with_names=True일 때 검색 결과에서 중복된 컴포넌트 이름이 발견되면

ID 목록으로 컴포넌트를 가져옵니다.

get_components_by_names

( names: list[str]collection: str | None = None ) → dict[str, Any]

매개변수

names (list[str]) — 구성 요소 이름 목록
collection (str | None) — 필터링할 선택적 collection

반환값

dict[str, Any]

컴포넌트 이름을 키로 사용하는 컴포넌트 사전

Raises

ValueError

ValueError — 검색 결과에서 중복된 구성 요소 이름이 발견된 경우

collection으로 필터링할 수 있는 이름 목록으로 컴포넌트를 가져옵니다.

get_ids

( names: str | list[str] = Nonecollection: str | None = None ) → list[str]

매개변수

names (str | list[str]) — 구성 요소 이름 목록
collection (str | None) — 필터링할 선택적 collection

반환값

list[str]

컴포넌트 ID 목록

collection으로 필터링할 수 있는 이름 목록으로 컴포넌트 ID를 가져옵니다.

get_model_info

( component_id: strfields: str | list[str] | None = None )

매개변수

component_id (str) — 정보를 가져올 컴포넌트의 이름
fields (str | list[str] | None) — 반환할 필드입니다. 단일 필드의 경우 문자열, 여러 필드의 경우 필드 목록을 사용할 수 있습니다. None인 경우 available_info_fields 설정을 사용합니다.

컴포넌트에 대한 포괄적인 정보를 가져옵니다.

get_one

( component_id: str | None = Nonename: str | None = Nonecollection: str | None = Noneload_id: str | None = None )

매개변수

component_id (str | None) — 가져올 선택적 컴포넌트 ID
name (str | None) — 컴포넌트 이름 또는 패턴
collection (str | None) — 필터링할 선택적 collection
load_id (str | None) — 필터링에 사용할 선택적 load_id

Raises

ValueError

ValueError — 구성 요소가 하나도 일치하지 않거나 여러 구성 요소가 일치하는 경우

다음 중 하나로 단일 구성 요소를 가져옵니다:

이름 검색(패턴 매칭), collection 또는 load_id.
component_id를 전달합니다. 여러 컴포넌트가 일치하거나 하나도 찾られない 경우 오류를 발생시킵니다.

제거

( component_id: str = None )

매개변수

component_id (str) — 제거할 컴포넌트의 ID

ComponentsManager에서 구성 요소를 제거합니다.

remove_from_collection

( component_id: strcollection: str )

컬렉션에서 구성 요소를 제거합니다.

search_components

( names: str | None = Nonecollection: str | None = Noneload_id: str | None = Nonereturn_dict_with_names: bool = True )

매개변수

names — 컴포넌트 이름 또는 패턴 패턴:
- “unet”: 기본 이름이 “unet”인 모든 구성 요소와 일치 (예: unet_123abc)
- “!unet”: 기본 이름이 “unet”인 구성 요소를 제외한 모든 것
- “unet*”: 기본 이름이 “unet”으로 시작하는 모든 항목
- “!unet*” : 기본 이름이 “unet”으로 시작하지 않는 모든 항목
- ”unet” : 기본 이름에 “unet”을 포함하는 모든 항목
- “!unet” : “unet”가 포함되지 않은 base name
- “refiner|vae|unet” : 기본 이름이 “refiner”, “vae”, “unet”과 정확히 일치하는 모든 항목
- “!refiner|vae|unet” : 기본 이름이 “refiner”, “vae”, “unet”과 정확히 일치하지 않는 모든 항목
- “unet|vae” : 기본 이름이 “unet”로 시작하거나 “vae”로 시작하는 모든 항목
collection — 필터링할 선택적 collection
load_id — 필터링에 사용할 선택적 load_id
return_dict_with_names — True인 경우, 구성 요소 이름을 키로 하는 딕셔너리를 반환하며, 동일한 이름을 가진 여러 구성 요소가 발견되면 오류를 발생시킵니다. False인 경우, 구성 요소 ID를 키로 하는 딕셔너리를 반환합니다.

simple pattern matching을 사용하여 이름으로 컴포넌트를 검색합니다. 선택적으로 collection 또는 load_id로 필터링할 수 있습니다.

set_offload_strategy

( offload_strategy )

매개변수

offload_strategy — (hooks, model_id, model, execution_device) -> hooks 시그니처를 가진 임의의 callable입니다. 현재 디바이스에 있는 모델들의 hooks를 받아오고, 들어오는 모델이 로드되기 전에 오프로드할 hooks를 반환합니다. 기본값은 AutoOffloadStrategy이며, 가장 작은 충분한 조합을 해제합니다.

관리되는 모든 모델의 offload 전략을 교체합니다. 자동 CPU offloading이 활성화된 상태에서만 유효합니다.

InsertableDict

class diffusers.modular_pipelines.InsertableDict

( )

Update on GitHub

←상태 가이드→