Diffusers documentation
Công cụ tiện ích
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
Chuyển đổi một ảnh numpy hoặc một lô ảnh thành ảnh PIL.
pt_to_pil
Chuyển đổi ảnh torch sang ảnh PIL.
load_image
diffusers.utils.load_image
< source >( image: str | PIL.Image.Imageconvert_method: typing.Optional[typing.Callable[[PIL.Image.Image], PIL.Image.Image]] = None ) → PIL.Image.Image
Tham số
- image (
strhoặcPIL.Image.Image) — Hình ảnh cần chuyển đổi sang định dạng PIL Image. - convert_method (Callable[[PIL.Image.Image], PIL.Image.Image], optional) —
Phương pháp 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 “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
< source >( video: strconvert_method: typing.Optional[typing.Callable[[list[PIL.Image.Image]], list[PIL.Image.Image]]] = Nonereturn_fps: bool = False ) → list[PIL.Image.Image] or tuple[list[PIL.Image.Image], float]
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]], optional) —
Phương pháp 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 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
< source >( image: list[PIL.Image.Image]output_gif_path: str = Nonefps: int = 10 )
export_to_video
diffusers.utils.export_to_video
< source >( video_frames: list[np.ndarray] | list[PIL.Image.Image]output_video_path: str = Nonefps: int = 10quality: float = 5.0bitrate: int | None = Nonemacro_block_size: int | None = 16 )
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 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ế.
Các video có chất lượng tốt hơn với kích thước tệp nhỏ hơn sẽ được tạo ra khi sử dụng tham số bitrate thay đổi quality
thay vì 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, đặ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
< source >( video: list[PIL.Image.Image] | np.ndarray | 'torch.Tensor' | Iterator['torch.Tensor']fps: intoutput_path: straudio: 'torch.Tensor' | None = Noneaudio_sample_rate: int | None = Nonevideo_chunks_number: int = 1 )
Tham số
- video (
List[PIL.Image.Image]hoặcnp.ndarrayhoặctorch.Tensor) — Một tensor video có hình dạng [frames, height, width, channels] với giá trị pixel nguyên trong khoảng [0, 255]. Nếu đầu vào là mộtnp.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ớioutput_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ần số lấy mẫu của dạng sóng âm thanh. - video_chunks_number (
int, tùy chọn, 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
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
< source >( shape: tuple | listgenerator: list['torch.Generator'] | 'torch.Generator' | None = Nonedevice: str | 'torch.device' | None = Nonedtype: 'torch.dtype' | None = Nonelayout: 'torch.layout' | None = None )
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
lớp diffusers.utils.torch_utils.TorchDeviceBackend
< source >( device: str | torch.device | None = None )
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ó khả năng sử 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.
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ê.
Bộ nhớ thiết bị trống và tổng, tính bằng byte.
apply_layerwise_casting
diffusers.hooks.apply_layerwise_casting
< source >( module: Modulestorage_dtype: dtypecompute_dtype: dtypeskip_modules_pattern: str | tuple[str, ...] = 'auto'skip_modules_classes: tuple[typing.Type[torch.nn.Module], ...] | None = Nonenon_blocking: bool = False )
Tham số
- module (
torch.nn.Module) — Module mà các module lá của nó sẽ được chuyển đổi 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 sang 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 được đặt thành"auto", các mẫu mặc định sẽ được sử dụng. Nếu được đặt thànhNone, không có module nào bị bỏ qua. Nếu được đặt thànhNonecùng vớiskip_modules_classeslà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 vào 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ếuTrue, các thao tác chuyển đổi kiểu 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 ModelMixin của Diffusers, 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
< source >( module: Moduleonload_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 = Nonenon_blocking: bool = Falseuse_stream: bool = Falserecord_stream: bool = Falselow_cpu_mem_usage: bool = Falseoffload_to_disk_path: str | None = Noneblock_modules: list[str] | None = Noneexclude_kwargs: list[str] | None = None )
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 onload 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 (
strhoặcGroupOffloadingType, mặc định là “block_level”) — Loại 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, tùy chọn) — Số lượng khối trong 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 truyề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ớiuse_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, mứ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], tuỳ 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 của chúng qua các lần forward pass. Nếu không được cung cấp, sẽ được suy ra từ thuộc tính_skip_keyscủ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(). Nó hoạt động bằng cách chuyển các tham số ở mức lá thấp nhất của đồ thị tính toán sang CPU để lưu trữ, và chỉ nạp các lá lên thiết bị tăng tốc để tính toán. Cách này sử dụng lượng bộ nhớ tăng 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). Phương pháp 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 nhiều 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,
... )