Hugging Face's logo

Diffusers documentation

Mô hình

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.42.1).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Mô hình

🤗 Diffusers cung cấp các mô hình được huấn luyện trước cho các thuật toán phổ biến và các module để tạo ra các hệ thống khuếch tán tùy chỉnh. Chức năng chính của các mô hình là khử nhiễu một mẫu đầu vào theo phân phối pθ(xt−1∣xt)p_{\theta}(x_{t-1}|x_{t}).

Tất cả các model được xây dựng từ lớp cơ sở ModelMixin, vốn là một torch.nn.Module cung cấp các chức năng cơ bản để lưu và tải model, cả cục bộ lẫn từ Hugging Face Hub.

ModelMixin

lớp diffusers.ModelMixin

< >

( )

Lớp cơ sở cho tất cả các mô hình.

ModelMixin chịu trách nhiệm lưu trữ cấu hình mô hình và cung cấp các phương thức để tải xuống, tải và lưu trữ mô hình.

compile_repeated_blocks

< >

( *args**kwargs )

Chỉ biên dịch những module con được lặp lại thường xuyên của mô hình (ví dụ: các lớp Transformer) thay vì biên dịch toàn bộ mô hình. Kỹ thuật này—thường được gọi là biên dịch theo vùng (xem công thức PyTorch https://docs.pytorch.org/tutorials/recipes/regional_compilation.html) có thể giảm đáng kể thời gian biên dịch đầu-cuối, trong khi vẫn giữ được tốc độ chạy nhanh hơn như bạn kỳ vọng từ torch.compile đầy đủ.

Bộ các module con cần biên dịch được xác định dựa trên sự hiện diện của thuộc tính _repeated_blocks trong định nghĩa model. Hãy định nghĩa thuộc tính này trên lớp con của model dưới dạng danh sách/bộ ba tên lớp (chuỗi). Mọi module có tên lớp khớp sẽ được biên dịch.

Khi được phát hiện, mỗi sub-module khớp sẽ được biên dịch bằng cách gọi submodule.compile(*args, **kwargs). Bất kỳ đối số vị trí hay đối số từ khóa nào bạn cung cấp cho compile_repeated_blocks đều được chuyển nguyên vẹn đến torch.compile.

cuda

( *args**kwargs )

Một giá trị giả lập cho một đường dẫn có dấu chấm (ví dụ: torch.float32): các chuỗi truy cập thuộc tính, các cuộc gọi hoạt động như các decorator pass-through, repr là đường dẫn có dấu chấm, và việc sử dụng nó như một lớp cơ sở sẽ thay thế bằng một lớp cơ sở type thông thường (PEP 560 __mro_entries__), do đó các lớp con thực sự vẫn giữ nguyên metaclass bình thường và inspect.signature sẽ đọc __init__ thực của chúng thay vì của một mock.

dequantize

< >

( )

Có thể khử lượng tử hóa mô hình trong trường hợp nó đã được lượng tử hóa bằng một phương pháp lượng tử hóa hỗ trợ khử lượng tử hóa.

disable_gradient_checkpointing

< >

( )

Tắt gradient checkpointing cho model hiện tại (có thể được gọi là activation checkpointing hoặc checkpoint activations trong các framework khác).

disable_npu_flash_attention

< >

( )

tắt npu flash attention từ torch_npu

disable_xformers_memory_efficient_attention

< >

( )

Tắt chú ý tiết kiệm bộ nhớ từ xFormers.

disable_xla_flash_attention

< >

( )

Tắt kernel pallals của flash attention cho torch_xla.

enable_gradient_checkpointing

< >

( gradient_checkpointing_func: typing.Optional[typing.Callable] = None )

Tham số

  • gradient_checkpointing_func (Callable, tuỳ chọn) — Hàm được sử dụng cho gradient checkpointing. Nếu là None, hàm checkpointing mặc định của PyTorch sẽ được sử dụng (torch.utils.checkpoint.checkpoint).

Bật gradient checkpointing cho model hiện tại (có thể được gọi là activation checkpointing hoặc checkpoint activations trong các framework khác).

enable_group_offload

< >

( onload_device: deviceoffload_device: device = torch.device()offload_type: str = 'block_level'num_blocks_per_group: int | None = Nonenon_blocking: bool = Falseuse_stream: bool = Falserecord_stream: bool = Falselow_cpu_mem_usage = Falseoffload_to_disk_path: str | None = Noneblock_modules: str | None = Noneexclude_kwargs: str | None = None )

Kích hoạt việc chuyển nhóm (group offloading) cho mô hình hiện tại.

Xem apply_group_offloading() để biết thêm thông tin.

Ví dụ:

>>> from diffusers import CogVideoXTransformer3DModel

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

>>> transformer.enable_group_offload(
...     onload_device=torch.device("cuda"),
...     offload_device=torch.device("cpu"),
...     offload_type="leaf_level",
...     use_stream=True,
... )

enable_layerwise_casting

< >

( storage_dtype: dtype = torch.float8_e4m3fncompute_dtype: typing.Optional[torch.dtype] = Noneskip_modules_pattern: tuple[str, ...] | None = Noneskip_modules_classes: tuple[typing.Type[torch.nn.Module], ...] | None = Nonenon_blocking: bool = False )

Tham số

  • storage_dtype (torch.dtype) — dtype mà mô hình cần được chuyển đổi để lưu trữ.
  • compute_dtype (torch.dtype) — Dtype mà trọng số của mô hình cần được chuyển đổi trong quá trình truyền thẳng.
  • skip_modules_pattern (tuple[str, ...], tuỳ chọn) — 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 None, các mẫu bỏ qua mặc định sẽ được sử dụng để bỏ qua một số lớp nội bộ của các module và các lớp PEFT.
  • skip_modules_classes (tuple[Type[torch.nn.Module], ...], tùy chọn) — 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, tùy chọn, mặc định là False) — Nếu True, các thao tác chuyển đổi kiểu trọng số sẽ không chặn.

Kích hoạt việc chuyển đổi kiểu dữ liệu theo từng lớp cho mô hình hiện tại.

Layerwise casting là một kỹ thuật chuyển đổi trọng số mô hình sang dtype độ chính xác thấp hơn để lưu trữ, nhưng tự động chuyển đổi chúng lên dtype độ chính xác cao hơn khi tính toán. Quy trình này có thể giảm đáng kể bộ nhớ sử dụng bởi trọng số mô hình, nhưng có thể dẫn đến một số suy giảm chất lượng trong đầu ra. Phần lớn các suy giảm là không đáng kể, chủ yếu bắt nguồn từ việc chuyển đổi trọng số trong các lớp chuẩn hóa và điều biến.

Mặc định, hầu hết các model trong diffusers đặt thuộc tính _skip_layerwise_casting_patterns để bỏ qua các lớp patch embedding, positional embedding và normalization. Điều này là do các lớp này có khả năng cao là nhạy cảm với độ chính xác đối với chất lượng. Nếu bạn muốn thay đổi hành vi này, bạn có thể đặt thuộc tính _skip_layerwise_casting_patterns thành None, hoặc gọi apply_layerwise_casting() với các đối số tùy chỉnh.

Ví dụ:

Sử dụng enable_layerwise_casting():

>>> from diffusers import CogVideoXTransformer3DModel

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

>>> # Enable layerwise casting via the model, which ignores certain modules by default
>>> transformer.enable_layerwise_casting(storage_dtype=torch.float8_e4m3fn, compute_dtype=torch.bfloat16)

enable_npu_flash_attention

< >

( )

Bật npu flash attention từ torch_npu

enable_xformers_memory_efficient_attention

< >

( attention_op: typing.Optional[typing.Callable] = None )

Tham số

  • attention_op (Callable, tùy chọn) — Ghi đè toán tử mặc định None để sử dụng làm đối số op cho hàm memory_efficient_attention() của xFormers.

Bật chú ý tiết kiệm bộ nhớ từ xFormers.

Khi tùy chọn này được bật, bạn nên quan sát thấy mức sử dụng bộ nhớ GPU thấp hơn và khả năng tăng tốc trong quá trình suy luận. Việc tăng tốc trong quá trình huấn luyện không được đảm bảo.

> ⚠️ Khi cả memory efficient attention và sliced attention đều được bật, memory efficient attention sẽ có > ưu tiên.

Ví dụ:

>>> import torch
>>> from diffusers import UNet2DConditionModel
>>> from xformers.ops import MemoryEfficientAttentionFlashAttentionOp

>>> model = UNet2DConditionModel.from_pretrained(
...     "stabilityai/stable-diffusion-2-1", subfolder="unet", torch_dtype=torch.float16
... )
>>> model = model.to("cuda")
>>> model.enable_xformers_memory_efficient_attention(attention_op=MemoryEfficientAttentionFlashAttentionOp)

enable_xla_flash_attention

< >

( partition_spec: typing.Optional[typing.Callable] = None**kwargs )

Bật kernel pallals của flash attention cho torch_xla.

from_pretrained

< >

( pretrained_model_name_or_path: str | os.PathLike | None**kwargs )

Tham số

  • pretrained_model_name_or_path (str hoặc os.PathLike, tùy chọn) — Có thể là:
    • Một chuỗi, model id (ví dụ google/ddpm-celebahq-256) của một mô hình được huấn luyện trước có sẵn trên Hub.
    • Đường dẫn đến một thư mục (ví dụ ./my_model_directory) chứa các trọng số mô hình đã được lưu bằng save_pretrained().
  • cache_dir (str | os.PathLike, tùy chọn) — Đường dẫn đến thư mục nơi cấu hình mô hình được huấn luyện trước đã tải xuống được lưu đệm nếu không sử dụng bộ lưu đệm tiêu chuẩn.
  • dtype (torch.dtype, tùy chọn) — Ghi đè torch.dtype mặc định và tải mô hình với một dtype khác.
  • force_download (bool, tùy chọn, mặc định là False) — Có nên buộc tải lại (re-download) trọng số mô hình và các tệp cấu hình, ghi đè lên các phiên bản đã được lưu trong bộ nhớ đệm nếu chúng tồn tại hay không.
  • proxies (dict[str, str], tuỳ chọn) — Một từ điển các máy chủ proxy để sử dụng theo giao thức hoặc điểm cuối, ví dụ, {'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}. Các proxy này được sử dụng cho mỗi yêu cầu.
  • output_loading_info (bool, tùy chọn, mặc định là False) — Có nên trả về một từ điển chứa các khóa bị thiếu, các khóa không mong đợi và thông báo lỗi hay không.
  • local_files_only(bool, tuỳ chọn, mặc định là False) — Có chỉ tải trọng số và tệp cấu hình mô hình cục bộ hay không. Nếu đặt thành True, mô hình sẽ không được tải xuống từ Hub.
  • token (str hoặc bool, tùy chọn) — Token được sử dụng làm HTTP bearer authorization cho các tệp từ xa. Nếu True, token được tạo từ diffusers-cli login (được lưu trong ~/.huggingface) sẽ được sử dụng.
  • revision (str, tùy chọn, mặc định là "main") — Phiên bản mô hình cụ thể cần sử dụng. Nó có thể là tên nhánh, tên thẻ, id commit, hoặc bất kỳ định danh nào được Git cho phép.
  • subfolder (str, tùy chọn, mặc định là "") — Vị trí thư mục con của tệp mô hình bên trong một kho lưu trữ mô hình lớn hơn trên Hub hoặc cục bộ.
  • mirror (str, optional) — Mirror source to resolve accessibility issues if you’re downloading a model in China. We do not guarantee the timeliness or safety of the source, and you should refer to the mirror site for more information.
  • device_map (int | str | torch.device hoặc dict[str, int | str | torch.device], tuỳ chọn) — Một bản đồ chỉ định vị trí của từng submodule. Không cần định nghĩa cho từng tên parameter/buffer; một khi tên module đã được đưa vào, mọi submodule của nó sẽ được gửi đến cùng một thiết bị. Mặc định là None, nghĩa là mô hình sẽ được tải lên CPU.

    Ví dụ:

Tạo một mô hình PyTorch được huấn luyện trước từ cấu hình của một mô hình được huấn luyện trước.

Mô hình được đặt ở chế độ đánh giá - model.eval() - theo mặc định, và các module dropout bị vô hiệu hóa. Để huấn luyện mô hình, hãy đặt lại nó ở chế độ huấn luyện bằng model.train().

> Để sử dụng các mô hình riêng tư hoặc có kiểm soát truy cập, hãy đăng nhập bằng hf > auth login. Bạn cũng có thể kích hoạt chế độ đặc biệt > “offline-mode” để sử dụng phương pháp này trong môi trường có tường lửa.

Ví dụ:

from diffusers import UNet2DConditionModel

unet = UNet2DConditionModel.from_pretrained("stable-diffusion-v1-5/stable-diffusion-v1-5", subfolder="unet")

Nếu bạn nhận được thông báo lỗi bên dưới, bạn cần tinh chỉnh trọng số cho tác vụ hạ nguồn của mình:

Some weights of UNet2DConditionModel were not initialized from the model checkpoint at stable-diffusion-v1-5/stable-diffusion-v1-5 and are newly initialized because the shapes did not match:
- conv_in.weight: found shape torch.Size([320, 4, 3, 3]) in the checkpoint and torch.Size([320, 9, 3, 3]) in the model instantiated
You should probably TRAIN this model on a down-stream task to be able to use it for predictions and inference.

get_memory_footprint

< >

( return_buffers = True )

Tham số

  • return_buffers (bool, tùy chọn, mặc định là True) — Có nên trả về kích thước của các tensor buffer trong quá trình tính toán mức sử dụng bộ nhớ hay không. Buffer là các tensor không yêu cầu gradient và không được đăng ký dưới dạng tham số. Ví dụ: mean và std trong các lớp batch norm. Vui lòng xem: https://discuss.pytorch.org/t/what-pytorch-means-by-buffers/120266/2

Lấy dấu chân bộ nhớ của một mô hình. Hàm này sẽ trả về dấu chân bộ nhớ của mô hình hiện tại tính bằng byte. Có ích để đo lường dấu chân bộ nhớ của mô hình hiện tại và thiết kế một số bài kiểm tra. Giải pháp được lấy cảm hứng từ các cuộc thảo luận trên PyTorch: https://discuss.pytorch.org/t/gpu-memory-that-model-uses/56822/2

số_tham_số

< >

( only_trainable: bool = Falseexclude_embeddings: bool = False ) → int

Tham số

  • only_trainable (bool, tùy chọn, mặc định là False) — Có nên chỉ trả về số lượng tham số có thể huấn luyện hay không.
  • exclude_embeddings (bool, tùy chọn, mặc định là False) — Có nên chỉ trả về số lượng tham số không phải embedding hay không.

Trả về

int

Số lượng tham số.

Lấy số lượng tham số (có thể huấn luyện hoặc không phải nhúng) trong module.

Ví dụ:

from diffusers import UNet2DConditionModel

model_id = "stable-diffusion-v1-5/stable-diffusion-v1-5"
unet = UNet2DConditionModel.from_pretrained(model_id, subfolder="unet")
unet.num_parameters(only_trainable=True)
859520964

reset_attention_backend

< >

( )

Đặt lại backend chú ý cho mô hình. Các cuộc gọi tiếp theo đến forward sẽ sử dụng mặc định của môi trường, nếu được đặt, hoặc chú ý tích vô hướng có tỷ lệ bản địa của torch.

save_pretrained

< >

( save_directory: str | os.PathLikeis_main_process: bool = Truesave_function: typing.Optional[typing.Callable] = Nonesafe_serialization: bool = Truevariant: str | None = Nonemax_shard_size: int | str = '10GB'push_to_hub: bool = Falseuse_flashpack: bool = False**kwargs )

Tham số

  • save_directory (str hoặc os.PathLike) — Thư mục để lưu trữ mô hình và tệp cấu hình của nó. Sẽ được tạo nếu chưa tồn tại.
  • is_main_process (bool, tùy chọn, mặc định là True) — Xác định xem tiến trình gọi hàm này có phải là tiến trình chính hay không. Hữu ích trong quá trình huấn luyện phân tán khi bạn cần gọi hàm này trên tất cả các tiến trình. Trong trường hợp này, chỉ đặt is_main_process=True trên tiến trình chính để tránh điều kiện đua.
  • save_function (Callable) — Hàm được sử dụng để lưu state dictionary. Hữu ích trong quá trình huấn luyện phân tán khi bạn cần thay thế torch.save bằng một phương pháp khác. Có thể được cấu hình bằng biến môi trường DIFFUSERS_SAVE_MODE.
  • safe_serialization (bool, tùy chọn, mặc định là True) — Liệu có lưu mô hình bằng safetensors hay theo cách truyền thống của PyTorch với pickle hay không.
  • variant (str, tùy chọn) — Nếu được chỉ định, trọng số sẽ được lưu ở định dạng pytorch_model.<variant>.bin.
  • max_shard_size (int hoặc str, mặc định là "10GB") — Kích thước tối đa của một checkpoint trước khi được chia nhỏ. Các checkpoint sau khi chia nhỏ sẽ có kích thước nhỏ hơn mức này. Nếu biểu diễn dưới dạng chuỗi, cần là các chữ số theo sau bởi một đơn vị (ví dụ "5GB"). Nếu biểu diễn dưới dạng số nguyên, đơn vị là byte. Lưu ý rằng giới hạn này sẽ được giảm sau một khoảng thời gian nhất định (bắt đầu từ tháng 10 năm 2024) để cho phép người dùng nâng cấp lên phiên bản mới nhất của diffusers. Điều này nhằm thiết lập một kích thước mặc định chung cho tham số này giữa các thư viện khác nhau trong hệ sinh thái Hugging Face (ví dụ như transformers và accelerate).
  • push_to_hub (bool, tùy chọn, mặc định là False) — Có đẩy mô hình của bạn lên Hugging Face Hub sau khi lưu hay không. Bạn có thể chỉ định kho lưu trữ muốn đẩy bằng repo_id (mặc định sẽ là tên của save_directory trong không gian tên của bạn).
  • kwargs (dict[str, Any], tùy chọn) — Các đối số từ khóa bổ sung được truyền đến phương thức push_to_hub().

Lưu một mô hình và tệp cấu hình của nó vào một thư mục để có thể tải lại bằng phương thức lớp from_pretrained().

set_attention_backend

< >

( backend: str )

Tham số

  • backend (str) — Tên của backend cần thiết lập. Phải là một trong các backend khả dụng được định nghĩa trong AttentionBackendName. Các backend khả dụng có thể tìm thấy trong diffusers.attention_dispatch.AttentionBackendName. Mặc định là torch native scaled dot product attention làm backend.

Đặt backend chú ý cho mô hình.

set_use_npu_flash_attention

< >

( valid: bool )

Đặt công tắc cho npu flash attention.

đến

( *args**kwargs )

Một giá trị giả lập cho một đường dẫn có dấu chấm (ví dụ: torch.float32): các chuỗi truy cập thuộc tính, các cuộc gọi hoạt động như các decorator pass-through, repr là đường dẫn có dấu chấm, và việc sử dụng nó như một lớp cơ sở sẽ thay thế bằng một lớp cơ sở type thông thường (PEP 560 __mro_entries__), do đó các lớp con thực sự vẫn giữ nguyên metaclass bình thường và inspect.signature sẽ đọc __init__ thực của chúng thay vì của một mock.

PushToHubMixin

lớp diffusers.utils.PushToHubMixin

< >

( )

Một Mixin để đẩy mô hình, bộ lập lịch hoặc pipeline lên Hugging Face Hub.

push_to_hub

< >

( repo_id: strcommit_message: str | None = Noneprivate: bool | None = Nonetoken: str | None = Nonecreate_pr: bool = Falsesafe_serialization: bool = Truevariant: str | None = Nonesubfolder: str | None = None )

Tham số

  • repo_id (str) — Tên của kho mà bạn muốn đẩy tệp mô hình, trình lập lịch hoặc pipeline của mình đến. Nó nên chứa tên tổ chức của bạn khi đẩy đến một tổ chức. repo_id cũng có thể là đường dẫn đến một thư mục cục bộ.
  • commit_message (str, tùy chọn) — Thông điệp để commit khi đẩy. Mặc định là "Upload {object}".
  • private (bool, optional) — Xác định có làm cho kho (repo) ở chế độ riêng tư hay không. Nếu là None (mặc định), kho sẽ ở chế độ công khai trừ khi mặc định của tổ chức là riêng tư. Giá trị này bị bỏ qua nếu kho đã tồn tại.
  • token (str, tùy chọn) — Token được sử dụng làm HTTP bearer authorization cho các tệp từ xa. Token được tạo khi chạy hf auth login (được lưu trong ~/.huggingface).
  • create_pr (bool, tùy chọn, mặc định là False) — Có tạo PR với các tệp đã tải lên hay commit trực tiếp hay không.
  • safe_serialization (bool, tùy chọn, mặc định là True) — Có chuyển đổi trọng số mô hình sang định dạng safetensors hay không.
  • variant (str, tùy chọn) — Nếu được chỉ định, trọng số sẽ được lưu ở định dạng pytorch_model.<variant>.bin.

Tải tệp mô hình, trình lập lịch hoặc pipeline lên 🤗 Hugging Face Hub.

Ví dụ:

from diffusers import UNet2DConditionModel

unet = UNet2DConditionModel.from_pretrained("stabilityai/stable-diffusion-2", subfolder="unet")

# Push the `unet` to your namespace with the name "my-finetuned-unet".
unet.push_to_hub("my-finetuned-unet")

# Push the `unet` to an organization with the name "my-finetuned-unet".
unet.push_to_hub("your-org/my-finetuned-unet")
Update on GitHub

←PEFT AutoModel→