Hugging Face's logo

Hub Python Library documentation

Seri hale getirme

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Seri hale getirme

huggingface_hub, makine öğrenimi model ağırlıklarını standart bir şekilde kaydetmek ve yüklemek için yardımcı işlevler sunar. Kütüphanenin bu bölümü hâlâ geliştirme aşamasındadır ve gelecekteki sürümlerde iyileştirilecektir. Amaç, ağırlıkların Hub genelinde nasıl kaydedildiğini ve yüklendiğini uyumlu hale getirmek; böylece kütüphaneler arası kod tekrarı ortadan kaldırılır ve tutarlı kurallar oluşturulur.

DDUF dosya biçimi

DDUF, difüzyon modelleri için tasarlanmış bir dosya biçimidir. Bir modeli çalıştırmak için gereken tüm bilgilerin tek bir dosyada kaydedilmesini sağlar. Bu çalışma, GGUF biçiminden ilham almıştır. huggingface_hub, DDUF dosyalarının kaydedilip yüklenmesi için yardımcı işlevler sunarak dosya biçiminin korunmasını garanti eder.

Bu, ayrıştırıcının çok erken bir sürümüdür. API ve uygulama yakın gelecekte evrilebilir.

Ayrıştırıcı şu anda çok az doğrulama yapıyor. Dosya biçimi hakkında daha fazla ayrıntı için https://github.com/huggingface/huggingface.js/tree/main/packages/dduf adresine göz atın.

DDUF dosyası nasıl yazılır?

Bir difüzyon modelinin farklı parçalarını içeren bir klasörü export_folder_as_dduf() kullanarak dışa aktarma yöntemi aşağıdaki gibidir:

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

Daha fazla esneklik için export_entries_as_dduf() işlevini kullanabilir ve nihai DDUF dosyasına dahil edilecek dosyaların listesini iletebilirsiniz:

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

entries parametresi, yol veya bayt içeren bir yinelebilir nesne geçilmesini de destekler. Yüklenmiş bir modeliniz varsa ve her bileşeni önce diske serialize edip ardından DDUF dosyası olarak serialize etmek yerine doğrudan bir DDUF dosyasına serialize etmek istiyorsanız bu işe yarayabilir. Bir StableDiffusionPipeline'in DDUF olarak nasıl serialize edilebileceğine dair bir örnek aşağıdadır:

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

Not: pratikte, diffusers bir pipeline'ı doğrudan bir DDUF dosyasına serialize etmek için bir yöntem sağlar. Yukarıdaki kod parçası yalnızca bir örnek olarak verilmiştir.

DDUF dosyası nasıl okunur?

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

Yardımcılar

huggingface_hub.export_entries_as_dduf

< >

( dduf_path: str | os.PathLikeentries: Iterable )

Parametreler

  • dduf_path (str veya os.PathLike) — Yazılacak DDUF dosyasının yolu.
  • entries (Iterable[tuple[str, Union[str, Path, bytes]]]) — DDUF dosyasına yazılacak girdilerin bir iterable'ı. Her girdi, dosya adını ve içeriğini içeren bir tuple'dır. Dosya adı, DDUF arşivindeki dosyanın yolunu belirtmelidir. İçerik, yerel diskteki bir dosyanın yolunu temsil eden bir string veya pathlib.Path ya da doğrudan bytes olarak içerik olabilir.

Yükseltilen

    • — DDUFExportError: Dışa aktarma sırasında bir sorun oluşursa (ör. geçersiz giriş adı, eksik ‘model_index.json’ vb.).

Bir girdi iterablesinden bir DDUF dosyası yazın.

Bu, export_folder_as_dduf() işlevinden daha düşük seviyeli bir yardımcıdır ve verileri seri hale getirirken daha fazla esneklik sağlar. Özellikle, verileri DDUF dosyasına dışa aktarmadan önce diskte saklamanız gerekmez.

Örnek:

# 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

< >

( dduf_path: str | os.PathLikefolder_path: str | os.PathLike )

Parametreler

  • dduf_path (str veya os.PathLike) — Yazılacak DDUF dosyasının yolu.
  • folder_path (str veya os.PathLike) — Difüzyon modelini içeren klasörün yolu.

Bir klasörü DDUF dosyası olarak dışa aktarın.

Aexport_entries_as_dduf() işlevini kullanır.

Örnek:

>>> from huggingface_hub import export_folder_as_dduf
>>> export_folder_as_dduf(dduf_path="FLUX.1-dev.dduf", folder_path="path/to/FLUX.1-dev")

huggingface_hub.read_dduf_file

< >

( dduf_path: os.PathLike | str ) → dict[str, DDUFEntry]

Parametreler

  • dduf_path (str veya os.PathLike) — Okunacak DDUF dosyasının yolu.

Dönüş değeri

dict[str, DDUFEntry]

Dosya adıyla indekslenmiş DDUFEntry sözlüğü.

Yükseltilen

    • — DDUFCorruptedFileError: DDUF dosyası bozuksa (yani DDUF formatına uymuyorsa).

Bir DDUF dosyasını okur ve girdilerin sözlüğünü döndürür.

Yalnızca meta veriler okunur, veriler belleğe yüklenmez.

Örnek:

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

sınıf huggingface_hub.DDUFEntry

< >

( filename: strlength: intoffset: intdduf_path: Path )

Parametreler

  • filename (str) — DDUF arşivindeki dosyanın adı.
  • offset (int) — DDUF arşivindeki dosyanın ofseti.
  • length (int) — DDUF arşivindeki dosyanın uzunluğu.
  • dduf_path (str) — DDUF arşivine giden yol (iç kullanım için).

DDUF dosyasındaki bir dosya girdisini temsil eden nesne.

Bir DDUF dosyasını nasıl okuyacağınızı görmek için read_dduf_file() bölümüne bakın.

as_mmap

< >

( )

Dosyayı bellek eşlemeli dosya olarak açın.

Dosyadan doğrudan safetensors yüklemek için faydalıdır.

Örnek:

>>> import safetensors.torch
>>> with entry.as_mmap() as mm:
...     tensors = safetensors.torch.load(mm)

read_text

< >

( encoding: str = 'utf-8' )

Dosyayı metin olarak okuyun.

‘.txt’ ve ‘.json’ girdileri için kullanışlıdır.

Örnek:

>>> import json
>>> index = json.loads(entry.read_text())

Hatalar

sınıf huggingface_hub.errors.DDUFError

< >

( )

DDUF formatıyla ilgili hatalar için temel istisna.

sınıf huggingface_hub.errors.DDUFCorruptedFileError

< >

( )

DDUF dosyası bozuk olduğunda atılan istisna.

sınıf huggingface_hub.errors.DDUFExportError

< >

( )

DDUF dışa aktarma sırasında oluşan hatalar için temel istisna.

sınıf huggingface_hub.errors.DDUFInvalidEntryNameError

< >

( )

Girdi adı geçersiz olduğunda atılan istisna.

Gergilerin kaydedilmesi

serialization modülünün ana yardımcı işlevi, girdi olarak bir torch nn.Module alır ve diske kaydeder. Ortak tensörleri kaydetme mantığını (bkz. safetensors açıklaması) ve split_torch_state_dict_into_shards() işlevini kullanarak durum sözlüğünü parçalara ayırma mantığını ele alır. Şu anda yalnızca torch çerçevesi desteklenmektedir.

nn.Module yerine bir durum sözlüğü (ör. katman adları ile ilgili tensörler arasındaki eşleme) kaydetmek istiyorsanız, aynı özellikleri sunan save_torch_state_dict() işlevini kullanabilirsiniz. Bu, örneğin durum sözlüğünü kaydetmeden önce özel bir mantık uygulamak istediğinizde faydalıdır.

save_torch_model

huggingface_hub.save_torch_model

< >

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

Parametreler

  • model (torch.nn.Module) — Diskte kaydedilecek model.
  • save_directory (str veya Path) — Modelin kaydedileceği dizin.
  • filename_pattern (str, isteğe bağlı) — Modelin kaydedileceği dosya adlarını oluşturmak için kullanılacak desen. Desen, filename_pattern.format(suffix=...) ile biçimlendirilebilen ve suffix anahtar kelimesini içeren bir dize olmalıdır. Varsayılan değer, safe_serialization parametresine bağlı olarak "model{suffix}.safetensors" veya pytorch_model{suffix}.bin şeklindedir.
  • force_contiguous (boolean, isteğe bağlı) — state_dict'in ardışık (contiguous) tensörler olarak kaydedilmesini zorlar. Bu, modelin doğruluğu üzerinde bir etkiye sahip değildir ancak tensörün yerleşimi bu amaçla özellikle seçildiyse performansını potansiyel olarak değiştirebilir. Varsayılan değeri True'dur.
  • max_shard_size (int veya str, isteğe bağlı) — Her shard'ın bayt cinsinden maksimum boyutu. Varsayılan değer 5GB'dır.
  • metadata (dict[str, str], isteğe bağlı) — Modelle birlikte kaydedilecek ek bilgiler. Her atılan tensör için bazı metadata eklenir. Bu bilgiler, paylaşılan yapının tamamını geri getirmek için yeterli olmayabilir ancak konuları anlamaya yardımcı olabilir.
  • safe_serialization (bool, isteğe bağlı) — Varsayılan davranış olan safetensors olarak kaydetme durumu. False ise, parçalar pickle olarak kaydedilir. Güvenlik nedenleriyle güvenli seri hale getirme önerilir. Pickle olarak kaydetme kullanımdan kaldırılmıştır ve gelecekteki bir sürümde kaldırılacaktır.
  • is_main_process (bool, isteğe bağlı) — Bu fonksiyonu çağıran sürecin ana süreç olup olmadığı. TPUs gibi dağıtık eğitim ortamlarında ve bu fonksiyonun tüm süreçlerden çağrılması gerektiğinde kullanışlıdır. Bu durumda, yarış durumlarını (race condition) önlemek için is_main_process=True değerini yalnızca ana süreçte ayarlayın. Varsayılan değer True'dur.
  • shared_tensors_to_discard (list[str], isteğe bağlı) — Paylaşılan tensörleri kaydetirken atılacak tensör adlarının listesi. Sağlanmaz ve paylaşılan tensörler algılanırsa, alfabetik olarak ilk gelen ad atılır.

Belirli bir torch modelini diske kaydeder; şeritlere bölme (sharding) ve paylaşılan tensör sorunlarını ele alır.

Daha fazla esneklikle bir durum sözlüğü kaydetmek için ayrıca save_torch_state_dict() işlevine de bakın.

Tensor paylaşımı hakkında daha fazla bilgi için bu kılavuza göz atın.

Model durum sözlüğü, her parçanın verilen boyuttan küçük olması için parçalara ayrılır. Parçalar, verilen filename_pattern ile save_directory içinde kaydedilir. Model, tek bir parçaya sığmayacak kadar büyükse, her tensörün nerede kaydedildiğini belirtmek için bir indeks dosyası save_directory içinde kaydedilir. Bu yardımcı, arka planda split_torch_state_dict_into_shards() kullanır. safe_serialization True ise, parçalar safetensors olarak kaydedilir (varsayılan). Aksi takdirde, parçalar pickle olarak kaydedilir.

Model kaydedilmeden önce, save_directory önceki parça dosyalarından temizlenir.

Modelin bir tensörü max_shard_size değerinden büyükse, kendi parçasına yerleştirilir ve bu parçanın boyutu max_shard_size değerinden büyük olur.

Modeliniz transformers.PreTrainedModel ise, paylaşılan tensörlerin kaydedilmesini doğru şekilde işlemek için model._tied_weights_keys değerini shared_tensors_to_discard parametresi olarak geçirmelisiniz. Bu, kaydetme sırasında doğru yinelenen tensörlerin atılmasını sağlar.

Örnek:

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

< >

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

Parametreler

  • state_dict (dict[str, torch.Tensor]) — Kaydedilecek durum sözlüğü.
  • save_directory (str veya Path) — Modelin kaydedileceği dizin.
  • filename_pattern (str, isteğe bağlı) — Modelin kaydedileceği dosya adlarını oluşturmak için kullanılacak desen. Desen, filename_pattern.format(suffix=...) ile biçimlendirilebilen ve suffix anahtar kelimesini içeren bir dize olmalıdır. Varsayılan değer, safe_serialization parametresine bağlı olarak "model{suffix}.safetensors" veya pytorch_model{suffix}.bin şeklindedir.
  • force_contiguous (boolean, isteğe bağlı) — state_dict'in ardışık (contiguous) tensörler olarak kaydedilmesini zorlar. Bu, modelin doğruluğu üzerinde bir etkiye sahip değildir ancak tensörün yerleşimi bu amaçla özellikle seçildiyse performansını potansiyel olarak değiştirebilir. Varsayılan değeri True'dur.
  • max_shard_size (int veya str, isteğe bağlı) — Her shard'ın bayt cinsinden maksimum boyutu. Varsayılan değer 5GB'dır.
  • metadata (dict[str, str], isteğe bağlı) — Modelle birlikte kaydedilecek ek bilgiler. Her atılan tensör için bazı metadata eklenir. Bu bilgiler, paylaşılan yapının tamamını geri getirmek için yeterli olmayabilir ancak konuları anlamaya yardımcı olabilir.
  • safe_serialization (bool, isteğe bağlı) — Varsayılan davranış olan safetensors olarak kaydetme durumu. False ise, parçalar pickle olarak kaydedilir. Güvenlik nedenleriyle güvenli seri hale getirme önerilir. Pickle olarak kaydetme kullanımdan kaldırılmıştır ve gelecekteki bir sürümde kaldırılacaktır.
  • is_main_process (bool, isteğe bağlı) — Bu fonksiyonu çağıran sürecin ana süreç olup olmadığı. TPUs gibi dağıtık eğitim ortamlarında ve bu fonksiyonun tüm süreçlerden çağrılması gerektiğinde kullanışlıdır. Bu durumda, yarış durumlarını (race condition) önlemek için is_main_process=True değerini yalnızca ana süreçte ayarlayın. Varsayılan değer True'dur.
  • shared_tensors_to_discard (list[str], isteğe bağlı) — Paylaşılan tensörleri kaydetirken atılacak tensör adlarının listesi. Sağlanmaz ve paylaşılan tensörler algılanırsa, alfabetik olarak ilk gelen ad atılır.

Bir model durum sözlüğünü diske kaydetmek için parçalama ve paylaşılan tensör sorunlarını ele alır.

Ayrıca, bir PyTorch modelini doğrudan kaydetmek için save_torch_model() işlevine de bakın.

Tensor paylaşımı hakkında daha fazla bilgi için bu kılavuza göz atın.

Model durum sözlüğü, her parçanın verilen boyuttan küçük olması için parçalara ayrılır. Parçalar, verilen filename_pattern ile save_directory içinde kaydedilir. Model, tek bir parçaya sığmayacak kadar büyükse, her tensörün nerede kaydedildiğini belirtmek için bir indeks dosyası save_directory içinde kaydedilir. Bu yardımcı, arka planda split_torch_state_dict_into_shards() kullanır. safe_serialization True ise, parçalar safetensors olarak kaydedilir (varsayılan). Aksi takdirde, parçalar pickle olarak kaydedilir.

Model kaydedilmeden önce, save_directory önceki parça dosyalarından temizlenir.

Modelin bir tensörü max_shard_size değerinden büyükse, kendi parçasına yerleştirilir ve bu parçanın boyutu max_shard_size değerinden büyük olur.

Modeliniz transformers.PreTrainedModel ise, paylaşılan tensörlerin kaydedilmesini doğru şekilde işlemek için model._tied_weights_keys değerini shared_tensors_to_discard parametresi olarak geçirmelisiniz. Bu, kaydetme sırasında doğru yinelenen tensörlerin atılmasını sağlar.

Örnek:

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

serialization modülü, bir durum sözlüğünü birden fazla parçaya bölüp bu sırada uygun bir indeks oluşturmak için düşük seviyeli yardımcıları da içerir. Bu yardımcılar torch tensörleri için kullanılabilir ve diğer ML çerçevelerine kolayca genişletilebilecek şekilde tasarlanmıştır.

split_torch_state_dict_into_shards

huggingface_hub.split_torch_state_dict_into_shards

< >

( state_dict: dictfilename_pattern: str = 'model{suffix}.safetensors'max_shard_size: int | str = '5GB' ) → StateDictSplit

Parametreler

  • state_dict (dict[str, torch.Tensor]) — Kaydedilecek durum sözlüğü.
  • filename_pattern (str, isteğe bağlı) — Modelin kaydedileceği dosya adlarını oluşturmak için kullanılacak desen. Desen, filename_pattern.format(suffix=...) ile biçimlendirilebilen ve suffix anahtar kelimesini içeren bir dize olmalıdır. Varsayılan değer "model{suffix}.safetensors"'tur.
  • max_shard_size (int veya str, isteğe bağlı) — Her shard'ın bayt cinsinden maksimum boyutu. Varsayılan değer 5GB'dır.

Dönüş değeri

StateDictSplit

Parçaları ve bunları almak için indeksi içeren bir StateDictSplit nesnesi.

Bir model durum sözlüğünü, her parçanın verilen boyuttan küçük olacağı şekilde parçalara ayırın.

Parçalar, state_dict anahtarlarının sırasına göre gezilerek belirlenir. Her parçanın, geçirilen maksimum boyuta olabildiğince yakın olması için herhangi bir optimizasyon yapılmaz. Örneğin, sınır 10GB ise ve [6GB, 6GB, 2GB, 6GB, 2GB, 2GB] boyutlarında tensörler varsa, bunlar [6GB], [6+2GB], [6+2+2GB] şeklinde parçalanır; [6+2+2GB], [6+2GB], [6GB] şeklinde değil.

Bir model durum sözlüğünü diske kaydetmek için save_torch_state_dict() işlevine bakın. Bu yardımcı, arka planda split_torch_state_dict_into_shards işlevini kullanır.

Modelin bir tensörü max_shard_size değerinden büyükse, kendi parçasına yerleştirilir ve bu parçanın boyutu max_shard_size değerinden büyük olur.

Örnek:

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

Bu, her çerçeveye özgü yardımcı sınıfın türetildiği temel fabrikadır. Pratikte, bu fabrikayı doğrudan kullanmanız beklenmez; yalnızca henüz desteklenmeyen bir çerçeveye uyarlamak zorundaysanız bu şekilde davranmanız gerekir. Böyle bir durumla karşılaşırsanız, lütfen huggingface_hub deposunda yeni bir sorun açarak bize bildirin.

huggingface_hub.split_state_dict_into_shards_factory

< >

( state_dict: dictget_storage_size: Callablefilename_pattern: strget_storage_id: Callable = <function <lambda> at 0x7f9673968670>max_shard_size: int | str = '5GB' ) → StateDictSplit

Parametreler

  • state_dict (dict[str, Tensor]) — Kaydedilecek durum sözlüğü.
  • get_storage_size (Callable[[Tensor], int]) — Bir tensörün diske kaydedildiğinde bayt cinsinden boyutunu döndüren bir işlev.
  • get_storage_id (Callable[[Tensor], Optional[Any]], isteğe bağlı) — Bir tensor depolamasına benzersiz bir kimlik döndüren bir işlev. Birden fazla farklı tensor, aynı temel depolamayı paylaşabilir. Bu kimlik, bu tensorun depolaması için yaşam süresi boyunca benzersiz ve sabit olmak üzere garanti edilir. Yaşam süreleri örtüşmeyen iki tensor depolamasının aynı kimliğe sahip olması mümkündür.
  • filename_pattern (str, isteğe bağlı) — Modelin kaydedileceği dosya adlarını oluşturmak için kullanılacak desen. Desen, filename_pattern.format(suffix=...) ile biçimlendirilebilen ve suffix anahtar kelimesini içeren bir dize olmalıdır.
  • max_shard_size (int veya str, isteğe bağlı) — Her shard'ın bayt cinsinden maksimum boyutu. Varsayılan değer 5GB'dır.

Dönüş değeri

StateDictSplit

Parçaları ve bunları almak için indeksi içeren bir StateDictSplit nesnesi.

Bir model durum sözlüğünü, her parçanın verilen boyuttan küçük olacağı şekilde parçalara ayırın.

Parçalar, state_dict anahtarlarının sırasına göre gezilerek belirlenir. Her parçanın, geçirilen maksimum boyuta olabildiğince yakın olması için herhangi bir optimizasyon yapılmaz. Örneğin, sınır 10GB ise ve [6GB, 6GB, 2GB, 6GB, 2GB, 2GB] boyutlarında tensörler varsa, bunlar [6GB], [6+2GB], [6+2+2GB] şeklinde parçalanır; [6+2+2GB], [6+2GB], [6GB] şeklinde değil.

Modelin bir tensörü max_shard_size değerinden büyükse, kendi parçasına yerleştirilir ve bu parçanın boyutu max_shard_size değerinden büyük olur.

Gergiler yükleniyor

Yükleme yardımcıları, hem tek dosyalı hem de parçalı kontrol noktalarını, safetensors veya pickle biçiminde destekler. load_torch_model(), girdi olarak bir nn.Module ve bir kontrol noktası yolu (tek bir dosya veya bir dizin) alır ve ağırlıkları modele yükler.

Her iki yardımcı da varsayılan olarak safe=True değerini kullanır; bu, dosyanın adından bağımsız olarak kontrol noktasının her zaman safetensors yükleyicisiyle çözümlendiği anlamına gelir. Bir pickle kontrol noktası yüklemek, unpickle işleminin yükleme sırasında keyfi kod çalıştırması nedeniyle açıkça onay gerektirir:

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

Pickle yolu ayrıca varsayılan olarak weights_only=True değerini kullanır, yani torch’un kısıtlı unpickler’ı. Gergensör olmayan nesneler (optimizer durumları, tüm bir model, …) içeren bir checkpoint için safe=False değerinin üzerine weights_only=False değeri de eklenmelidir.

load_torch_model

huggingface_hub.load_torch_model

< >

( 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

Parametreler

  • model (torch.nn.Module) — Kontrol noktasının yükleneceği model.
  • checkpoint_path (str veya os.PathLike) — Kontrol noktası dosyasına veya kontrol noktası(lar)ını içeren dizine giden yol.
  • strict (bool, isteğe bağlı, varsayılan False) — Model durum sözlüğündeki anahtarların, kontrol noktasındaki anahtarlarla birebir eşleşmesini katı bir şekilde zorlayıp zorlamayacağı. torch.nn.Module.load_state_dict ile olduğu gibi, bu kontrol kontrol noktası yüklendikten sonra yapılır; bu nedenle hata yükseltildiğinde model kısmen güncellenmiş olabilir.
  • safe (bool, isteğe bağlı, varsayılan True) — safe True ise, safetensors dosyaları yüklenecektir. safe False ise, işlev önce mevcutlarsa safetensors dosyalarını yüklemeye çalışacak, aksi takdirde pickle dosyalarını yüklemeye dönecektir. Safetensors dosyalarını açıklamayan bir filename_pattern, safe=True olduğunda reddedilir.
  • weights_only (bool, isteğe bağlı, varsayılan True) — True ise, yalnızca model ağırlıklarını yükler; optimizör durumları ve diğer meta verileri içermez, bunun için torch’un kısıtlı unpickler’ını kullanır. Pickle checkpoint’inde keyfi Python nesnelerine izin vermek için False olarak ayarlayın (bu, yükleme sırasında keyfi kod çalıştırır). Kısıtlı unpickler içermeyen ve her zaman kısıtlama olmadan unpickle yapan PyTorch < 1.13 üzerinde hiçbir etkisi yoktur.
  • map_location (str veya torch.device, isteğe bağlı) — Depolama konumlarının nasıl yeniden eşleneceğini belirten bir torch.device nesnesi, dize veya sözlük. Tüm tensörlerin yükleneceği konumu belirtir.
  • mmap (bool, isteğe bağlı, varsayılan False) — Hafıza eşlemeli dosya yükleme kullanılıp kullanılmayacağı. PyTorch >= 2.1.0 sürümlerinde zipfile tabanlı checkpoint'ler için büyük modellerde yükleme performansını artırabilir.
  • filename_pattern (str, isteğe bağlı) — Dizin dosyası için aranacak desen. Desen, filename_pattern.format(suffix=...) ile biçimlendirilebilen ve suffix anahtar kelimesini içeren bir dize olmalıdır. Varsayılan değer "model{suffix}.safetensors"'tur.

Dönüş değeri

NamedTuple

missing_keys ve unexpected_keys alanlarına sahip adlandırılmış bir demet.

  • missing_keys, checkpoint'te olmayan ancak modelde bulunan anahtarları içeren bir str listesidir.
  • unexpected_keys, checkpoint'te varken modelde olmayan anahtarları, yani beklenmeyen anahtarları içeren bir str listesidir.

Yükseltilen

FileNotFoundError veya ImportError veya ValueError

  • FileNotFoundError — Kontrol noktası dosyası veya dizini mevcut değilse.
  • ImportError — Sırasıyla bir .safetensors dosyası veya PyTorch checkpoint'i yüklenmeye çalışılırken safetensors veya torch kurulu değilse.
  • ValueError — Kontrol noktası biçimi belirlenemezse.

Bir kontrol noktasını modele yükleyin; hem parçalı hem de parçasız kontrol noktalarını işleyin.

Örnek:

>>> from huggingface_hub import load_torch_model
>>> model = ... # A PyTorch model
>>> load_torch_model(model, "path/to/checkpoint")

load_state_dict_from_file

huggingface_hub.load_state_dict_from_file

< >

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

Parametreler

  • checkpoint_file (str veya os.PathLike) — Yüklenmesi istenen checkpoint dosyasının yolu. Safetensors veya pickle (.bin) checkpoint olabilir.
  • map_location (str veya torch.device, isteğe bağlı) — Depolama konumlarının nasıl yeniden eşleneceğini belirten bir torch.device nesnesi, dize veya sözlük. Tüm tensörlerin yükleneceği konumu belirtir.
  • weights_only (bool, isteğe bağlı, varsayılan True) — True ise, yalnızca model ağırlıklarını yükler; optimizör durumları ve diğer meta verileri içermez, bunun için torch’un kısıtlı unpickler’ını kullanır. Pickle checkpoint’inde keyfi Python nesnelerine izin vermek için False olarak ayarlayın (bu, yükleme sırasında keyfi kodun çalıştırılmasına neden olur). Safetensors dosyaları yüklenirken hiçbir etkisi yoktur; ayrıca kısıtlı unpickler içermeyen PyTorch < 1.13 sürümlerinde de etkisizdir — bu sürümler her zaman kısıtlama olmadan unpickle eder ve bir uyarı günlüğe kaydedilir.
  • mmap (bool, isteğe bağlı, varsayılan False) — Hafıza eşlemeli dosya yükleme kullanılıp kullanılmayacağı. PyTorch >= 2.1.0 sürümlerinde zipfile tabanlı checkpoint'ler için büyük modellerde yükleme performansını artırabilir. safetensors kütüphanesi varsayılan olarak hafıza eşlemesi kullandığı için safetensors dosyalarının yüklenmesinde herhangi bir etkisi yoktur.
  • safe (bool, isteğe bağlı, varsayılan True) — True ise, kontrol noktası adı ne olursa olsun her zaman safetensors olarak yüklenir. Diğer herhangi bir biçim (ör. bir pickle .bin dosyası) deseri hale getirilmek yerine bir ValueError yükseltir: pickle kontrol noktaları, yüklenme sırasında keyfi kod çalıştırabilir. False ise, dosya adı öyle belirtiyorsa safetensors olarak, aksi halde torch.load ile yüklenir.

Dönüş değeri

Union[dict[str, "torch.Tensor"], Any]

Yüklenen kontrol noktası.

  • safetensors dosyaları için: her zaman parametre adlarını tensörlere eşleyen bir sözlük döndürür.
  • Pickle dosyaları için: pickl'lenmiş herhangi bir Python nesnesini döndürür (genellikle bir state dict, ancak tüm bir model, optimizer durumu veya herhangi bir başka Python nesnesi de olabilir).

Yükseltilen

FileNotFoundError veya ImportError veya OSError veya ValueError

  • FileNotFoundError — Kontrol noktası dosyası mevcut değilse.
  • ImportError — Sırasıyla bir .safetensors dosyası veya PyTorch checkpoint'i yüklenmeye çalışılırken safetensors veya torch kurulu değilse.
  • OSError — Kontrol noktası dosya biçimi geçersizse veya git-lfs dosyaları düzgün indirilmediyse.
  • ValueError — Kontrol noktası dosya yolu boş veya geçersizse veya safe=True iken safetensors olarak seri dışı bırakılamıyorsa (safe=False geçirerek pickle kontrol noktalarına izin verin).

Safetensors ve pickle kontrol noktası biçimlerini işleyerek bir kontrol noktası dosyası yükler.

Örnek:

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

Tensör yardımcıları

get_torch_storage_id

huggingface_hub.get_torch_storage_id

< >

( tensor: torch.Tensor )

Bir tensör depolamasına benzersiz tanımlayıcı döndürür.

Birden fazla farklı tensör aynı altta yatan depolamayı paylaşabilir. Bu tanımlayıcı, tensörün depolaması için yaşam süresi boyunca benzersiz ve sabit olmaya garanti edilir. Yaşam süreleri örtüşmeyen iki tensör depolamasının aynı kimliğe sahip olması mümkündür. Meta tensörler durumunda, aynı depolamayı paylaşıp paylaşmadıklarını belirleyemediğimiz için None döndürülür.

https://github.com/huggingface/transformers/blob/1ecf5f7c982d761b4daaa96719d162c324187c64/src/transformers/pytorch_utils.py#L278 adresinden alınmıştır.

get_torch_storage_size

huggingface_hub.get_torch_storage_size

< >

( tensor: torch.Tensor )

https://github.com/huggingface/safetensors/blob/08db34094e9e59e2f9218f2df133b7b4aaff5a99/bindings/python/py_src/safetensors/torch.py#L31C1-L41C59 adresinden alınmıştır

Update on GitHub

←Webhooks sunucusu Katı dataclass'lar→