Hub Python Library documentation
Serialisasi
Serialisasi
huggingface_hub menyediakan helper untuk menyimpan dan memuat bobot model ML dengan cara yang terstandarisasi. Bagian pustaka ini masih dalam pengembangan dan akan ditingkatkan pada rilis mendatang. Tujuannya adalah untuk menyelaraskan cara bobot disimpan dan dimuat di seluruh Hub, baik untuk menghilangkan duplikasi kode antar pustaka maupun untuk menetapkan konvensi yang konsisten.
Format file DDUF
DDUF adalah format file yang dirancang untuk model difusi. Format ini memungkinkan penyimpanan semua informasi yang diperlukan untuk menjalankan model dalam satu file. Pekerjaan ini terinspirasi oleh format GGUF. huggingface_hub menyediakan helper untuk menyimpan dan memuat file DDUF, memastikan format file dipatuhi.
Ini adalah versi parser yang sangat awal. API dan implementasinya dapat berkembang dalam waktu dekat.
Parser saat ini melakukan validasi yang sangat sedikit. Untuk detail lebih lanjut tentang format file, lihat https://github.com/huggingface/huggingface.js/tree/main/packages/dduf.
Bagaimana cara menulis file DDUF?
Berikut cara mengekspor folder yang berisi berbagai bagian dari model difusi menggunakan export_folder_as_dduf():
# Export a folder as a DDUF file
>>> from huggingface_hub import export_folder_as_dduf
>>> export_folder_as_dduf("FLUX.1-dev.dduf", folder_path="path/to/FLUX.1-dev")Untuk fleksibilitas yang lebih besar, Anda dapat menggunakan export_entries_as_dduf() dan meneruskan daftar file yang akan disertakan dalam file DDUF akhir:
# Export specific files from the local disk.
>>> from huggingface_hub import export_entries_as_dduf
>>> export_entries_as_dduf(
... dduf_path="stable-diffusion-v1-4-FP16.dduf",
... entries=[ # List entries to add to the DDUF file (here, only FP16 weights)
... ("model_index.json", "path/to/model_index.json"),
... ("vae/config.json", "path/to/vae/config.json"),
... ("vae/diffusion_pytorch_model.fp16.safetensors", "path/to/vae/diffusion_pytorch_model.fp16.safetensors"),
... ("text_encoder/config.json", "path/to/text_encoder/config.json"),
... ("text_encoder/model.fp16.safetensors", "path/to/text_encoder/model.fp16.safetensors"),
... # ... add more entries here
... ]
... )Parameter entries juga mendukung pengiriman iterable dari path atau bytes. Hal ini dapat berguna jika Anda memiliki model yang sudah dimuat dan ingin langsung mengserialisasikannya ke dalam file DDUF, alih-alih harus mengserialisasikan setiap komponen ke disk terlebih dahulu dan kemudian sebagai file DDUF. Berikut adalah contoh bagaimana StableDiffusionPipeline dapat diserialisasikan sebagai DDUF:
# Export state_dicts one by one from a loaded pipeline
>>> from diffusers import DiffusionPipeline
>>> from typing import Generator, Tuple
>>> import safetensors.torch
>>> from huggingface_hub import export_entries_as_dduf
>>> pipe = DiffusionPipeline.from_pretrained("CompVis/stable-diffusion-v1-4")
... # ... do some work with the pipeline
>>> def as_entries(pipe: DiffusionPipeline) -> Generator[Tuple[str, bytes], None, None]:
... # Build a generator that yields the entries to add to the DDUF file.
... # The first element of the tuple is the filename in the DDUF archive (must use UNIX separator!). The second element is the content of the file.
... # Entries will be evaluated lazily when the DDUF file is created (only 1 entry is loaded in memory at a time)
... yield "vae/config.json", pipe.vae.to_json_string().encode()
... yield "vae/diffusion_pytorch_model.safetensors", safetensors.torch.save(pipe.vae.state_dict())
... yield "text_encoder/config.json", pipe.text_encoder.config.to_json_string().encode()
... yield "text_encoder/model.safetensors", safetensors.torch.save(pipe.text_encoder.state_dict())
... # ... add more entries here
>>> export_entries_as_dduf(dduf_path="stable-diffusion-v1-4.dduf", entries=as_entries(pipe))Catatan: dalam praktiknya, diffusers menyediakan metode untuk langsung melakukan serialisasi pipeline ke dalam file DDUF. Snippet di atas hanya dimaksudkan sebagai contoh.
Bagaimana cara membaca file DDUF?
>>> import json
>>> import safetensors.torch
>>> from huggingface_hub import read_dduf_file
# Read DDUF metadata
>>> dduf_entries = read_dduf_file("FLUX.1-dev.dduf")
# Returns a mapping filename <> DDUFEntry
>>> dduf_entries["model_index.json"]
DDUFEntry(filename='model_index.json', offset=66, length=587)
# Load model index as JSON
>>> json.loads(dduf_entries["model_index.json"].read_text())
{'_class_name': 'FluxPipeline', '_diffusers_version': '0.32.0.dev0', '_name_or_path': 'black-forest-labs/FLUX.1-dev', 'scheduler': ['diffusers', 'FlowMatchEulerDiscreteScheduler'], 'text_encoder': ['transformers', 'CLIPTextModel'], 'text_encoder_2': ['transformers', 'T5EncoderModel'], 'tokenizer': ['transformers', 'CLIPTokenizer'], 'tokenizer_2': ['transformers', 'T5TokenizerFast'], 'transformer': ['diffusers', 'FluxTransformer2DModel'], 'vae': ['diffusers', 'AutoencoderKL']}
# Load VAE weights using safetensors
>>> with dduf_entries["vae/diffusion_pytorch_model.safetensors"].as_mmap() as mm:
... state_dict = safetensors.torch.load(mm)Helper
huggingface_hub.export_entries_as_dduf
< source >( dduf_path: str | os.PathLikeentries: Iterable )
Parameter
- dduf_path (
stratauos.PathLike) — Path ke file DDUF yang akan ditulis. - entries (
Iterable[tuple[str, Union[str, Path, bytes]]]) — Iterable dari entri untuk ditulis ke dalam file DDUF. Setiap entri adalah tuple yang berisi nama file dan isinya. Nama file harus berupa path ke file dalam arsip DDUF. Isinya dapat berupa string atau pathlib.Path yang merepresentasikan path ke file di disk lokal, atau langsung berupa konten sebagai bytes.
Membuang
-
- —
DDUFExportError: Jika terjadi kesalahan selama proses ekspor (misalnya nama entri tidak valid, file ‘model_index.json’ tidak ditemukan, dll.).
- —
Tulis file DDUF dari iterable entri.
Ini adalah helper tingkat yang lebih rendah daripada export_folder_as_dduf() yang memberikan fleksibilitas lebih besar saat melakukan serialisasi data. Secara khusus, Anda tidak perlu menyimpan data ke disk terlebih dahulu sebelum mengekspornya ke file DDUF.
Contoh:
# Export specific files from the local disk.
>>> from huggingface_hub import export_entries_as_dduf
>>> export_entries_as_dduf(
... dduf_path="stable-diffusion-v1-4-FP16.dduf",
... entries=[ # List entries to add to the DDUF file (here, only FP16 weights)
... ("model_index.json", "path/to/model_index.json"),
... ("vae/config.json", "path/to/vae/config.json"),
... ("vae/diffusion_pytorch_model.fp16.safetensors", "path/to/vae/diffusion_pytorch_model.fp16.safetensors"),
... ("text_encoder/config.json", "path/to/text_encoder/config.json"),
... ("text_encoder/model.fp16.safetensors", "path/to/text_encoder/model.fp16.safetensors"),
... # ... add more entries here
... ]
... )# Export state_dicts one by one from a loaded pipeline
>>> from diffusers import DiffusionPipeline
>>> from typing import Generator, Tuple
>>> import safetensors.torch
>>> from huggingface_hub import export_entries_as_dduf
>>> pipe = DiffusionPipeline.from_pretrained("CompVis/stable-diffusion-v1-4")
... # ... do some work with the pipeline
>>> def as_entries(pipe: DiffusionPipeline) -> Generator[tuple[str, bytes], None, None]:
... # Build a generator that yields the entries to add to the DDUF file.
... # The first element of the tuple is the filename in the DDUF archive (must use UNIX separator!). The second element is the content of the file.
... # Entries will be evaluated lazily when the DDUF file is created (only 1 entry is loaded in memory at a time)
... yield "vae/config.json", pipe.vae.to_json_string().encode()
... yield "vae/diffusion_pytorch_model.safetensors", safetensors.torch.save(pipe.vae.state_dict())
... yield "text_encoder/config.json", pipe.text_encoder.config.to_json_string().encode()
... yield "text_encoder/model.safetensors", safetensors.torch.save(pipe.text_encoder.state_dict())
... # ... add more entries here
>>> export_entries_as_dduf(dduf_path="stable-diffusion-v1-4.dduf", entries=as_entries(pipe))huggingface_hub.export_folder_as_dduf
< source >( dduf_path: str | os.PathLikefolder_path: str | os.PathLike )
Ekspor folder sebagai file DDUF.
AMenggunakan export_entries_as_dduf() di balik layar.
huggingface_hub.read_dduf_file
< source >( dduf_path: os.PathLike | str ) → dict[str, DDUFEntry]
Parameter
Mengembalikan
dict[str, DDUFEntry]
Kamus DDUFEntry yang diindeks berdasarkan nama file.
Membuang
-
- —
DDUFCorruptedFileError: Jika file DDUF rusak (yaitu tidak mengikuti format DDUF).
- —
Baca file DDUF dan kembalikan kamus entri.
Hanya metadata yang dibaca, datanya tidak dimuat ke dalam memori.
Contoh:
>>> import json
>>> import safetensors.torch
>>> from huggingface_hub import read_dduf_file
# Read DDUF metadata
>>> dduf_entries = read_dduf_file("FLUX.1-dev.dduf")
# Returns a mapping filename <> DDUFEntry
>>> dduf_entries["model_index.json"]
DDUFEntry(filename='model_index.json', offset=66, length=587)
# Load model index as JSON
>>> json.loads(dduf_entries["model_index.json"].read_text())
{'_class_name': 'FluxPipeline', '_diffusers_version': '0.32.0.dev0', '_name_or_path': 'black-forest-labs/FLUX.1-dev', ...
# Load VAE weights using safetensors
>>> with dduf_entries["vae/diffusion_pytorch_model.safetensors"].as_mmap() as mm:
... state_dict = safetensors.torch.load(mm)kelas huggingface_hub.DDUFEntry
< source >( filename: strlength: intoffset: intdduf_path: Path )
Objek yang merepresentasikan entri file dalam file DDUF.
Lihat read_dduf_file() untuk cara membaca file DDUF.
Buka file sebagai file yang dipetakan ke memori.
Berguna untuk memuat safetensors langsung dari file.
Baca file sebagai teks.
Berguna untuk entri ‘.txt’ dan ‘.json’.
Kesalahan
Pengecualian dasar untuk kesalahan yang terkait dengan format DDUF.
Pengecualian dilempar ketika file DDUF rusak.
Pengecualian dasar untuk kesalahan selama ekspor DDUF.
Exception dilempar ketika nama entri tidak valid.
Menyimpan tensor
Helper utama dari modul serialization menerima torch nn.Module sebagai input dan menyimpannya ke disk. Helper ini menangani logika untuk menyimpan tensor bersama (lihat penjelasan safetensors) serta logika untuk memecah state dictionary menjadi shard, menggunakan split_torch_state_dict_into_shards() di baliknya. Saat ini, hanya framework torch yang didukung.
Jika Anda ingin menyimpan state dictionary (misalnya pemetaan antara nama layer dan tensor terkait) alih-alih nn.Module, Anda dapat menggunakan save_torch_state_dict() yang menyediakan fitur yang sama. Ini berguna, misalnya, jika Anda ingin menerapkan logika kustom pada state dict sebelum menyimpannya.
save_torch_model
huggingface_hub.save_torch_model
< source >( model: torch.nn.Modulesave_directory: str | pathlib.Pathfilename_pattern: str | None = Noneforce_contiguous: bool = Truemax_shard_size: int | str = '5GB'metadata: dict[str, str] | None = Nonesafe_serialization: bool = Trueis_main_process: bool = Trueshared_tensors_to_discard: list[str] | None = None )
Parameter
- model (
torch.nn.Module) — Model yang akan disimpan ke disk. - save_directory (
stratauPath) — Direktori tempat model akan disimpan. - filename_pattern (
str, opsional) — Pola untuk menghasilkan nama file tempat model akan disimpan. Pola harus berupa string yang dapat diformat denganfilename_pattern.format(suffix=...)dan harus mengandung kata kuncisuffixBawaan adalah"model{suffix}.safetensors"ataupytorch_model{suffix}.bintergantung pada parametersafe_serialization. - force_contiguous (
boolean, opsional) — Memaksa state_dict disimpan sebagai tensor yang contiguous. Hal ini tidak memengaruhi kebenaran model, tetapi berpotensi mengubah kinerja jika tata letak tensor dipilih secara khusus untuk alasan tersebut. Nilainya secara default adalahTrue. - max_shard_size (
intataustr, opsional) — Ukuran maksimum setiap shard, dalam byte. Defaultnya 5GB. - metadata (
dict[str, str], opsional) — Informasi tambahan untuk disimpan bersama model. Beberapa metadata akan ditambahkan untuk setiap tensor yang dihapus. Informasi ini tidak akan cukup untuk memulihkan struktur bersama secara keseluruhan, tetapi mungkin membantu memahami hal-hal tersebut. - safe_serialization (
bool, opsional) — Apakah menyimpan sebagai safetensors, yang merupakan perilaku default. JikaFalse, shard disimpan sebagai pickle. Serialisasi aman direkomendasikan karena alasan keamanan. Menyimpan sebagai pickle sudah tidak didukung (deprecated) dan akan dihapus pada versi mendatang. - is_main_process (
bool, opsional) — Apakah proses yang memanggil ini adalah proses utama atau tidak. Berguna saat dalam pelatihan terdistribusi seperti TPUs dan perlu memanggil fungsi ini dari semua proses. Dalam kasus ini, aturis_main_process=Truehanya pada proses utama untuk menghindari kondisi balapan. Bawaan adalah True. - shared_tensors_to_discard (
list[str], opsional) — Daftar nama tensor yang akan dihapus saat menyimpan tensor bersama. Jika tidak disediakan dan tensor bersama terdeteksi, nama pertama secara alfabetis akan dihapus.
Menyimpan model torch tertentu ke disk, menangani masalah sharding dan tensor bersama.
Lihat juga save_torch_state_dict() untuk menyimpan state dict dengan fleksibilitas yang lebih besar.
Untuk informasi lebih lanjut tentang berbagi tensor, lihat panduan ini.
Kamus state model dipecah menjadi beberapa shard sehingga setiap shard lebih kecil dari ukuran tertentu. Shard disimpan di save_directory dengan filename_pattern yang diberikan. Jika model terlalu besar untuk muat dalam satu shard, file indeks disimpan di save_directory untuk menunjukkan di mana setiap tensor disimpan. Helper ini menggunakan split_torch_state_dict_into_shards() di baliknya. Jika safe_serialization adalah True, shard disimpan sebagai safetensors (default). Sebaliknya, shard disimpan sebagai pickle.
Sebelum menyimpan model, save_directory dibersihkan dari file shard sebelumnya.
Jika salah satu tensor model lebih besar dari
max_shard_size, tensor tersebut akan berakhir di shard tersendiri yang ukurannya lebih besar darimax_shard_size.
Jika model Anda adalah
transformers.PreTrainedModel, Anda harus meneruskanmodel._tied_weights_keyssebagaishared_tensors_to_discarduntuk menangani penyimpanan tensor bersama dengan benar. Hal ini memastikan tensor duplikat yang tepat dibuang selama penyimpanan.
Contoh:
>>> from huggingface_hub import save_torch_model
>>> model = ... # A PyTorch model
# Save state dict to "path/to/folder". The model will be split into shards of 5GB each and saved as safetensors.
>>> save_torch_model(model, "path/to/folder")
# Load model back
>>> from huggingface_hub import load_torch_model # TODO
>>> load_torch_model(model, "path/to/folder")
>>>save_torch_state_dict
huggingface_hub.save_torch_state_dict
< source >( state_dict: dictsave_directory: str | pathlib.Pathfilename_pattern: str | None = Noneforce_contiguous: bool = Truemax_shard_size: int | str = '5GB'metadata: dict[str, str] | None = Nonesafe_serialization: bool = Trueis_main_process: bool = Trueshared_tensors_to_discard: list[str] | None = None )
Parameter
- state_dict (
dict[str, torch.Tensor]) — Kamus status yang akan disimpan. - save_directory (
stratauPath) — Direktori tempat model akan disimpan. - filename_pattern (
str, opsional) — Pola untuk menghasilkan nama file tempat model akan disimpan. Pola harus berupa string yang dapat diformat denganfilename_pattern.format(suffix=...)dan harus mengandung kata kuncisuffixBawaan adalah"model{suffix}.safetensors"ataupytorch_model{suffix}.bintergantung pada parametersafe_serialization. - force_contiguous (
boolean, opsional) — Memaksa state_dict disimpan sebagai tensor yang contiguous. Hal ini tidak memengaruhi kebenaran model, tetapi berpotensi mengubah kinerja jika tata letak tensor dipilih secara khusus untuk alasan tersebut. Nilainya secara default adalahTrue. - max_shard_size (
intataustr, opsional) — Ukuran maksimum setiap shard, dalam byte. Defaultnya 5GB. - metadata (
dict[str, str], opsional) — Informasi tambahan untuk disimpan bersama model. Beberapa metadata akan ditambahkan untuk setiap tensor yang dihapus. Informasi ini tidak akan cukup untuk memulihkan struktur bersama secara keseluruhan, tetapi mungkin membantu memahami hal-hal tersebut. - safe_serialization (
bool, opsional) — Apakah menyimpan sebagai safetensors, yang merupakan perilaku default. JikaFalse, shard disimpan sebagai pickle. Serialisasi aman direkomendasikan karena alasan keamanan. Menyimpan sebagai pickle sudah tidak didukung (deprecated) dan akan dihapus pada versi mendatang. - is_main_process (
bool, opsional) — Apakah proses yang memanggil ini adalah proses utama atau tidak. Berguna saat dalam pelatihan terdistribusi seperti TPUs dan perlu memanggil fungsi ini dari semua proses. Dalam kasus ini, aturis_main_process=Truehanya pada proses utama untuk menghindari kondisi balapan. Bawaan adalah True. - shared_tensors_to_discard (
list[str], opsional) — Daftar nama tensor yang akan dihapus saat menyimpan tensor bersama. Jika tidak disediakan dan tensor bersama terdeteksi, nama pertama secara alfabetis akan dihapus.
Simpan kamus status model ke disk, menangani masalah sharding dan tensor bersama.
Lihat juga save_torch_model() untuk menyimpan model PyTorch secara langsung.
Untuk informasi lebih lanjut tentang berbagi tensor, lihat panduan ini.
Kamus state model dipecah menjadi beberapa shard sehingga setiap shard lebih kecil dari ukuran tertentu. Shard disimpan di save_directory dengan filename_pattern yang diberikan. Jika model terlalu besar untuk muat dalam satu shard, file indeks disimpan di save_directory untuk menunjukkan di mana setiap tensor disimpan. Helper ini menggunakan split_torch_state_dict_into_shards() di baliknya. Jika safe_serialization adalah True, shard disimpan sebagai safetensors (default). Sebaliknya, shard disimpan sebagai pickle.
Sebelum menyimpan model, save_directory dibersihkan dari file shard sebelumnya.
Jika salah satu tensor model lebih besar dari
max_shard_size, tensor tersebut akan berakhir di shard tersendiri yang ukurannya lebih besar darimax_shard_size.
Jika model Anda adalah
transformers.PreTrainedModel, Anda harus meneruskanmodel._tied_weights_keyssebagaishared_tensors_to_discarduntuk menangani penyimpanan tensor bersama dengan benar. Hal ini memastikan tensor duplikat yang tepat dibuang selama penyimpanan.
Contoh:
>>> from huggingface_hub import save_torch_state_dict
>>> model = ... # A PyTorch model
# Save state dict to "path/to/folder". The model will be split into shards of 5GB each and saved as safetensors.
>>> state_dict = model_to_save.state_dict()
>>> save_torch_state_dict(state_dict, "path/to/folder")Modul serialization juga berisi helper tingkat rendah untuk memecah state dictionary menjadi beberapa shard, sambil membuat indeks yang tepat dalam prosesnya. Helper ini tersedia untuk tensor torch dan dirancang agar mudah diperluas ke framework ML lainnya.
split_torch_state_dict_into_shards
huggingface_hub.split_torch_state_dict_into_shards
< source >( state_dict: dictfilename_pattern: str = 'model{suffix}.safetensors'max_shard_size: int | str = '5GB' ) → StateDictSplit
Parameter
- state_dict (
dict[str, torch.Tensor]) — Kamus status yang akan disimpan. - filename_pattern (
str, opsional) — Pola untuk menghasilkan nama file tempat model akan disimpan. Pola harus berupa string yang dapat diformat denganfilename_pattern.format(suffix=...)dan harus mengandung kata kuncisuffixBawaan adalah"model{suffix}.safetensors". - max_shard_size (
intataustr, opsional) — Ukuran maksimum setiap shard, dalam byte. Defaultnya 5GB.
Mengembalikan
StateDictSplit
Objek StateDictSplit yang berisi shard dan indeks untuk mengambilnya.
Pisahkan kamus status model menjadi beberapa fragmen agar setiap fragmen lebih kecil dari ukuran tertentu.
Shard ditentukan dengan mengiterasi state_dict sesuai urutan kuncinya. Tidak ada optimasi yang dilakukan untuk membuat setiap shard sedekat mungkin dengan ukuran maksimum yang diberikan. Misalnya, jika batasnya adalah 10GB dan kita memiliki tensor dengan ukuran [6GB, 6GB, 2GB, 6GB, 2GB, 2GB], mereka akan di-shard menjadi [6GB], [6+2GB], [6+2+2GB] dan bukan [6+2+2GB], [6+2GB], [6GB].
Untuk menyimpan kamus status model ke disk, lihat save_torch_state_dict(). Helper ini menggunakan
split_torch_state_dict_into_shardsdi baliknya.
Jika salah satu tensor model lebih besar dari
max_shard_size, tensor tersebut akan berakhir di shard tersendiri yang ukurannya lebih besar darimax_shard_size.
Contoh:
>>> import json
>>> import os
>>> from safetensors.torch import save_file as safe_save_file
>>> from huggingface_hub import split_torch_state_dict_into_shards
>>> def save_state_dict(state_dict: dict[str, torch.Tensor], save_directory: str):
... state_dict_split = split_torch_state_dict_into_shards(state_dict)
... for filename, tensors in state_dict_split.filename_to_tensors.items():
... shard = {tensor: state_dict[tensor] for tensor in tensors}
... safe_save_file(
... shard,
... os.path.join(save_directory, filename),
... metadata={"format": "pt"},
... )
... if state_dict_split.is_sharded:
... index = {
... "metadata": state_dict_split.metadata,
... "weight_map": state_dict_split.tensor_to_filename,
... }
... with open(os.path.join(save_directory, "model.safetensors.index.json"), "w") as f:
... f.write(json.dumps(index, indent=2))split_state_dict_into_shards_factory
Ini adalah pabrik dasar yang menjadi asal turunan setiap helper yang spesifik untuk framework tertentu. Dalam praktiknya, Anda tidak diharapkan untuk menggunakan pabrik ini secara langsung, kecuali jika Anda perlu menyesuaikannya dengan framework yang belum didukung. Jika demikian, silakan beri tahu kami dengan membuka issue baru di repo huggingface_hub.
huggingface_hub.split_state_dict_into_shards_factory
< source >( state_dict: dictget_storage_size: Callablefilename_pattern: strget_storage_id: Callable = <function <lambda> at 0x7f9673968670>max_shard_size: int | str = '5GB' ) → StateDictSplit
Parameter
- state_dict (
dict[str, Tensor]) — Kamus status yang akan disimpan. - get_storage_size (
Callable[[Tensor], int]) — Fungsi yang mengembalikan ukuran tensor saat disimpan di disk dalam byte. - get_storage_id (
Callable[[Tensor], Optional[Any]], opsional) — Fungsi yang mengembalikan pengidentifikasi unik untuk penyimpanan tensor. Beberapa tensor yang berbeda dapat berbagi penyimpanan dasar yang sama. Pengidentifikasi ini dijamin unik dan konstan untuk penyimpanan tensor ini selama masa hidupnya. Dua penyimpanan tensor dengan masa hidup yang tidak tumpang tindih dapat memiliki id yang sama. - filename_pattern (
str, opsional) — Pola untuk menghasilkan nama file tempat model akan disimpan. Pola harus berupa string yang dapat diformat denganfilename_pattern.format(suffix=...)dan harus mengandung kata kuncisuffix - max_shard_size (
intataustr, opsional) — Ukuran maksimum setiap shard, dalam byte. Defaultnya 5GB.
Mengembalikan
StateDictSplit
Objek StateDictSplit yang berisi shard dan indeks untuk mengambilnya.
Pisahkan kamus status model menjadi beberapa fragmen agar setiap fragmen lebih kecil dari ukuran tertentu.
Shard ditentukan dengan mengiterasi state_dict sesuai urutan kuncinya. Tidak ada optimasi yang dilakukan untuk membuat setiap shard sedekat mungkin dengan ukuran maksimum yang diberikan. Misalnya, jika batasnya adalah 10GB dan kita memiliki tensor dengan ukuran [6GB, 6GB, 2GB, 6GB, 2GB, 2GB], mereka akan di-shard menjadi [6GB], [6+2GB], [6+2+2GB] dan bukan [6+2+2GB], [6+2GB], [6GB].
Jika salah satu tensor model lebih besar dari
max_shard_size, tensor tersebut akan berakhir di shard tersendiri yang ukurannya lebih besar darimax_shard_size.
Memuat tensor
Helper pemuatan mendukung checkpoint tunggal dan terpecah dalam format safetensors atau pickle. load_torch_model() menerima nn.Module dan path checkpoint (baik file tunggal maupun direktori) sebagai input, lalu memuat bobot ke dalam model.
Kedua helper ini secara default menggunakan
safe=True, yang berarti checkpoint selalu dideserialisasi dengan loader safetensors — apa pun nama filenya. Memuat checkpoint pickle memerlukan opt-in secara eksplisit, karena unpickling mengeksekusi kode arbitrer saat pemuatan:>>> from huggingface_hub import load_state_dict_from_file, load_torch_model # Raises: the file is not safetensors >>> load_state_dict_from_file("path/to/pytorch_model.bin") >>> load_torch_model(model, "path/to/pytorch_model.bin") # Explicit opt-in >>> load_state_dict_from_file("path/to/pytorch_model.bin", safe=False) >>> load_torch_model(model, "path/to/pytorch_model.bin", safe=False)Jalur pickle secara default juga menggunakan
weights_only=True, yaitu unpickler terbatas dari torch. Checkpoint yang berisi objek non-tensor (state optimizer, seluruh model, …) memerlukanweights_only=Falsedi sampingsafe=False.
load_torch_model
huggingface_hub.load_torch_model
< source >( model: torch.nn.Modulecheckpoint_path: str | os.PathLikestrict: bool = Falsesafe: bool = Trueweights_only: bool = Truemap_location: typing.Union[str, ForwardRef('torch.device'), NoneType] = Nonemmap: bool = Falsefilename_pattern: str | None = None ) → NamedTuple
Parameter
- model (
torch.nn.Module) — Model tempat checkpoint dimuat. - checkpoint_path (
stratauos.PathLike) — Path ke file checkpoint atau direktori yang berisi checkpoint. - strict (
bool, opsional, defaultFalse) — Apakah akan menegakkan secara ketat bahwa kunci dalam state dict model harus cocok dengan kunci dalam checkpoint. Sama sepertitorch.nn.Module.load_state_dict, pemeriksaan dilakukan setelah checkpoint dimuat, sehingga model mungkin sudah diperbarui sebagian ketika error dilempar. - safe (
bool, opsional, defaultTrue) — Jikasafebernilai True, file safetensors akan dimuat. Jikasafebernilai False, fungsi tersebut akan terlebih dahulu mencoba memuat file safetensors jika tersedia, jika tidak, akan beralih ke memuat file pickle.filename_patternyang tidak mendeskripsikan file safetensors akan ditolak ketikasafe=True. - weights_only (
bool, opsional, defaultTrue) — Jika True, hanya memuat bobot model tanpa status optimizer dan metadata lainnya, menggunakan unpickler terbatas dari torch. Atur ke False untuk mengizinkan objek Python arbitrer dalam checkpoint pickle (hal ini mengeksekusi kode arbitrer saat pemuatan). Tidak berpengaruh pada PyTorch < 1.13, yang tidak memiliki unpickler terbatas dan selalu melakukan unpickle tanpa batasan. - map_location (
stratautorch.device, opsional) — Objektorch.device, string, atau dict yang menentukan cara memetakan ulang lokasi penyimpanan. Ini menunjukkan lokasi di mana semua tensor harus dimuat. - mmap (
bool, opsional, defaultFalse) — Apakah akan menggunakan pemuatan file berbasis memory-mapped. Pemetaan memori dapat meningkatkan kinerja pemuatan untuk model besar di PyTorch >= 2.1.0 dengan checkpoint berbasis zipfile. - filename_pattern (
str, opsional) — Pola untuk mencari file indeks. Pola harus berupa string yang dapat diformat denganfilename_pattern.format(suffix=...)dan harus mengandung kata kuncisuffixBawaan adalah"model{suffix}.safetensors".
Mengembalikan
NamedTuple
Named tuple dengan field missing_keys dan unexpected_keys.
missing_keysadalah daftar str yang berisi kunci yang hilang, yaitu kunci yang ada di model tetapi tidak ada di checkpoint.unexpected_keysadalah daftar str yang berisi kunci yang tidak terduga, yaitu kunci yang ada di checkpoint tetapi tidak ada di model.
Membuang
FileNotFoundError atau ImportError atau ValueError
FileNotFoundError— Jika file atau direktori checkpoint tidak ada.ImportError— Jika safetensors atau torch tidak terpasang saat mencoba memuat file .safetensors atau checkpoint PyTorch, masing-masing.ValueError— Jika format checkpoint tidak dapat ditentukan.
Muat checkpoint ke dalam model, menangani checkpoint yang terpecah (sharded) maupun yang tidak terpecah.
load_state_dict_from_file
huggingface_hub.load_state_dict_from_file
< source >( checkpoint_file: str | os.PathLikemap_location: typing.Union[str, ForwardRef('torch.device'), NoneType] = Noneweights_only: bool = Truemmap: bool = Falsesafe: bool = True ) → Union[dict[str, "torch.Tensor"], Any]
Parameter
- checkpoint_file (
stratauos.PathLike) — Path ke file checkpoint yang akan dimuat. Bisa berupa checkpoint safetensors atau pickle (.bin). - map_location (
stratautorch.device, opsional) — Objektorch.device, string, atau dict yang menentukan cara memetakan ulang lokasi penyimpanan. Ini menunjukkan lokasi di mana semua tensor harus dimuat. - weights_only (
bool, opsional, defaultTrue) — Jika True, hanya memuat bobot model tanpa status optimizer dan metadata lainnya, menggunakan unpickler terbatas dari torch. Atur ke False untuk mengizinkan objek Python arbitrer dalam checkpoint pickle (hal ini mengeksekusi kode arbitrer saat pemuatan). Tidak berpengaruh saat memuat file safetensors, maupun pada PyTorch < 1.13 yang tidak memiliki unpickler terbatas — versi-versi tersebut selalu melakukan unpickle tanpa pembatasan dan sebuah peringatan dicatat. - mmap (
bool, opsional, defaultFalse) — Apakah akan menggunakan pemuatan file berbasis memory-mapped. Pemetaan memori dapat meningkatkan kinerja pemuatan untuk model besar di PyTorch >= 2.1.0 dengan checkpoint berbasis zipfile. Tidak berpengaruh saat memuat file safetensors, karena pustakasafetensorsmenggunakan pemetaan memori secara default. - safe (
bool, opsional, defaultTrue) — Jika True, checkpoint selalu dimuat sebagai safetensors, apa pun namanya. Format lain (misalnya file pickle.bin) akan memicuValueErroralih-alih dideserialisasi: checkpoint pickle dapat mengeksekusi kode arbitrer saat dimuat. Jika False, file dimuat sebagai safetensors jika namanya mengindikasikan demikian, dan dengantorch.loadjika tidak.
Mengembalikan
Union[dict[str, "torch.Tensor"], Any]
Checkpoint yang dimuat.
- Untuk file safetensors: selalu mengembalikan kamus yang memetakan nama parameter ke tensor.
- Untuk file pickle: mengembalikan objek Python apa pun yang di-pickle (umumnya state dict, tetapi bisa juga seluruh model, state optimizer, atau objek Python lainnya).
Membuang
FileNotFoundError atau ImportError atau OSError atau ValueError
FileNotFoundError— Jika file checkpoint tidak ada.ImportError— Jika safetensors atau torch tidak terpasang saat mencoba memuat file .safetensors atau checkpoint PyTorch, masing-masing.OSError— Jika format file checkpoint tidak valid atau jika file git-lfs tidak diunduh dengan benar.ValueError— Jika jalur file checkpoint kosong atau tidak valid, atau jika file tersebut tidak dapat dideserialisasi sebagai safetensors saatsafe=True(lalusafe=Falseuntuk mengizinkan checkpoint pickle).
Memuat file checkpoint, menangani format checkpoint safetensors dan pickle.
Contoh:
>>> from huggingface_hub import load_state_dict_from_file
# Load a safetensors checkpoint (safe by default)
>>> state_dict = load_state_dict_from_file("path/to/model.safetensors", safe=True)
>>> model.load_state_dict(state_dict)
# Load a pickle checkpoint. `safe=False` is required: pickle files can execute arbitrary code.
>>> state_dict = load_state_dict_from_file("path/to/model.bin", safe=False, map_location="cpu")
>>> model.load_state_dict(state_dict)Helper tensor
get_torch_storage_id
Kembalikan pengenal unik ke penyimpanan tensor.
Beberapa tensor yang berbeda dapat berbagi penyimpanan (storage) yang sama. Identifikasi ini dijamin unik dan konstan untuk penyimpanan tensor ini selama masa hidupnya. Dua penyimpanan tensor dengan masa hidup yang tidak tumpang tindih dapat memiliki id yang sama. Untuk tensor meta, kami mengembalikan None karena kami tidak dapat menentukan apakah mereka berbagi penyimpanan yang sama.