Buckets:

hf-doc-build
/

doc

Files

xet

hf-doc-build/doc / diffusers /main /ko /api /utilities.md

mishig

about 7 hours ago

preview code

download

raw

19 kB

# 유틸리티

🤗 Diffusers를 다루기 위한 유틸리티 및 헬퍼 함수

## numpy_to_pil[[diffusers.utils.numpy_to_pil]]

#### diffusers.utils.numpy_to_pil[[diffusers.utils.numpy_to_pil]]

```python
diffusers.utils.numpy_to_pil(images)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/utils/pil_utils.py#L35)

numpy 이미지 또는 이미지 배치 하나를 PIL 이미지로 변환합니다.

## pt_to_pil[[diffusers.utils.pt_to_pil]]

#### diffusers.utils.pt_to_pil[[diffusers.utils.pt_to_pil]]

```python
diffusers.utils.pt_to_pil(images)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/utils/pil_utils.py#L25)

torch 이미지를 PIL 이미지로 변환합니다.

## load_image[[diffusers.utils.load_image]]

#### diffusers.utils.load_image[[diffusers.utils.load_image]]

```python
diffusers.utils.load_image(image: str | PIL.Image.Image, convert_method: typing.Optional[typing.Callable[[PIL.Image.Image], PIL.Image.Image]] = None)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/utils/loading_utils.py#L14)

**매개변수:**

image (`str` 또는 `PIL.Image.Image`) : PIL Image 형식으로 변환할 이미지.

convert_method (Callable[[PIL.Image.Image], PIL.Image.Image], *선택 사항*) : 이미지를 로드한 후 적용할 변환 방법입니다. `None`으로 설정하면 이미지는 "RGB"로 변환됩니다.
**반환값:** `PIL.Image.Image`
PIL 이미지입니다.
`image`를 PIL Image로 로드합니다.
## load_video[[diffusers.utils.load_video]]
#### diffusers.utils.load_video[[diffusers.utils.load_video]]
```python
diffusers.utils.load_video(video: str, convert_method: typing.Optional[typing.Callable[[list[PIL.Image.Image]], list[PIL.Image.Image]]] = None, return_fps: bool = False)
```
[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/utils/loading_utils.py#L57)
**매개변수:**
video (`str`) : PIL Image 형식의 리스트로 변환할 비디오의 URL 또는 경로.
convert_method (Callable[[list[PIL.Image.Image]], list[PIL.Image.Image]], *선택 사항*) : 비디오를 로드한 후 적용할 변환 메서드입니다. `None`으로 설정하면 이미지가 "RGB"로 변환됩니다.
return_fps (`bool`, *선택 사항*, 기본값 `False`) : 비디오가 인코딩된 프레임 레이트도 반환할지 여부입니다. 프레임 목록에는 해당 정보가 포함되지 않으므로, 입력을 모델이 동작하는 프레임 레이트로 리샘플링하는 파이프라인에 필요합니다.
**반환값:** `list[PIL.Image.Image]` 또는 `tuple[list[PIL.Image.Image], float]`
`return_fps`가 설정된 경우, PIL 이미지 목록으로 구성된 비디오와 해당 프레임 레이트를 반환합니다.
`video`를 PIL Image 목록으로 로드합니다.
## export_to_gif[[diffusers.utils.export_to_gif]]
#### diffusers.utils.export_to_gif[[diffusers.utils.export_to_gif]]
```python
diffusers.utils.export_to_gif(image: list[PIL.Image.Image], output_gif_path: str = None, fps: int = 10)
```
[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/utils/export_utils.py#L37)
## export_to_video[[diffusers.utils.export_to_video]]
#### diffusers.utils.export_to_video[[diffusers.utils.export_to_video]]
```python
diffusers.utils.export_to_video(video_frames: list[np.ndarray] | list[PIL.Image.Image], output_video_path: str = None, fps: int = 10, quality: float = 5.0, bitrate: int | None = None, macro_block_size: int | None = 16)
```
[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/utils/export_utils.py#L150)
quality: Video output quality. Default is 5. Uses variable bit rate. Highest quality is 10, lowest is 0. Set to None to prevent variable bitrate flags to FFMPEG so you can manually specify them using output_params instead. Specifying a fixed bitrate using `bitrate` disables this parameter.

bitrate: 비디오 인코딩에 사용할 고정 비트레이트를 설정합니다. 기본값은 None이며, 이 경우 `quality` 매개변수가 대신 사용됩니다. 이 매개변수로 고정 비트레이트를 지정하는 것보다 `quality` 가변 비트레이트 매개변수를 사용하는 것이 더 작은 파일 크기로 더 높은 품질의 비디오를 생성합니다.

macro_block_size: 비디오에 대한 크기 제약입니다. 너비와 높이는 이 숫자로 나누어떨어져야 합니다. 이 숫자로 나누어떨어지지 않으면 imageio는 ffmpeg에 이 숫자로 나누어떨어지는 가장 가까운 다음 크기로 이미지를 확대하도록 지시합니다. 대부분의 코덱은 매크로블록 크기 16(기본값)과 호환되며, 일부는 더 작은 값(4, 8)을 사용할 수 있습니다. 이 자동 기능을 비활성화하려면 None 또는 1로 설정하십시오. 그러나 크기가 홀수인 비디오를 디코딩할 수 없는 재생기가 많고, 일부 코덱은 품질이 저하되거나 실패할 수 있으므로 주의하십시오. https://en.wikipedia.org/wiki/Macroblock을 참조하십시오.

## encode_video[[diffusers.utils.encode_video]]

#### diffusers.utils.encode_video[[diffusers.utils.encode_video]]

```python
diffusers.utils.encode_video(video: list[PIL.Image.Image] | np.ndarray | 'torch.Tensor' | Iterator['torch.Tensor'], fps: int, output_path: str, audio: 'torch.Tensor' | None = None, audio_sample_rate: int | None = None, video_chunks_number: int = 1)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/utils/export_utils.py#L304)

**매개변수:**

video (`List[PIL.Image.Image]` 또는 `np.ndarray` 또는 `torch.Tensor`) : [0, 255] 범위의 정수 픽셀 값을 가진 [frames, height, width, channels] 형태의 비디오 텐서입니다. 입력이 `np.ndarray`인 경우, [0, 1] 범위의 값으로 구성된 float 배열이어야 합니다(파이프라인이 `output_type="np"`로 반환하는 일반적인 형태입니다).

fps (`int`) : 인코딩된 비디오의 초당 프레임 수(FPS).

output_path (`str`) : 인코딩된 비디오를 저장할 경로.
audio (`torch.Tensor`, *선택 사항*) : [audio_channels, samples] 형태의 오디오 웨이브폼입니다.

audio_sample_rate : (`int`, *선택 사항*): 오디오 웨이브폼의 샘플링 레이트입니다.

video_chunks_number (`int`, *optional*, 기본값 `1`) : 인코딩을 위해 비디오를 분할할 청크의 수입니다. 각 청크는 개별적으로 인코딩됩니다. 사용할 청크의 수는 비디오 VAE의 타일링 구성에 따라 달라지는 경우가 많습니다.

PyAV 라이브러리를 사용하여 선택적 오디오와 함께 비디오를 인코딩합니다. 원래 LTX-2 저장소의 코드를 기반으로 합니다: https://github.com/Lightricks/LTX-2/blob/4f410820b198e05074a1e92de793e3b59e9ab5a0/packages/ltx-pipelines/src/ltx_pipelines/utils/media_io.py#L182

## make_image_grid[[diffusers.utils.make_image_grid]]

#### diffusers.utils.make_image_grid[[diffusers.utils.make_image_grid]]

```python
diffusers.utils.make_image_grid(images: list, rows: int, cols: int, resize: int = None)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/utils/pil_utils.py#L51)

이미지 그리드 하나를 준비합니다. 시각화 목적으로 유용합니다.

## randn_tensor[[diffusers.utils.torch_utils.randn_tensor]]
#### diffusers.utils.torch_utils.randn_tensor[[diffusers.utils.torch_utils.randn_tensor]]
```python
diffusers.utils.torch_utils.randn_tensor(shape: tuple | list, generator: list['torch.Generator'] | 'torch.Generator' | None = None, device: str | 'torch.device' | None = None, dtype: 'torch.dtype' | None = None, layout: 'torch.layout' | None = None)
```
[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/utils/torch_utils.py#L61)
원하는 `device`와 `dtype`을 가진 랜덤 텐서를 생성하는 헬퍼 함수입니다. 생성기 목록을 전달하면 각 배치 크기를 개별적으로 시드할 수 있습니다. CPU 생성기가 전달되면 텐서는 항상 CPU에서 생성됩니다.
## TorchDeviceBackend[[diffusers.utils.torch_utils.TorchDeviceBackend]]

#### diffusers.utils.torch_utils.TorchDeviceBackend[[diffusers.utils.torch_utils.TorchDeviceBackend]]

```python
diffusers.utils.torch_utils.TorchDeviceBackend(device: str | torch.device | None = None)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/utils/torch_utils.py#L228)

하나의 장치에 대한 `torch.<backend>` 네임스페이스(`torch.cuda`, `torch.xpu`, `torch.mps`, ...)의 프록시입니다. 이 클래스가 정의하지 않은 속성은 모듈 자체의 속성(`synchronize`, `device_count`, `Stream`, `current_stream`, ...)이며, 여기서 정의된 메서드는 백엔드 간 가용성이 달라 폴백이 필요한 연산을 오버라이드합니다: 캐시 정리, 시드 설정 및 메모리 조회. `device`가 없으면 `torch.accelerator`를 통해 호스트 가속기를 감지합니다. torch에 해당 백엔드 모듈이 없으면 `torch.cuda`로 조용히 폴백하는 대신 예외를 발생시킵니다.

#### max_memory_allocated[[diffusers.utils.torch_utils.TorchDeviceBackend.max_memory_allocated]]
```python
max_memory_allocated()
```
[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/utils/torch_utils.py#L291)
마지막 리셋 이후 디바이스에 할당된 피크 메모리(바이트 단위); 백엔드가 통계를 유지하지 않는 경우 0.
#### mem_get_info[[diffusers.utils.torch_utils.TorchDeviceBackend.mem_get_info]]

```python
mem_get_info()
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/utils/torch_utils.py#L279)

바이트 단위의 가용 및 전체 디바이스 메모리.

## apply_layerwise_casting[[diffusers.hooks.apply_layerwise_casting]]

#### diffusers.hooks.apply_layerwise_casting[[diffusers.hooks.apply_layerwise_casting]]

```python
diffusers.hooks.apply_layerwise_casting(module: Module, storage_dtype: dtype, compute_dtype: dtype, skip_modules_pattern: str | tuple[str, ...] = 'auto', skip_modules_classes: tuple[typing.Type[torch.nn.Module], ...] | None = None, non_blocking: bool = False)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/hooks/layerwise_casting.py#L101)

**매개변수:**

module (`torch.nn.Module`) : 계산 시 리프 모듈을 고정밀 dtype으로, 저장 시 저정밀 dtype으로 캐스팅할 모듈입니다.

storage_dtype (`torch.dtype`) : 저장하기 위해 forward pass 전/후에 모듈을 캐스팅할 dtype.
compute_dtype (`torch.dtype`) : forward pass에서 계산을 위해 모듈을 캐스트할 dtype입니다.

skip_modules_pattern (`tuple[str, ...]`, 기본값은 `"auto"`) : 레이어별 캐스팅 과정에서 건너뛸 모듈의 이름을 일치시키기 위한 패턴 목록입니다. `"auto"`로 설정하면 기본 패턴이 사용됩니다. `None`으로 설정하면 어떤 모듈도 건너뛰지 않습니다. `None`으로 설정하고 `skip_modules_classes`도 `None`인 경우, 레이어별 캐스팅이 내부 하위 모듈이 아닌 모듈 자체에 직접 적용됩니다.

skip_modules_classes (`tuple[Type[torch.nn.Module], ...]`, 기본값은 `None`) : 레이어별 캐스팅 과정에서 건너뛸 모듈 클래스 목록입니다.

non_blocking (`bool`, 기본값은 `False`) : `True`인 경우, 가중치 캐스팅 작업이 비차단(non-blocking) 방식으로 수행됩니다.
Applies layerwise casting to a given module. The module expected here is a Diffusers ModelMixin but it can be any nn.Module using diffusers layers or pytorch primitives.
예:
```python
>>> import torch
>>> from diffusers import CogVideoXTransformer3DModel
>>> transformer = CogVideoXTransformer3DModel.from_pretrained(
...     model_id, subfolder="transformer", torch_dtype=torch.bfloat16
... )

>>> apply_layerwise_casting(
...     transformer,
...     storage_dtype=torch.float8_e4m3fn,
...     compute_dtype=torch.bfloat16,
...     skip_modules_pattern=["patch_embed", "norm", "proj_out"],
...     non_blocking=True,
... )
```
## apply_group_offloading[[diffusers.hooks.apply_group_offloading]]
#### diffusers.hooks.apply_group_offloading[[diffusers.hooks.apply_group_offloading]]
```python
diffusers.hooks.apply_group_offloading(module: Module, onload_device: typing.Union[str, torch.device], offload_device: typing.Union[str, torch.device] = torch.device(), offload_type: str | diffusers.hooks.group_offloading.GroupOffloadingType = 'block_level', num_blocks_per_group: int | None = None, non_blocking: bool = False, use_stream: bool = False, record_stream: bool = False, low_cpu_mem_usage: bool = False, offload_to_disk_path: str | None = None, block_modules: list[str] | None = None, exclude_kwargs: list[str] | None = None)
```
[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/hooks/group_offloading.py#L567)
**매개변수:**
module (`torch.nn.Module`) : 그룹 오프로딩이 적용되는 모듈입니다.
onload_device (`torch.device`) : 모듈 그룹이 로드된 디바이스.

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인 경우, offloading과 onloading이 non-blocking 데이터 전송으로 수행됩니다.
use_stream (`bool`, 기본값은 `False`) : True인 경우, CUDA 스트림을 사용하여 오프로딩과 온로딩을 비동기적으로 수행합니다. 이는 계산과 데이터 전송을 오버랩하는 데 유용할 수 있습니다.

record_stream (`bool`, 기본값은 `False`) : `use_stream`와 함께 활성화되면, 현재 텐서가 해당 스트림에 의해 사용되었음을 표시합니다. 메모리 사용량이 약간 증가하는 대신 더 빠른 성능을 제공합니다. 자세한 내용은 [PyTorch 공식 문서](https://pytorch.org/docs/stable/generated/torch.Tensor.record_stream.html)를 참조하세요.

low_cpu_mem_usage (`bool`, 기본값은 `False`) : True인 경우, 사전 고정 대신 텐서를 온더플라이로 고정하여 CPU 메모리 사용량을 최소화합니다. 이 옵션은 스트림된 CPU 오프로딩(즉, `use_stream=True`)을 사용할 때만 의미가 있습니다. CPU 메모리가 병목 현상을 일으키는 경우 유용할 수 있지만, 스트림 사용의 이점을 상쇄할 수도 있습니다.

block_modules (`list[str]`, *선택 사항*) : 오프로딩을 위한 블록으로 처리해야 할 모듈 이름 목록입니다. 제공된 경우, 블록 수준 오프로딩을 고려할 때 이 모듈들만 대상이 됩니다. 제공되지 않으면 기본 블록 감지 로직이 사용됩니다.
exclude_kwargs (`list[str]`, *optional*) : List of kwarg keys that should not be processed by send_to_device. This is useful for mutable state like caching lists that need to maintain their object identity across forward passes. If not provided, will be inferred from the module's `_skip_keys` attribute if it exists.

torch.nn.Module의 내부 레이어에 group offloading을 적용합니다. group offloading이 무엇인지, 그리고 어떤 상황에서 이점이 있는지 이해하려면, 먼저 다른 지원되는 offloading 방식이 어떻게 작동하는지에 대한 배경을 제공해야 합니다.

일반적으로 오프로딩은 두 단계에서 수행됩니다:
- Module-level: Diffusers에서는 `ModelMixin::enable_model_cpu_offload()` 메서드를 사용하여 이를 활성화할 수 있습니다. 이 메서드는 파이프라인의 각 구성 요소를 저장 목적으로 CPU로 offload하고, 계산이 필요할 때 accelerator device로 onload하는 방식으로 동작합니다. 이 메서드는 모든 구성 요소를 accelerator에 유지하는 것보다 메모리 효율이 높지만, 여전히 메모리 요구량이 상당히 높습니다. 이 메서드가 작동하려면 forward pass를 완료할 수 있도록 런타임 dtype 기준 모델 크기 + 가장 큰 중간 activation 텐서 크기에 해당하는 메모리가 필요합니다.
- Leaf-level: Diffusers에서는 `ModelMixin::enable_sequential_cpu_offload()` 메서드를 사용하여 이를 활성화할 수 있습니다. 이 방식은 계산 그래프의 가장 낮은 leaf-level 파라미터를 CPU로 offload하여 저장하고, 계산 시 leaf만 accelerator device로 onload하는 방식으로 동작합니다. 이 방식은 accelerator 메모리 사용량이 가장 적지만, 과도한 수의 device 동기화 때문에 속도가 느려질 수 있습니다.

Group offloading은 두 가지 방법의 중간 단계입니다. 내부 레이어 그룹(`torch.nn.ModuleList` 또는 `torch.nn.Sequential`)을 offload하는 방식으로 동작합니다. 이 방법은 모듈 수준 offloading보다 메모리 사용량이 적습니다. 또한 장치 동기화 횟수가 줄어들어 leaf 수준/순차적 offloading보다 빠릅니다.

CUDA 디바이스에서 비동기 데이터 전송 스트림을 지원하는 경우, 또 다른 지원되는 기능은 순차적 오프로딩과 비교하여 전체 실행 시간을 줄이기 위해 데이터 전송과 계산을 겹치게 하는 능력입니다. 이는 스트림을 사용한 레이어 프리페칭으로 활성화되며, 즉 현재 레이어가 실행되는 동안 다음으로 실행될 레이어가 가속기 디바이스로의 온로딩을 시작합니다 - 이로 인해 메모리 요구량이 약간 증가합니다. 이 구현은 리프 레벨 오프로딩도 지원하지만, 스트림을 사용할 때 훨씬 더 빨라질 수 있습니다.

예:
```python
>>> from diffusers import CogVideoXTransformer3DModel
>>> from diffusers.hooks import apply_group_offloading
>>> transformer = CogVideoXTransformer3DModel.from_pretrained(
...     "THUDM/CogVideoX-5b", subfolder="transformer", torch_dtype=torch.bfloat16
... )
>>> apply_group_offloading(
...     transformer,
...     onload_device=torch.device("cuda"),
...     offload_device=torch.device("cpu"),
...     offload_type="block_level",
...     num_blocks_per_group=2,
...     use_stream=True,
... )
```

Xet Storage Details

Size:: 19 kB
Xet hash:: ded9e5d19d6674beeef456fd43a9d0634b1dab494e3a2b2ec669575e009d1c2b

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

	# 유틸리티

	🤗 Diffusers를 다루기 위한 유틸리티 및 헬퍼 함수

	## numpy_to_pil[[diffusers.utils.numpy_to_pil]]

	#### diffusers.utils.numpy_to_pil[[diffusers.utils.numpy_to_pil]]

	```python
	diffusers.utils.numpy_to_pil(images)
	```

	[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/utils/pil_utils.py#L35)

	numpy 이미지 또는 이미지 배치 하나를 PIL 이미지로 변환합니다.

	## pt_to_pil[[diffusers.utils.pt_to_pil]]

	#### diffusers.utils.pt_to_pil[[diffusers.utils.pt_to_pil]]

	```python
	diffusers.utils.pt_to_pil(images)
	```

	[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/utils/pil_utils.py#L25)

	torch 이미지를 PIL 이미지로 변환합니다.

	## load_image[[diffusers.utils.load_image]]

	#### diffusers.utils.load_image[[diffusers.utils.load_image]]

	```python
	diffusers.utils.load_image(image: str \| PIL.Image.Image, convert_method: typing.Optional[typing.Callable[[PIL.Image.Image], PIL.Image.Image]] = None)
	```

	[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/utils/loading_utils.py#L14)

	매개변수:

	image (`str` 또는 `PIL.Image.Image`) : PIL Image 형식으로 변환할 이미지.

	convert_method (Callable[[PIL.Image.Image], PIL.Image.Image], 선택 사항) : 이미지를 로드한 후 적용할 변환 방법입니다. `None`으로 설정하면 이미지는 "RGB"로 변환됩니다.

	반환값: `PIL.Image.Image`

	PIL 이미지입니다.

	`image`를 PIL Image로 로드합니다.

	## load_video[[diffusers.utils.load_video]]

	#### diffusers.utils.load_video[[diffusers.utils.load_video]]

	```python
	diffusers.utils.load_video(video: str, convert_method: typing.Optional[typing.Callable[[list[PIL.Image.Image]], list[PIL.Image.Image]]] = None, return_fps: bool = False)
	```

	[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/utils/loading_utils.py#L57)

	매개변수:

	video (`str`) : PIL Image 형식의 리스트로 변환할 비디오의 URL 또는 경로.

	convert_method (Callable[[list[PIL.Image.Image]], list[PIL.Image.Image]], 선택 사항) : 비디오를 로드한 후 적용할 변환 메서드입니다. `None`으로 설정하면 이미지가 "RGB"로 변환됩니다.

	return_fps (`bool`, 선택 사항, 기본값 `False`) : 비디오가 인코딩된 프레임 레이트도 반환할지 여부입니다. 프레임 목록에는 해당 정보가 포함되지 않으므로, 입력을 모델이 동작하는 프레임 레이트로 리샘플링하는 파이프라인에 필요합니다.

	반환값: `list[PIL.Image.Image]` 또는 `tuple[list[PIL.Image.Image], float]`

	`return_fps`가 설정된 경우, PIL 이미지 목록으로 구성된 비디오와 해당 프레임 레이트를 반환합니다.

	`video`를 PIL Image 목록으로 로드합니다.

	## export_to_gif[[diffusers.utils.export_to_gif]]

	#### diffusers.utils.export_to_gif[[diffusers.utils.export_to_gif]]

	```python
	diffusers.utils.export_to_gif(image: list[PIL.Image.Image], output_gif_path: str = None, fps: int = 10)
	```

	[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/utils/export_utils.py#L37)

	## export_to_video[[diffusers.utils.export_to_video]]

	#### diffusers.utils.export_to_video[[diffusers.utils.export_to_video]]

	```python
	diffusers.utils.export_to_video(video_frames: list[np.ndarray] \| list[PIL.Image.Image], output_video_path: str = None, fps: int = 10, quality: float = 5.0, bitrate: int \| None = None, macro_block_size: int \| None = 16)
	```

	[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/utils/export_utils.py#L150)

	quality: Video output quality. Default is 5. Uses variable bit rate. Highest quality is 10, lowest is 0. Set to None to prevent variable bitrate flags to FFMPEG so you can manually specify them using output_params instead. Specifying a fixed bitrate using `bitrate` disables this parameter.

	bitrate: 비디오 인코딩에 사용할 고정 비트레이트를 설정합니다. 기본값은 None이며, 이 경우 `quality` 매개변수가 대신 사용됩니다. 이 매개변수로 고정 비트레이트를 지정하는 것보다 `quality` 가변 비트레이트 매개변수를 사용하는 것이 더 작은 파일 크기로 더 높은 품질의 비디오를 생성합니다.

	macro_block_size: 비디오에 대한 크기 제약입니다. 너비와 높이는 이 숫자로 나누어떨어져야 합니다. 이 숫자로 나누어떨어지지 않으면 imageio는 ffmpeg에 이 숫자로 나누어떨어지는 가장 가까운 다음 크기로 이미지를 확대하도록 지시합니다. 대부분의 코덱은 매크로블록 크기 16(기본값)과 호환되며, 일부는 더 작은 값(4, 8)을 사용할 수 있습니다. 이 자동 기능을 비활성화하려면 None 또는 1로 설정하십시오. 그러나 크기가 홀수인 비디오를 디코딩할 수 없는 재생기가 많고, 일부 코덱은 품질이 저하되거나 실패할 수 있으므로 주의하십시오. https://en.wikipedia.org/wiki/Macroblock을 참조하십시오.

	## encode_video[[diffusers.utils.encode_video]]

	#### diffusers.utils.encode_video[[diffusers.utils.encode_video]]

	```python
	diffusers.utils.encode_video(video: list[PIL.Image.Image] \| np.ndarray \| 'torch.Tensor' \| Iterator['torch.Tensor'], fps: int, output_path: str, audio: 'torch.Tensor' \| None = None, audio_sample_rate: int \| None = None, video_chunks_number: int = 1)
	```

	[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/utils/export_utils.py#L304)

	매개변수:

	video (`List[PIL.Image.Image]` 또는 `np.ndarray` 또는 `torch.Tensor`) : [0, 255] 범위의 정수 픽셀 값을 가진 [frames, height, width, channels] 형태의 비디오 텐서입니다. 입력이 `np.ndarray`인 경우, [0, 1] 범위의 값으로 구성된 float 배열이어야 합니다(파이프라인이 `output_type="np"`로 반환하는 일반적인 형태입니다).

	fps (`int`) : 인코딩된 비디오의 초당 프레임 수(FPS).

	output_path (`str`) : 인코딩된 비디오를 저장할 경로.

	audio (`torch.Tensor`, 선택 사항) : [audio_channels, samples] 형태의 오디오 웨이브폼입니다.

	audio_sample_rate : (`int`, 선택 사항): 오디오 웨이브폼의 샘플링 레이트입니다.

	video_chunks_number (`int`, optional, 기본값 `1`) : 인코딩을 위해 비디오를 분할할 청크의 수입니다. 각 청크는 개별적으로 인코딩됩니다. 사용할 청크의 수는 비디오 VAE의 타일링 구성에 따라 달라지는 경우가 많습니다.

	PyAV 라이브러리를 사용하여 선택적 오디오와 함께 비디오를 인코딩합니다. 원래 LTX-2 저장소의 코드를 기반으로 합니다: https://github.com/Lightricks/LTX-2/blob/4f410820b198e05074a1e92de793e3b59e9ab5a0/packages/ltx-pipelines/src/ltx_pipelines/utils/media_io.py#L182

	## make_image_grid[[diffusers.utils.make_image_grid]]

	#### diffusers.utils.make_image_grid[[diffusers.utils.make_image_grid]]

	```python
	diffusers.utils.make_image_grid(images: list, rows: int, cols: int, resize: int = None)
	```

	[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/utils/pil_utils.py#L51)

	이미지 그리드 하나를 준비합니다. 시각화 목적으로 유용합니다.

	## randn_tensor[[diffusers.utils.torch_utils.randn_tensor]]

	#### diffusers.utils.torch_utils.randn_tensor[[diffusers.utils.torch_utils.randn_tensor]]

	```python
	diffusers.utils.torch_utils.randn_tensor(shape: tuple \| list, generator: list['torch.Generator'] \| 'torch.Generator' \| None = None, device: str \| 'torch.device' \| None = None, dtype: 'torch.dtype' \| None = None, layout: 'torch.layout' \| None = None)
	```

	[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/utils/torch_utils.py#L61)

	원하는 `device`와 `dtype`을 가진 랜덤 텐서를 생성하는 헬퍼 함수입니다. 생성기 목록을 전달하면 각 배치 크기를 개별적으로 시드할 수 있습니다. CPU 생성기가 전달되면 텐서는 항상 CPU에서 생성됩니다.

	## TorchDeviceBackend[[diffusers.utils.torch_utils.TorchDeviceBackend]]

	#### diffusers.utils.torch_utils.TorchDeviceBackend[[diffusers.utils.torch_utils.TorchDeviceBackend]]

	```python
	diffusers.utils.torch_utils.TorchDeviceBackend(device: str \| torch.device \| None = None)
	```

	[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/utils/torch_utils.py#L228)

	하나의 장치에 대한 `torch.<backend>` 네임스페이스(`torch.cuda`, `torch.xpu`, `torch.mps`, ...)의 프록시입니다. 이 클래스가 정의하지 않은 속성은 모듈 자체의 속성(`synchronize`, `device_count`, `Stream`, `current_stream`, ...)이며, 여기서 정의된 메서드는 백엔드 간 가용성이 달라 폴백이 필요한 연산을 오버라이드합니다: 캐시 정리, 시드 설정 및 메모리 조회. `device`가 없으면 `torch.accelerator`를 통해 호스트 가속기를 감지합니다. torch에 해당 백엔드 모듈이 없으면 `torch.cuda`로 조용히 폴백하는 대신 예외를 발생시킵니다.

	#### max_memory_allocated[[diffusers.utils.torch_utils.TorchDeviceBackend.max_memory_allocated]]

	```python
	max_memory_allocated()
	```

	[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/utils/torch_utils.py#L291)

	마지막 리셋 이후 디바이스에 할당된 피크 메모리(바이트 단위); 백엔드가 통계를 유지하지 않는 경우 0.

	#### mem_get_info[[diffusers.utils.torch_utils.TorchDeviceBackend.mem_get_info]]

	```python
	mem_get_info()
	```

	[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/utils/torch_utils.py#L279)

	바이트 단위의 가용 및 전체 디바이스 메모리.

	## apply_layerwise_casting[[diffusers.hooks.apply_layerwise_casting]]

	#### diffusers.hooks.apply_layerwise_casting[[diffusers.hooks.apply_layerwise_casting]]

	```python
	diffusers.hooks.apply_layerwise_casting(module: Module, storage_dtype: dtype, compute_dtype: dtype, skip_modules_pattern: str \| tuple[str, ...] = 'auto', skip_modules_classes: tuple[typing.Type[torch.nn.Module], ...] \| None = None, non_blocking: bool = False)
	```

	[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/hooks/layerwise_casting.py#L101)

	매개변수:

	module (`torch.nn.Module`) : 계산 시 리프 모듈을 고정밀 dtype으로, 저장 시 저정밀 dtype으로 캐스팅할 모듈입니다.

	storage_dtype (`torch.dtype`) : 저장하기 위해 forward pass 전/후에 모듈을 캐스팅할 dtype.

	compute_dtype (`torch.dtype`) : forward pass에서 계산을 위해 모듈을 캐스트할 dtype입니다.

	skip_modules_pattern (`tuple[str, ...]`, 기본값은 `"auto"`) : 레이어별 캐스팅 과정에서 건너뛸 모듈의 이름을 일치시키기 위한 패턴 목록입니다. `"auto"`로 설정하면 기본 패턴이 사용됩니다. `None`으로 설정하면 어떤 모듈도 건너뛰지 않습니다. `None`으로 설정하고 `skip_modules_classes`도 `None`인 경우, 레이어별 캐스팅이 내부 하위 모듈이 아닌 모듈 자체에 직접 적용됩니다.

	skip_modules_classes (`tuple[Type[torch.nn.Module], ...]`, 기본값은 `None`) : 레이어별 캐스팅 과정에서 건너뛸 모듈 클래스 목록입니다.

	non_blocking (`bool`, 기본값은 `False`) : `True`인 경우, 가중치 캐스팅 작업이 비차단(non-blocking) 방식으로 수행됩니다.

	Applies layerwise casting to a given module. The module expected here is a Diffusers ModelMixin but it can be any nn.Module using diffusers layers or pytorch primitives.

	예:

	```python
	>>> import torch
	>>> from diffusers import CogVideoXTransformer3DModel

	>>> transformer = CogVideoXTransformer3DModel.from_pretrained(
	... model_id, subfolder="transformer", torch_dtype=torch.bfloat16
	... )

	>>> apply_layerwise_casting(
	... transformer,
	... storage_dtype=torch.float8_e4m3fn,
	... compute_dtype=torch.bfloat16,
	... skip_modules_pattern=["patch_embed", "norm", "proj_out"],
	... non_blocking=True,
	... )
	```

	## apply_group_offloading[[diffusers.hooks.apply_group_offloading]]

	#### diffusers.hooks.apply_group_offloading[[diffusers.hooks.apply_group_offloading]]

	```python
	diffusers.hooks.apply_group_offloading(module: Module, onload_device: typing.Union[str, torch.device], offload_device: typing.Union[str, torch.device] = torch.device(), offload_type: str \| diffusers.hooks.group_offloading.GroupOffloadingType = 'block_level', num_blocks_per_group: int \| None = None, non_blocking: bool = False, use_stream: bool = False, record_stream: bool = False, low_cpu_mem_usage: bool = False, offload_to_disk_path: str \| None = None, block_modules: list[str] \| None = None, exclude_kwargs: list[str] \| None = None)
	```

	[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/hooks/group_offloading.py#L567)

	매개변수:

	module (`torch.nn.Module`) : 그룹 오프로딩이 적용되는 모듈입니다.

	onload_device (`torch.device`) : 모듈 그룹이 로드된 디바이스.

	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인 경우, offloading과 onloading이 non-blocking 데이터 전송으로 수행됩니다.

	use_stream (`bool`, 기본값은 `False`) : True인 경우, CUDA 스트림을 사용하여 오프로딩과 온로딩을 비동기적으로 수행합니다. 이는 계산과 데이터 전송을 오버랩하는 데 유용할 수 있습니다.

	record_stream (`bool`, 기본값은 `False`) : `use_stream`와 함께 활성화되면, 현재 텐서가 해당 스트림에 의해 사용되었음을 표시합니다. 메모리 사용량이 약간 증가하는 대신 더 빠른 성능을 제공합니다. 자세한 내용은 [PyTorch 공식 문서](https://pytorch.org/docs/stable/generated/torch.Tensor.record_stream.html)를 참조하세요.

	low_cpu_mem_usage (`bool`, 기본값은 `False`) : True인 경우, 사전 고정 대신 텐서를 온더플라이로 고정하여 CPU 메모리 사용량을 최소화합니다. 이 옵션은 스트림된 CPU 오프로딩(즉, `use_stream=True`)을 사용할 때만 의미가 있습니다. CPU 메모리가 병목 현상을 일으키는 경우 유용할 수 있지만, 스트림 사용의 이점을 상쇄할 수도 있습니다.

	block_modules (`list[str]`, 선택 사항) : 오프로딩을 위한 블록으로 처리해야 할 모듈 이름 목록입니다. 제공된 경우, 블록 수준 오프로딩을 고려할 때 이 모듈들만 대상이 됩니다. 제공되지 않으면 기본 블록 감지 로직이 사용됩니다.

	exclude_kwargs (`list[str]`, optional) : List of kwarg keys that should not be processed by send_to_device. This is useful for mutable state like caching lists that need to maintain their object identity across forward passes. If not provided, will be inferred from the module's `_skip_keys` attribute if it exists.

	torch.nn.Module의 내부 레이어에 group offloading을 적용합니다. group offloading이 무엇인지, 그리고 어떤 상황에서 이점이 있는지 이해하려면, 먼저 다른 지원되는 offloading 방식이 어떻게 작동하는지에 대한 배경을 제공해야 합니다.

	일반적으로 오프로딩은 두 단계에서 수행됩니다:
	- Module-level: Diffusers에서는 `ModelMixin::enable_model_cpu_offload()` 메서드를 사용하여 이를 활성화할 수 있습니다. 이 메서드는 파이프라인의 각 구성 요소를 저장 목적으로 CPU로 offload하고, 계산이 필요할 때 accelerator device로 onload하는 방식으로 동작합니다. 이 메서드는 모든 구성 요소를 accelerator에 유지하는 것보다 메모리 효율이 높지만, 여전히 메모리 요구량이 상당히 높습니다. 이 메서드가 작동하려면 forward pass를 완료할 수 있도록 런타임 dtype 기준 모델 크기 + 가장 큰 중간 activation 텐서 크기에 해당하는 메모리가 필요합니다.
	- Leaf-level: Diffusers에서는 `ModelMixin::enable_sequential_cpu_offload()` 메서드를 사용하여 이를 활성화할 수 있습니다. 이 방식은 계산 그래프의 가장 낮은 leaf-level 파라미터를 CPU로 offload하여 저장하고, 계산 시 leaf만 accelerator device로 onload하는 방식으로 동작합니다. 이 방식은 accelerator 메모리 사용량이 가장 적지만, 과도한 수의 device 동기화 때문에 속도가 느려질 수 있습니다.

	Group offloading은 두 가지 방법의 중간 단계입니다. 내부 레이어 그룹(`torch.nn.ModuleList` 또는 `torch.nn.Sequential`)을 offload하는 방식으로 동작합니다. 이 방법은 모듈 수준 offloading보다 메모리 사용량이 적습니다. 또한 장치 동기화 횟수가 줄어들어 leaf 수준/순차적 offloading보다 빠릅니다.

	CUDA 디바이스에서 비동기 데이터 전송 스트림을 지원하는 경우, 또 다른 지원되는 기능은 순차적 오프로딩과 비교하여 전체 실행 시간을 줄이기 위해 데이터 전송과 계산을 겹치게 하는 능력입니다. 이는 스트림을 사용한 레이어 프리페칭으로 활성화되며, 즉 현재 레이어가 실행되는 동안 다음으로 실행될 레이어가 가속기 디바이스로의 온로딩을 시작합니다 - 이로 인해 메모리 요구량이 약간 증가합니다. 이 구현은 리프 레벨 오프로딩도 지원하지만, 스트림을 사용할 때 훨씬 더 빨라질 수 있습니다.

	예:
	```python
	>>> from diffusers import CogVideoXTransformer3DModel
	>>> from diffusers.hooks import apply_group_offloading

	>>> transformer = CogVideoXTransformer3DModel.from_pretrained(
	... "THUDM/CogVideoX-5b", subfolder="transformer", torch_dtype=torch.bfloat16
	... )

	>>> apply_group_offloading(
	... transformer,
	... onload_device=torch.device("cuda"),
	... offload_device=torch.device("cpu"),
	... offload_type="block_level",
	... num_blocks_per_group=2,
	... use_stream=True,
	... )
	```