diffusers/main/ko/api/modular_diffusers/pipeline_components.md

컴포넌트 및 구성

ComponentSpec[[diffusers.ComponentSpec]]

diffusers.ComponentSpec[[diffusers.ComponentSpec]]

diffusers.ComponentSpec(name: str | None = None, type_hint: typing.Optional[typing.Type] = None, description: str | None = None, config: diffusers.configuration_utils.FrozenDict | None = None, pretrained_model_name_or_path: str | list[str] | None = None, subfolder: str | None = '', variant: str | None = None, revision: str | None = None, default_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의 선택적 변형

revision : pretrained_model_name_or_path의 선택적 리비전

default_creation_method : 권장 생성 방법 - "from_config" 또는 "from_pretrained"

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

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

1. 설정 딕셔너리를 사용하여 __init__로 처음부터
2. from_pretrained를 사용하여

생성[[diffusers.ComponentSpec.create]]

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

소스

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

decode_load_id[[diffusers.ComponentSpec.decode_load_id]]

decode_load_id(load_id: str)

소스

매개변수:

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

반환값:

Dict mapping loading field names to their values. e.g. { "pretrained_model_name_or_path": "path/to/repo", "subfolder": "subfolder", "variant": "variant", "revision": "revision" } If a segment value is "null", it's replaced with None. Returns None if load_id is "null" (indicating component not created with load method).

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

from_component[[diffusers.ComponentSpec.from_component]]

from_component(name: str, component: Any)

소스

매개변수:

name : 구성 요소의 이름

component : spec을 생성할 컴포넌트 객체

반환값:

ComponentSpec 객체

예외: ValueError

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

Component에서 ComponentSpec을 생성합니다.

현재 지원:

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

load[[diffusers.ComponentSpec.load]]

load(**kwargs)

소스

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

loading_fields[[diffusers.ComponentSpec.loading_fields]]

loading_fields()

소스

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

ConfigSpec[[diffusers.ConfigSpec]]

diffusers.ConfigSpec[[diffusers.ConfigSpec]]

diffusers.ConfigSpec(name: str, default: Any, description: str | None = None)

소스

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

ComponentsManager[[diffusers.ComponentsManager]]

diffusers.ComponentsManager[[diffusers.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")

추가[[diffusers.ComponentsManager.add]]

add(name: str, component: Any, collection: str | None = None)

소스

매개변수:

name (str) : 컴포넌트의 이름

component (Any) : 추가할 컴포넌트

collection (str | None) : 구성 요소를 추가할 컬렉션

반환값: str

Python의 내장 객체 고유 식별자인 id(component)를 사용하여 "{name}_{id(component)}" 형식으로 생성되는 고유한 컴포넌트 ID

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

disable_auto_cpu_offload[[diffusers.ComponentsManager.disable_auto_cpu_offload]]

disable_auto_cpu_offload()

소스

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

enable_auto_cpu_offload[[diffusers.ComponentsManager.enable_auto_cpu_offload]]

enable_auto_cpu_offload(device: str | int | torch.device = None, memory_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 시그니처를 가진 호출 가능한 객체로, 새로 로드될 모델이 로드되기 전에 오프로드할 레지던트 모델을 반환합니다. 기본값은 AutoOffloadStrategy이며, 가장 작은 충분한 조합을 해제합니다.

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

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

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

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

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

get_components_by_ids[[diffusers.ComponentsManager.get_components_by_ids]]

get_components_by_ids(ids: list[str], return_dict_with_names: bool | None = True)

소스

매개변수:

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.

예외: ValueError

• ValueError -- return_dict_with_names=True일 때 검색 결과에서 중복된 구성 요소 이름이 발견되면

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

get_components_by_names[[diffusers.ComponentsManager.get_components_by_names]]

get_components_by_names(names: list[str], collection: str | None = None)

소스

매개변수:

names (list[str]) : 구성 요소 이름 목록

collection (str | None) : 필터링할 선택적 컬렉션

반환값: dict[str, Any]

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

예외: ValueError

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

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

get_ids[[diffusers.ComponentsManager.get_ids]]

get_ids(names: str | list[str] = None, collection: str | None = None)

소스

매개변수:

names (str | list[str]) : 구성 요소 이름 목록

collection (str | None) : 필터링할 선택적 컬렉션

반환값: list[str]

컴포넌트 ID 목록

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

get_model_info[[diffusers.ComponentsManager.get_model_info]]

get_model_info(component_id: str, fields: str | list[str] | None = None)

소스

매개변수:

component_id (str) : 정보를 가져올 컴포넌트의 이름

fields (str | list[str] | None) : 반환할 필드입니다. 단일 필드의 경우 문자열, 여러 필드의 경우 필드 목록을 사용할 수 있습니다. None인 경우 available_info_fields 설정을 사용합니다.

반환값:

요청한 구성 요소 메타데이터를 포함하는 사전입니다. fields가 지정된 경우 해당 필드만 반환합니다. 그렇지 않으면 모든 필드를 반환합니다.

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

get_one[[diffusers.ComponentsManager.get_one]]

get_one(component_id: str | None = None, name: str | None = None, collection: str | None = None, load_id: str | None = None)

소스

매개변수:

component_id (str | None) : 가져올 선택적 component ID

name (str | None) : 컴포넌트 이름 또는 패턴

collection (str | None) : 필터링할 선택적 컬렉션

load_id (str | None) : 필터링에 사용할 선택적 load_id

반환값:

단일 구성 요소

예외: ValueError

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

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

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

제거[[diffusers.ComponentsManager.remove]]

remove(component_id: str = None)

소스

매개변수:

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

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

remove_from_collection[[diffusers.ComponentsManager.remove_from_collection]]

remove_from_collection(component_id: str, collection: str)

소스

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

search_components[[diffusers.ComponentsManager.search_components]]

search_components(names: str | None = None, collection: str | None = None, load_id: str | None = None, return_dict_with_names: bool = True)

소스

매개변수:

names : 컴포넌트 이름 또는 패턴 패턴: - "unet" : 기본 이름이 "unet"인 모든 컴포넌트와 일치 (예: unet_123abc) - "!unet" : 기본 이름이 "unet"인 컴포넌트를 제외한 모든 것 - "unet*" : 기본 이름이 "unet"으로 시작하는 모든 것 - "!unet*" : 기본 이름이 "unet"으로 시작하지 않는 모든 것 - "unet" : 기본 이름에 "unet"을 포함하는 모든 것 - "!unet" : 기본 이름에 "unet"을 포함하지 않는 모든 것 - "refiner|vae|unet" : 기본 이름이 "refiner", "vae", 또는 "unet"과 정확히 일치하는 모든 것 - "!refiner|vae|unet" : 기본 이름이 "refiner", "vae", 또는 "unet"과 정확히 일치하지 않는 모든 것 - "unet*|vae*" : 기본 이름이 "unet"으로 시작하거나 "vae"로 시작하는 모든 것

collection : 필터링할 선택적 컬렉션

load_id : 필터링을 위한 선택적 load_id

return_dict_with_names : True인 경우, 구성 요소 이름을 키로 하는 딕셔너리를 반환하며, 동일한 이름을 가진 여러 구성 요소가 발견되면 오류를 발생시킵니다. False인 경우, 구성 요소 ID를 키로 하는 딕셔너리를 반환합니다

반환값:

Dictionary mapping component names to components if return_dict_with_names=True, or a dictionary mapping component IDs to components if return_dict_with_names=False

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

set_offload_strategy[[diffusers.ComponentsManager.set_offload_strategy]]

set_offload_strategy(offload_strategy)

소스

매개변수:

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

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

InsertableDict[[diffusers.modular_pipelines.InsertableDict]]

diffusers.modular_pipelines.InsertableDict[[diffusers.modular_pipelines.InsertableDict]]

소스