Buckets:

hf-doc-build
/

doc

Files

xet

hf-doc-build/doc / diffusers /main /ko /modular_diffusers /components_manager.md

mishig

about 7 hours ago

preview code

download

raw

5.56 kB

# ComponentsManager

> [!WARNING]
> [ComponentsManager](/docs/diffusers/main/ko/api/modular_diffusers/pipeline_components#diffusers.ComponentsManager)은 아직 활발한 개발 단계에 있으며 API가 변경될 수 있습니다.

[ComponentsManager](/docs/diffusers/main/ko/api/modular_diffusers/pipeline_components#diffusers.ComponentsManager)는 Modular Diffusers의 모델 레지스트리 및 관리 시스템입니다. 모델을 추가하고 추적하며, 유용한 메타데이터(모델 크기, 디바이스 배치, 어댑터)를 저장하고, 오프로딩을 지원합니다.

이 가이드에서는 [ComponentsManager](/docs/diffusers/main/ko/api/modular_diffusers/pipeline_components#diffusers.ComponentsManager)를 사용하여 컴포넌트와 디바이스 메모리를 관리하는 방법을 보여줍니다.

## 파이프라인에 연결

Create a [ComponentsManager](/docs/diffusers/main/ko/api/modular_diffusers/pipeline_components#diffusers.ComponentsManager) and pass it to a [ModularPipeline](/docs/diffusers/main/ko/api/modular_diffusers/pipeline#diffusers.ModularPipeline) with either [from_pretrained()](/docs/diffusers/main/ko/api/modular_diffusers/pipeline#diffusers.ModularPipeline.from_pretrained) or [init_pipeline()](/docs/diffusers/main/ko/api/modular_diffusers/pipeline_blocks#diffusers.ModularPipelineBlocks.init_pipeline).

```py
from diffusers import ModularPipeline, ComponentsManager
import torch
manager = ComponentsManager()
pipe = ModularPipeline.from_pretrained("Tongyi-MAI/Z-Image-Turbo", components_manager=manager)
pipe.load_components(dtype=torch.bfloat16)
```

```py
from diffusers import ModularPipelineBlocks, ComponentsManager
import torch
manager = ComponentsManager()
blocks = ModularPipelineBlocks.from_pretrained("diffusers/Florence2-image-Annotator", trust_remote_code=True)
pipe= blocks.init_pipeline(components_manager=manager)
pipe.load_components(dtype=torch.bfloat16)
```

pipeline에 의해 로드된 Components는 자동으로 manager에 등록됩니다. 바로 검사할 수 있습니다.

## 구성 요소 검사

등록된 모든 컴포넌트와 해당 클래스, 디바이스 배치, dtype, 메모리 크기, 로드 ID를 확인하려면 [ComponentsManager](/docs/diffusers/main/ko/api/modular_diffusers/pipeline_components#diffusers.ComponentsManager)를 출력합니다.

아래의 출력은 위의 `from_pretrained` 예제에 해당합니다.

```py
Components:
=============================================================================================================================
Models:
-----------------------------------------------------------------------------------------------------------------------------
Name_ID                      | Class                    | Device: act(exec) | Dtype          | Size (GB) | Load ID
-----------------------------------------------------------------------------------------------------------------------------
text_encoder_140458257514752 | Qwen3Model               | cpu               | torch.bfloat16 | 7.49      | Tongyi-MAI/Z-Image-Turbo|text_encoder|null|null
vae_140458257515376          | AutoencoderKL            | cpu               | torch.bfloat16 | 0.16      | Tongyi-MAI/Z-Image-Turbo|vae|null|null
transformer_140458257515616  | ZImageTransformer2DModel | cpu               | torch.bfloat16 | 11.46     | Tongyi-MAI/Z-Image-Turbo|transformer|null|null
-----------------------------------------------------------------------------------------------------------------------------
Other Components:
-----------------------------------------------------------------------------------------------------------------------------
ID                           | Class                           | Collection
-----------------------------------------------------------------------------------------------------------------------------
scheduler_140461023555264    | FlowMatchEulerDiscreteScheduler | N/A
tokenizer_140458256346432    | Qwen2Tokenizer                  | N/A
-----------------------------------------------------------------------------------------------------------------------------
```

… 테이블은 모델(디바이스, dtype, 메모리 정보 포함)을 스케줄러나 토크나이저와 같은 다른 컴포넌트와 별도로 표시합니다. 모델에 LoRA 어댑터, IP-Adapter 또는 양자화가 적용된 경우, 해당 정보는 하단의 추가 섹션에 표시됩니다.

## 오프로딩

[enable_auto_cpu_offload()](/docs/diffusers/main/ko/api/modular_diffusers/pipeline_components#diffusers.ComponentsManager.enable_auto_cpu_offload) 메서드는 어떤 파이프라인이 모델을 사용하든 상관없이 모든 모델에 걸쳐 작동하는 전역 오프로딩 전략입니다. 활성화된 후에는 구성 요소를 추가하거나 제거하더라도 디바이스 배치에 대해 걱정할 필요가 없습니다.

```py
manager.enable_auto_cpu_offload(device="cuda")  # or "mps", "xpu", "cpu"
```

모든 모델은 CPU에서 시작하며, [ComponentsManager](/docs/diffusers/main/ko/api/modular_diffusers/pipeline_components#diffusers.ComponentsManager)는 모델이 필요해지는 시점 직전에 해당 모델을 적절한 장치로 이동하고, GPU 메모리가 부족할 경우 다른 모델을 다시 CPU로 이동합니다.

[disable_auto_cpu_offload()](/docs/diffusers/main/ko/api/modular_diffusers/pipeline_components#diffusers.ComponentsManager.disable_auto_cpu_offload)를 호출하여 오프로딩을 비활성화합니다.

```py
manager.disable_auto_cpu_offload()
```

Xet Storage Details

Size:: 5.56 kB
Xet hash:: 578cadcb582ab155494816cbbdbb91348b597066be07fef594f03c9ef7f9571a

Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.

	# ComponentsManager

	> [!WARNING]
	> [ComponentsManager](/docs/diffusers/main/ko/api/modular_diffusers/pipeline_components#diffusers.ComponentsManager)은 아직 활발한 개발 단계에 있으며 API가 변경될 수 있습니다.

	[ComponentsManager](/docs/diffusers/main/ko/api/modular_diffusers/pipeline_components#diffusers.ComponentsManager)는 Modular Diffusers의 모델 레지스트리 및 관리 시스템입니다. 모델을 추가하고 추적하며, 유용한 메타데이터(모델 크기, 디바이스 배치, 어댑터)를 저장하고, 오프로딩을 지원합니다.

	이 가이드에서는 [ComponentsManager](/docs/diffusers/main/ko/api/modular_diffusers/pipeline_components#diffusers.ComponentsManager)를 사용하여 컴포넌트와 디바이스 메모리를 관리하는 방법을 보여줍니다.

	## 파이프라인에 연결

	Create a [ComponentsManager](/docs/diffusers/main/ko/api/modular_diffusers/pipeline_components#diffusers.ComponentsManager) and pass it to a [ModularPipeline](/docs/diffusers/main/ko/api/modular_diffusers/pipeline#diffusers.ModularPipeline) with either [from_pretrained()](/docs/diffusers/main/ko/api/modular_diffusers/pipeline#diffusers.ModularPipeline.from_pretrained) or [init_pipeline()](/docs/diffusers/main/ko/api/modular_diffusers/pipeline_blocks#diffusers.ModularPipelineBlocks.init_pipeline).

	```py
	from diffusers import ModularPipeline, ComponentsManager
	import torch

	manager = ComponentsManager()
	pipe = ModularPipeline.from_pretrained("Tongyi-MAI/Z-Image-Turbo", components_manager=manager)
	pipe.load_components(dtype=torch.bfloat16)
	```

	```py
	from diffusers import ModularPipelineBlocks, ComponentsManager
	import torch
	manager = ComponentsManager()
	blocks = ModularPipelineBlocks.from_pretrained("diffusers/Florence2-image-Annotator", trust_remote_code=True)
	pipe= blocks.init_pipeline(components_manager=manager)
	pipe.load_components(dtype=torch.bfloat16)
	```

	pipeline에 의해 로드된 Components는 자동으로 manager에 등록됩니다. 바로 검사할 수 있습니다.

	## 구성 요소 검사

	등록된 모든 컴포넌트와 해당 클래스, 디바이스 배치, dtype, 메모리 크기, 로드 ID를 확인하려면 [ComponentsManager](/docs/diffusers/main/ko/api/modular_diffusers/pipeline_components#diffusers.ComponentsManager)를 출력합니다.

	아래의 출력은 위의 `from_pretrained` 예제에 해당합니다.

	```py
	Components:
	=============================================================================================================================
	Models:
	-----------------------------------------------------------------------------------------------------------------------------
	Name_ID \| Class \| Device: act(exec) \| Dtype \| Size (GB) \| Load ID
	-----------------------------------------------------------------------------------------------------------------------------
	text_encoder_140458257514752 \| Qwen3Model \| cpu \| torch.bfloat16 \| 7.49 \| Tongyi-MAI/Z-Image-Turbo\|text_encoder\|null\|null
	vae_140458257515376 \| AutoencoderKL \| cpu \| torch.bfloat16 \| 0.16 \| Tongyi-MAI/Z-Image-Turbo\|vae\|null\|null
	transformer_140458257515616 \| ZImageTransformer2DModel \| cpu \| torch.bfloat16 \| 11.46 \| Tongyi-MAI/Z-Image-Turbo\|transformer\|null\|null
	-----------------------------------------------------------------------------------------------------------------------------

	Other Components:
	-----------------------------------------------------------------------------------------------------------------------------
	ID \| Class \| Collection
	-----------------------------------------------------------------------------------------------------------------------------
	scheduler_140461023555264 \| FlowMatchEulerDiscreteScheduler \| N/A
	tokenizer_140458256346432 \| Qwen2Tokenizer \| N/A
	-----------------------------------------------------------------------------------------------------------------------------
	```

	… 테이블은 모델(디바이스, dtype, 메모리 정보 포함)을 스케줄러나 토크나이저와 같은 다른 컴포넌트와 별도로 표시합니다. 모델에 LoRA 어댑터, IP-Adapter 또는 양자화가 적용된 경우, 해당 정보는 하단의 추가 섹션에 표시됩니다.

	## 오프로딩

	[enable_auto_cpu_offload()](/docs/diffusers/main/ko/api/modular_diffusers/pipeline_components#diffusers.ComponentsManager.enable_auto_cpu_offload) 메서드는 어떤 파이프라인이 모델을 사용하든 상관없이 모든 모델에 걸쳐 작동하는 전역 오프로딩 전략입니다. 활성화된 후에는 구성 요소를 추가하거나 제거하더라도 디바이스 배치에 대해 걱정할 필요가 없습니다.

	```py
	manager.enable_auto_cpu_offload(device="cuda") # or "mps", "xpu", "cpu"
	```

	모든 모델은 CPU에서 시작하며, [ComponentsManager](/docs/diffusers/main/ko/api/modular_diffusers/pipeline_components#diffusers.ComponentsManager)는 모델이 필요해지는 시점 직전에 해당 모델을 적절한 장치로 이동하고, GPU 메모리가 부족할 경우 다른 모델을 다시 CPU로 이동합니다.

	[disable_auto_cpu_offload()](/docs/diffusers/main/ko/api/modular_diffusers/pipeline_components#diffusers.ComponentsManager.disable_auto_cpu_offload)를 호출하여 오프로딩을 비활성화합니다.

	```py
	manager.disable_auto_cpu_offload()
	```