Diffusers documentation

Model

Diffusers

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

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

Model

🤗 Diffusers menyediakan model pretrained untuk algoritma populer dan modul untuk membuat sistem difusi kustom. Fungsi utama dari model adalah untuk menghilangkan noise dari sampel input sesuai dengan distribusi $p_{\theta}(x_{t-1}|x_{t})$ .

Semua model dibangun dari kelas dasar ModelMixin yang merupakan torch.nn.Module yang menyediakan fungsionalitas dasar untuk menyimpan dan memuat model, baik secara lokal maupun dari Hugging Face Hub.

ModelMixin

kelas diffusers.ModelMixin

( )

Kelas dasar untuk semua model.

ModelMixin menangani penyimpanan konfigurasi model dan menyediakan metode untuk memuat, mengunduh, dan menyimpan model.

config_name (str) — Nama file untuk menyimpan model saat memanggil save_pretrained().

compile_repeated_blocks

( *args**kwargs )

Mengompilasi hanya sub-modul yang sering diulang dari sebuah model (misalnya lapisan Transformer) alih-alih mengompilasi seluruh model. Teknik ini—sering disebut kompilasi regional (lihat resep PyTorch https://docs.pytorch.org/tutorials/recipes/regional_compilation.html) dapat mengurangi waktu kompilasi end-to-end secara signifikan, sambil mempertahankan peningkatan kecepatan runtime yang Anda harapkan dari torch.compile penuh.

Set sub-modul yang akan dikompilasi ditemukan berdasarkan keberadaan atribut _repeated_blocks dalam definisi model. Definisikan atribut ini pada subkelas model Anda sebagai daftar/tuple nama kelas (string). Setiap modul yang nama kelasnya cocok akan dikompilasi.

Setelah ditemukan, setiap sub-modul yang cocok dikompilasi dengan memanggil submodule.compile(*args, **kwargs). Argumen posisional atau kata kunci apa pun yang Anda berikan ke compile_repeated_blocks diteruskan apa adanya ke torch.compile.

cuda

( *args**kwargs )

Nilai mock untuk jalur bertitik (mis. torch.float32): rantai akses atribut, pemanggilan berperilaku sebagai dekorator pass-through, repr adalah jalur bertitik, dan penggunaannya sebagai kelas dasar menggantikan kelas dasar type polos (PEP 560 __mro_entries__), sehingga subkelas asli tetap mempertahankan metakelas normal dan inspect.signature membaca __init__ asli mereka, bukan milik mock.

dequantize

( )

Potensi dekuantisasi model jika model tersebut telah dikuantisasi dengan metode kuantisasi yang mendukung dekuantisasi.

disable_gradient_checkpointing

( )

Menonaktifkan gradient checkpointing untuk model saat ini (dapat disebut sebagai activation checkpointing atau checkpoint activations di framework lain).

disable_npu_flash_attention

( )

nonaktifkan npu flash attention dari torch_npu

disable_xformers_memory_efficient_attention

( )

Nonaktifkan perhatian hemat memori dari xFormers.

disable_xla_flash_attention

( )

Nonaktifkan kernel pallals flash attention untuk torch_xla.

enable_gradient_checkpointing

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

Parameter

gradient_checkpointing_func (Callable, opsional) — Fungsi yang digunakan untuk gradient checkpointing. Jika None, fungsi checkpointing PyTorch default digunakan (torch.utils.checkpoint.checkpoint).

Mengaktifkan gradient checkpointing untuk model saat ini (dapat disebut sebagai activation checkpointing atau checkpoint activations di framework lain).

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 )

Mengaktifkan offloading grup untuk model saat ini.

Lihat apply_group_offloading() untuk informasi lebih lanjut.

Contoh:

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

Parameter

storage_dtype (torch.dtype) — dtype yang harus digunakan untuk meng-cast model saat penyimpanan.
compute_dtype (torch.dtype) — dtype yang harus digunakan untuk meng-cast bobot model selama forward pass.
skip_modules_pattern (tuple[str, ...], opsional) — Daftar pola untuk mencocokkan nama modul yang akan dilewati selama proses casting per lapisan. Jika diatur ke None, pola skip default digunakan untuk mengabaikan lapisan internal tertentu dari modul dan lapisan PEFT.
skip_modules_classes (tuple[Type[torch.nn.Module], ...], opsional) — Daftar kelas modul yang akan dilewati selama proses pencetakan layerwise.
non_blocking (bool, opsional, defaultnya False) — Jika True, operasi casting bobot bersifat non-blocking.

Mengaktifkan pencetakan layerwise untuk model saat ini.

Layerwise casting adalah teknik yang mengubah (cast) bobot model ke dtype presisi yang lebih rendah untuk penyimpanan, tetapi mengubahnya (upcast) secara langsung ke dtype presisi yang lebih tinggi untuk komputasi. Proses ini dapat secara signifikan mengurangi jejak memori dari bobot model, tetapi dapat menyebabkan penurunan kualitas tertentu pada output. Sebagian besar penurunan kualitas dapat diabaikan, terutama berasal dari pengubahan bobot pada lapisan normalisasi dan modulasi.

Secara default, sebagian besar model di diffusers menetapkan atribut _skip_layerwise_casting_patterns untuk mengabaikan patch embedding, positional embedding, dan lapisan normalisasi. Hal ini karena lapisan-lapisan tersebut kemungkinan besar sangat kritis terhadap presisi untuk kualitas. Jika Anda ingin mengubah perilaku ini, Anda dapat menetapkan atribut _skip_layerwise_casting_patterns ke None, atau memanggil apply_layerwise_casting() dengan argumen kustom.

Contoh:

Menggunakan 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

( )

Aktifkan npu flash attention dari torch_npu

enable_xformers_memory_efficient_attention

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

Parameter

attention_op (Callable, opsional) — Timpa operator default None untuk digunakan sebagai argumen op pada fungsi memory_efficient_attention() dari xFormers.

Aktifkan perhatian hemat memori dari xFormers.

Ketika opsi ini diaktifkan, Anda seharusnya mengamati penggunaan memori GPU yang lebih rendah dan potensi percepatan selama inferensi. Percepatan selama pelatihan tidak dijamin.

> ⚠️ Ketika memory efficient attention dan sliced attention keduanya diaktifkan, memory efficient attention memiliki > prioritas.

Contoh:

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

Aktifkan kernel pallals flash attention untuk torch_xla.

from_pretrained

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

Parameter

pretrained_model_name_or_path (str atau os.PathLike, opsional) — Dapat berupa:
- String, model id (misalnya google/ddpm-celebahq-256) dari model pretrained yang dihosting di Hub.
- Path ke direktori (misalnya ./my_model_directory) yang berisi bobot model yang disimpan dengan save_pretrained().
cache_dir (str | os.PathLike, opsional) — Path ke direktori tempat konfigurasi model pretrained yang diunduh di-cache jika cache standar tidak digunakan.
dtype (torch.dtype, opsional) — Timpa torch.dtype bawaan dan muat model dengan dtype lain.
force_download (bool, opsional, default False) — Apakah akan memaksa (mengunduh ulang) bobot model dan file konfigurasi, menimpa versi yang sudah di-cache jika ada.
proxies (dict[str, str], opsional) — Kamus server proxy yang digunakan berdasarkan protokol atau endpoint, misalnya {'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}. Proxy digunakan pada setiap permintaan.
output_loading_info (bool, opsional, default False) — Apakah akan mengembalikan kamus yang berisi kunci yang hilang, kunci yang tidak terduga, dan pesan kesalahan.
local_files_only(bool, opsional, defaultnya False) — Apakah hanya memuat bobot model dan file konfigurasi lokal atau tidak. Jika diatur ke True, model tidak akan diunduh dari Hub.
token (str atau bool, opsional) — Token yang digunakan sebagai otorisasi bearer HTTP untuk file jarak jauh. Jika True, token yang dihasilkan dari diffusers-cli login (disimpan di ~/.huggingface) akan digunakan.
revision (str, opsional, default "main") — Versi model spesifik yang akan digunakan. Bisa berupa nama branch, nama tag, commit id, atau identifier apa pun yang diizinkan oleh Git.
subfolder (str, opsional, default "") — Lokasi subfolder dari file model di dalam repositori model yang lebih besar di Hub atau secara lokal.
mirror (str, opsional) — Sumber cermin untuk mengatasi masalah aksesibilitas jika Anda mengunduh model di Tiongkok. Kami tidak menjamin ketepatan waktu atau keamanan sumber, dan Anda harus merujuk ke situs cermin untuk informasi lebih lanjut.
device_map (int | str | torch.device atau dict[str, int | str | torch.device], opsional) — Peta yang menentukan ke perangkat mana setiap submodul harus ditempatkan. Tidak perlu didefinisikan untuk setiap nama parameter/buffer; begitu nama modul tertentu ada di dalamnya, semua submodulnya akan dikirim ke perangkat yang sama. Nilainya secara default adalah None, yang berarti model akan dimuat di CPU.
Contoh:

Instansiasi model PyTorch pretrained dari konfigurasi model pretrained.

Model diatur dalam mode evaluasi - model.eval() - secara default, dan modul dropout dinonaktifkan. Untuk melatih model, kembalikan ke mode pelatihan dengan model.train().

> Untuk menggunakan model privat atau model bergerbang, masuk dengan hf > auth login. Anda juga dapat mengaktifkan mode khusus > “offline-mode” untuk menggunakan metode ini di lingkungan > yang terisolasi oleh firewall.

Contoh:

from diffusers import UNet2DConditionModel

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

Jika Anda menerima pesan kesalahan di bawah ini, Anda perlu melakukan penyesuaian bobot untuk tugas turunan Anda:

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 )

Parameter

return_buffers (bool, opsional, defaultnya True) — Apakah akan mengembalikan ukuran tensor buffer dalam perhitungan jejak memori. Buffer adalah tensor yang tidak memerlukan gradien dan tidak terdaftar sebagai parameter. Misalnya, mean dan std pada lapisan batch norm. Silakan lihat: https://discuss.pytorch.org/t/what-pytorch-means-by-buffers/120266/2

Dapatkan jejak memori (memory footprint) dari sebuah model. Ini akan mengembalikan jejak memori dari model saat ini dalam byte. Berfungsi untuk melakukan benchmark jejak memori dari model saat ini dan merancang beberapa pengujian. Solusi terinspirasi dari diskusi PyTorch: https://discuss.pytorch.org/t/gpu-memory-that-model-uses/56822/2

num_parameters

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

Parameter

only_trainable (bool, opsional, default False) — Apakah hanya mengembalikan jumlah parameter yang dapat dilatih.
exclude_embeddings (bool, opsional, default False) — Apakah hanya mengembalikan jumlah parameter non-embedding.

Mengembalikan

int

Jumlah parameter.

Dapatkan jumlah parameter (yang dapat dilatih atau non-embedding) dalam modul.

Contoh:

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

( )

Mengatur ulang backend perhatian untuk model. Panggilan ke forward selanjutnya akan menggunakan default lingkungan, jika diatur, atau scaled dot product attention native 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 )

Parameter

save_directory (str atau os.PathLike) — Direktori untuk menyimpan model dan file konfigurasinya. Akan dibuat jika belum ada.
is_main_process (bool, opsional, default True) — Apakah proses yang memanggil ini adalah proses utama atau tidak. Berguna selama pelatihan terdistribusi dan Anda perlu memanggil fungsi ini di semua proses. Dalam kasus ini, setel is_main_process=True hanya pada proses utama untuk menghindari kondisi balapan.
save_function (Callable) — Fungsi yang digunakan untuk menyimpan state dictionary. Berguna selama pelatihan terdistribusi ketika Anda perlu mengganti torch.save dengan metode lain. Dapat dikonfigurasi dengan variabel lingkungan DIFFUSERS_SAVE_MODE.
safe_serialization (bool, opsional, default True) — Apakah model disimpan menggunakan safetensors atau cara tradisional PyTorch dengan pickle.
variant (str, opsional) — Jika ditentukan, bobot disimpan dalam format pytorch_model.<variant>.bin.
max_shard_size (int atau str, default "10GB") — Ukuran maksimum untuk checkpoint sebelum di-shard. Checkpoint yang di-shard akan masing-masing berukuran lebih kecil dari ukuran ini. Jika dinyatakan sebagai string, harus berupa angka diikuti oleh satuan (seperti "5GB"). Jika dinyatakan sebagai integer, satuannya adalah byte. Perhatikan bahwa batas ini akan dikurangi setelah periode waktu tertentu (mulai dari Okt 2024) untuk memungkinkan pengguna melakukan upgrade ke versi terbaru dari diffusers. Hal ini dilakukan untuk menetapkan ukuran default yang umum untuk argumen ini di berbagai pustaka dalam ekosistem Hugging Face (misalnya transformers, dan accelerate).
push_to_hub (bool, opsional, default False) — Apakah model Anda akan didorong ke Hugging Face Hub setelah disimpan. Anda dapat menentukan repositori yang ingin Anda tuju dengan repo_id (defaultnya adalah nama save_directory di namespace Anda).
kwargs (dict[str, Any], opsional) — Argumen kata kunci tambahan yang diteruskan ke metode push_to_hub().

Simpan model dan file konfigurasinya ke sebuah direktori agar dapat dimuat ulang menggunakan metode kelas from_pretrained().

set_attention_backend

( backend: str )

Parameter

backend (str) — Nama backend yang akan disetel. Harus salah satu dari backend yang tersedia yang didefinisikan dalam AttentionBackendName. Backend yang tersedia dapat ditemukan di diffusers.attention_dispatch.AttentionBackendName. Secara default menggunakan torch native scaled dot product attention sebagai backend.

Atur backend perhatian untuk model.

set_use_npu_flash_attention

( valid: bool )

Atur sakelar untuk npu flash attention.

ke

( *args**kwargs )

Nilai mock untuk jalur bertitik (mis. torch.float32): rantai akses atribut, pemanggilan berperilaku sebagai dekorator pass-through, repr adalah jalur bertitik, dan penggunaannya sebagai kelas dasar menggantikan kelas dasar type polos (PEP 560 __mro_entries__), sehingga subkelas asli tetap mempertahankan metakelas normal dan inspect.signature membaca __init__ asli mereka, bukan milik mock.

PushToHubMixin

kelas diffusers.utils.PushToHubMixin

( )

Mixin untuk mendorong model, scheduler, atau pipeline ke 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 )

Parameter

repo_id (str) — Nama repositori tempat Anda ingin mendorong file model, scheduler, atau pipeline Anda. Seharusnya mengandung nama organisasi Anda saat mendorong ke organisasi. repo_id juga bisa berupa path ke direktori lokal.
commit_message (str, opsional) — Pesan untuk commit saat push. Default ke "Upload {object}".
private (bool, opsional) — Apakah membuat repo menjadi privat. Jika None (default), repo akan menjadi publik kecuali default organisasi adalah privat. Nilai ini diabaikan jika repo sudah ada.
token (str, opsional) — Token yang digunakan sebagai otorisasi bearer HTTP untuk file jarak jauh. Token yang dihasilkan saat menjalankan hf auth login (disimpan di ~/.huggingface).
create_pr (bool, opsional, default False) — Apakah akan membuat PR dengan file yang diunggah atau langsung melakukan commit.
safe_serialization (bool, opsional, defaultnya True) — Apakah akan mengonversi bobot model ke format safetensors.
variant (str, opsional) — Jika ditentukan, bobot disimpan dalam format pytorch_model.<variant>.bin.

Unggah file model, scheduler, atau pipeline ke 🤗 Hugging Face Hub.

Contoh:

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→