diffusers/v0.43.0/vi/api/utilities.md

Công cụ tiện ích

Các hàm tiện ích và hỗ trợ để làm việc với 🤗 Diffusers.

numpy_to_pil[[diffusers.utils.numpy_to_pil]]

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

diffusers.utils.numpy_to_pil(images)

Nguồn

Chuyển đổi một ảnh numpy hoặc một lô ảnh thành ảnh PIL.

pt_to_pil[[diffusers.utils.pt_to_pil]]

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

diffusers.utils.pt_to_pil(images)

Nguồn

Chuyển đổi ảnh torch sang ảnh PIL.

load_image[[diffusers.utils.load_image]]

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

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

Nguồn

Tham số:

image (str hoặc PIL.Image.Image) : Ảnh cần chuyển đổi sang định dạng PIL Image.

convert_method (Callable[[PIL.Image.Image], PIL.Image.Image], tùy chọn) : Phương thức chuyển đổi để áp dụng cho hình ảnh sau khi tải. Khi đặt thành None, hình ảnh sẽ được chuyển đổi sang "RGB".

Trả về: PIL.Image.Image

Một hình ảnh PIL.

Tải image vào một hình ảnh PIL.

load_video[[diffusers.utils.load_video]]

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

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)

Nguồn

Tham số:

video (str) : Một URL hoặc Path trỏ đến video cần chuyển đổi thành danh sách ảnh định dạng PIL Image.

convert_method (Callable[[list[PIL.Image.Image]], list[PIL.Image.Image]], tùy chọn) : Phương thức chuyển đổi để áp dụng cho video sau khi tải. Khi đặt thành None, các hình ảnh sẽ được chuyển đổi sang "RGB".

return_fps (bool, tùy chọn, mặc định là False) : Có nên trả về cả tốc độ khung hình mà video được mã hóa hay không. Cần thiết cho các pipeline thực hiện lấy mẫu lại đầu vào theo tốc độ khung hình mà mô hình của chúng hoạt động, vì một danh sách các khung hình không chứa thông tin đó.

Trả về: list[PIL.Image.Image] hoặc tuple[list[PIL.Image.Image], float]

Video dưới dạng danh sách các hình ảnh PIL, cùng với tốc độ khung hình của nó nếu return_fps được đặt.

Tải video vào một danh sách ảnh PIL.

export_to_gif[[diffusers.utils.export_to_gif]]

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

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

Nguồn

export_to_video[[diffusers.utils.export_to_video]]

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

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)

Nguồn

quality: Chất lượng đầu ra video. Mặc định là 5. Sử dụng tốc độ bit thay đổi. Chất lượng cao nhất là 10, thấp nhất là 0. Đặt thành None để ngăn các cờ tốc độ bit thay đổi được truyền đến FFMPEG, cho phép bạn chỉ định chúng thủ công bằng cách sử dụng output_params thay thế. Việc chỉ định tốc độ bit cố định bằng bitrate sẽ vô hiệu hóa tham số này.

bitrate: Đặt bitrate cố định cho việc mã hóa video. Mặc định là None, khiến tham số quality được sử dụng thay thế. Việc sử dụng tham số bitrate thay đổi quality sẽ cho ra video có chất lượng tốt hơn với kích thước tệp nhỏ hơn so với việc chỉ định bitrate cố định bằng tham số này.

macro_block_size: Ràng buộc kích thước cho video. Độ rộng và chiều cao phải chia hết cho số này. Nếu không chia hết, imageio sẽ yêu cầu ffmpeg phóng to hình ảnh lên kích thước gần nhất có thể chia hết cho số này. Hầu hết các codec tương thích với kích thước macroblock là 16 (mặc định), một số có thể nhỏ hơn (4, 8). Để tắt tính năng tự động này, hãy đặt giá trị là None hoặc 1, tuy nhiên cần lưu ý rằng nhiều trình phát không thể giải mã video có kích thước lẻ và một số codec sẽ cho kết quả kém hoặc thất bại. Xem https://en.wikipedia.org/wiki/Macroblock.

encode_video[[diffusers.utils.encode_video]]

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

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)

Nguồn

Tham số:

video (List[PIL.Image.Image] hoặc np.ndarray hoặc torch.Tensor) : Một tensor video có hình dạng [frames, height, width, channels] với các giá trị pixel nguyên trong khoảng [0, 255]. Nếu đầu vào là một np.ndarray, nó được kỳ vọng là một mảng float với các giá trị trong khoảng [0, 1] (đây là thứ mà các pipeline thường trả về với output_type="np").

fps (int) : Số khung hình mỗi giây (FPS) của video đã mã hóa.

output_path (str) : Đường dẫn để lưu video đã mã hóa.

audio (torch.Tensor, tùy chọn) : Một dạng sóng âm thanh có hình dạng [audio_channels, samples].

audio_sample_rate : (int, tùy chọn): Tốc độ lấy mẫu của dạng sóng âm thanh.

video_chunks_number (int, optional, mặc định là 1) : Số lượng khối để chia video khi mã hóa. Mỗi khối sẽ được mã hóa riêng biệt. Số lượng khối cần dùng thường phụ thuộc vào cấu hình lát cắt (tiling config) cho VAE của video.

Mã hóa video với âm thanh tùy chọn bằng thư viện PyAV. Dựa trên mã từ kho LTX-2 gốc: 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]]

diffusers.utils.make_image_grid(images: list[PIL.Image.Image], rows: int, cols: int, resize: int = None)

Nguồn

Chuẩn bị một lưới ảnh duy nhất. Hữu ích cho mục đích trực quan hóa.

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

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

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)

Nguồn

Một hàm trợ giúp để tạo các tensor ngẫu nhiên trên device mong muốn với dtype mong muốn. Khi truyền vào một danh sách các generator, bạn có thể đặt seed cho từng kích thước batch riêng biệt. Nếu truyền vào các generator CPU, tensor luôn được tạo trên CPU.

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

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

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

Nguồn

Một proxy cho namespace torch.<backend> (torch.cuda, torch.xpu, torch.mps, ...) của một thiết bị. Các thuộc tính mà lớp không định nghĩa là của chính module (synchronize, device_count, Stream, current_stream, ...); các phương thức được định nghĩa ở đây ghi đè lên các thao tác có tính khả dụng khác nhau giữa các backend và cần một phương án dự phòng: xóa cache, seeding và truy vấn bộ nhớ. Nếu không có device, sẽ phát hiện bộ tăng tốc của host thông qua torch.accelerator. Ném ngoại lệ nếu torch không có module cho backend thay vì âm thầm quay lại torch.cuda.

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

max_memory_allocated()

Nguồn

Bộ nhớ tối đa được cấp phát trên thiết bị tính bằng byte kể từ lần đặt lại gần nhất; 0 nếu backend không lưu trữ thống kê.

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

mem_get_info()

Nguồn

Bộ nhớ thiết bị trống và tổng, tính bằng byte.

apply_layerwise_casting[[diffusers.hooks.apply_layerwise_casting]]

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

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)

Nguồn

Tham số:

module (torch.nn.Module) : Module mà các module lá của nó sẽ được chuyển sang dtype độ chính xác cao để tính toán và sang dtype độ chính xác thấp để lưu trữ.

storage_dtype (torch.dtype) : dtype để chuyển đổi module trước/sau bước forward để lưu trữ.

compute_dtype (torch.dtype) : dtype để chuyển đổi module trong quá trình forward pass để tính toán.

skip_modules_pattern (tuple[str, ...], mặc định là "auto") : Một danh sách các mẫu để khớp với tên của các module cần bỏ qua trong quá trình chuyển đổi kiểu dữ liệu theo từng lớp. Nếu đặt thành "auto", các mẫu mặc định sẽ được sử dụng. Nếu đặt thành None, không có module nào bị bỏ qua. Nếu đặt thành None cùng với skip_modules_classes là None, quá trình chuyển đổi kiểu dữ liệu theo từng lớp sẽ được áp dụng trực tiếp lên module thay vì các submodule bên trong của nó.

skip_modules_classes (tuple[Type[torch.nn.Module], ...], mặc định là None) : Một danh sách các lớp module cần bỏ qua trong quá trình chuyển đổi kiểu theo từng lớp.

non_blocking (bool, mặc định là False) : Nếu True, các thao tác chuyển đổi trọng số sẽ không chặn.

Áp dụng việc chuyển kiểu (casting) theo từng lớp cho một module được chỉ định. Module được kỳ vọng ở đây là một Diffusers ModelMixin nhưng nó có thể là bất kỳ nn.Module nào sử dụng các lớp của diffusers hoặc các nguyên thủy của pytorch.

Ví dụ:

>>> 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]]

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)

Nguồn

Tham số:

module (torch.nn.Module) : Module mà group offloading được áp dụng.

onload_device (torch.device) : Thiết bị mà nhóm các module được nạp lên.

offload_device (torch.device, mặc định là torch.device("cpu")) : Thiết bị mà nhóm các module được offload đến. Thông thường, đây nên là CPU. Mặc định là CPU.

offload_type (str hoặc GroupOffloadingType, mặc định là "block_level") : Kiểu offloading sẽ được áp dụng. Có thể là "block_level" hoặc "leaf_level". Mặc định là "block_level".

offload_to_disk_path (str, tùy chọn, mặc định là None) : Đường dẫn đến thư mục nơi các tham số sẽ được offload. Việc thiết lập tùy chọn này có thể hữu ích trong các môi trường có RAM hạn chế, nơi cần một sự đánh đổi hợp lý giữa tốc độ và bộ nhớ.

num_blocks_per_group (int, optional) : Số lượng khối trên mỗi nhóm khi sử dụng offload_type="block_level". Tham số này là bắt buộc khi sử dụng offload_type="block_level".

non_blocking (bool, mặc định là False) : Nếu là True, việc offloading và onloading sẽ được thực hiện với chuyển dữ liệu không chặn (non-blocking).

use_stream (bool, mặc định là False) : Nếu là True, việc offloading và onloading sẽ được thực hiện bất đồng bộ bằng cách sử dụng một CUDA stream. Điều này có thể hữu ích để chồng chéo giữa tính toán và truyền dữ liệu.

record_stream (bool, mặc định là False) : Khi được bật cùng với use_stream, nó đánh dấu tensor hiện tại là đã được sử dụng bởi stream này. Cách này nhanh hơn nhưng đổi lại tiêu tốn thêm một chút bộ nhớ. Xem tài liệu chính thức của PyTorch để biết thêm chi tiết.

low_cpu_mem_usage (bool, mặc định là False) : Nếu là True, việc sử dụng bộ nhớ CPU được tối thiểu hóa bằng cách ghim các tensor theo thời gian thực thay vì ghim trước. Tùy chọn này chỉ có ý nghĩa khi sử dụng offloading CPU dạng luồng (tức là use_stream=True). Điều này có thể hữu ích khi bộ nhớ CPU là điểm nghẽn, nhưng có thể làm giảm lợi ích của việc sử dụng luồng.

block_modules (list[str], tùy chọn) : Danh sách tên module cần được xử lý như các khối để offload. Nếu được cung cấp, chỉ các module này sẽ được xem xét cho offload ở cấp độ khối. Nếu không được cung cấp, logic phát hiện khối mặc định sẽ được sử dụng.

exclude_kwargs (list[str], tùy chọn) : Danh sách các khóa kwarg không nên được xử lý bởi send_to_device. Điều này hữu ích cho các trạng thái có thể thay đổi như danh sách cache cần duy trì bản dạng đối tượng xuyên suốt các lần truyền tiến. Nếu không được cung cấp, sẽ được suy ra từ thuộc tính _skip_keys của module nếu nó tồn tại.

Áp dụng group offloading cho các lớp bên trong của một torch.nn.Module. Để hiểu group offloading là gì và khi nào nó mang lại lợi ích, trước tiên chúng ta cần cung cấp một số ngữ cảnh về cách các phương pháp offloading khác được hỗ trợ hoạt động.

Thông thường, việc offload được thực hiện ở hai cấp độ:

• Module-level: Trong Diffusers, tính năng này có thể được bật bằng phương thức ModelMixin::enable_model_cpu_offload(). Nó hoạt động bằng cách offload từng thành phần của pipeline sang CPU để lưu trữ, và onload lên thiết bị accelerator khi cần cho tính toán. Phương thức này hiệu quả hơn về bộ nhớ so với việc giữ tất cả các thành phần trên accelerator, nhưng yêu cầu về bộ nhớ vẫn khá cao. Để phương thức này hoạt động, cần có bộ nhớ tương đương với kích thước của model trong runtime dtype + kích thước của các tensor kích hoạt trung gian lớn nhất để có thể hoàn thành forward pass.
• Mức lá: Trong Diffusers, tính năng này có thể được bật bằng phương thức ModelMixin::enable_sequential_cpu_offload(). Cơ chế hoạt động là offload các tham số ở mức lá thấp nhất của đồ thị tính toán xuống CPU để lưu trữ, và chỉ onload các lá đó lên thiết bị gia tốc để tính toán. Cách này sử dụng lượng bộ nhớ gia tốc thấp nhất, nhưng có thể chậm hơn do số lượng đồng bộ hóa thiết bị quá lớn.

Group offloading là giải pháp trung gian giữa hai phương pháp. Phương pháp này hoạt động bằng cách offload các nhóm lớp bên trong (dạng torch.nn.ModuleList hoặc torch.nn.Sequential). Cách này sử dụng bộ nhớ thấp hơn so với offloading ở cấp module. Nó cũng nhanh hơn so với offloading ở cấp leaf/sequential, vì số lần đồng bộ hóa thiết bị được giảm đi.

Một tính năng khác được hỗ trợ (cho các thiết bị CUDA có hỗ trợ các luồng chuyển dữ liệu bất đồng bộ) là khả năng chồng chéo giữa việc chuyển dữ liệu và tính toán để giảm thời gian thực thi tổng thể so với việc offload tuần tự. Tính năng này được kích hoạt bằng cách sử dụng layer prefetching với streams, tức là layer sẽ được thực thi tiếp theo bắt đầu onloading lên thiết bị tăng tốc trong khi layer hiện tại đang được thực thi - điều này làm tăng nhẹ yêu cầu về bộ nhớ. Lưu ý rằng cài đặt này cũng hỗ trợ offload ở cấp độ lá (leaf-level) nhưng có thể nhanh hơn đáng kể khi sử dụng streams.

Ví dụ:

>>> 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,
... )