Hub Python Library documentation
Sérialisation
Sérialisation
huggingface_hub fournit des utilitaires pour enregistrer et charger les poids des modèles ML de manière standardisée. Cette partie de la bibliothèque est encore en cours de développement et sera améliorée dans les prochaines versions. L’objectif est d’harmoniser la façon dont les poids sont enregistrés et chargés sur le Hub, afin d’éliminer la duplication de code entre les bibliothèques et d’établir des conventions cohérentes.
Format de fichier DDUF
DDUF est un format de fichier conçu pour les modèles de diffusion. Il permet d'enregistrer toutes les informations nécessaires à l'exécution d'un modèle dans un seul fichier. Ce travail s'inspire du format GGUF. huggingface_hub fournit des utilitaires pour enregistrer et charger les fichiers DDUF, garantissant le respect du format de fichier.
Il s'agit d'une version très préliminaire de l'analyseur. L'API et l'implémentation peuvent évoluer à court terme.
L’analyseur effectue actuellement très peu de validation. Pour plus de détails sur le format de fichier, consultez https://github.com/huggingface/huggingface.js/tree/main/packages/dduf.
Comment écrire un fichier DDUF ?
Voici comment exporter un dossier contenant différentes parties d'un modèle de diffusion à l'aide de 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")Pour plus de flexibilité, vous pouvez utiliser export_entries_as_dduf() et passer une liste de fichiers à inclure dans le fichier DDUF final :
# 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
... ]
... )Le paramètre entries prend également en charge le passage d'un itérable de chemins ou d'octets. Cela peut s'avérer utile si vous avez un modèle chargé et souhaitez le sérialiser directement dans un fichier DDUF, plutôt que de devoir d'abord sérialiser chaque composant sur le disque puis de le convertir en fichier DDUF. Voici un exemple de la manière dont un StableDiffusionPipeline peut être sérialisé au format 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))Remarque : en pratique, diffusers fournit une méthode pour sérialiser directement un pipeline dans un fichier DDUF. L'extrait ci-dessus n'est fourni qu'à titre d'exemple.
Comment lire un fichier 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)Aides
huggingface_hub.export_entries_as_dduf
< source >( dduf_path: str | os.PathLikeentries: Iterable )
Paramètres
- dduf_path (
strouos.PathLike) — Le chemin du fichier DDUF à écrire. - entries (
Iterable[tuple[str, Union[str, Path, bytes]]]) — Un itérable d’entrées à écrire dans le fichier DDUF. Chaque entrée est un tuple contenant le nom du fichier et son contenu. Le nom du fichier doit être le chemin du fichier dans l’archive DDUF. Le contenu peut être une chaîne de caractères ou un pathlib.Path représentant un chemin vers un fichier sur le disque local, ou directement le contenu sous forme d’octets.
Lève
-
- —
DDUFExportError: si un problème survient pendant l’exportation (par exemple, nom d’entrée invalide, absence de ‘model_index.json’, etc.).
- —
Écrire un fichier DDUF à partir d'un itérable d'entrées.
Il s’agit d’un utilitaire de bas niveau par rapport à export_folder_as_dduf(), offrant une plus grande flexibilité lors de la sérialisation des données. En particulier, vous n’avez pas besoin d’enregistrer les données sur le disque avant de les exporter dans le fichier DDUF.
Exemple :
# 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 )
Exporter un dossier en tant que fichier DDUF.
AUtilise export_entries_as_dduf() en interne.
huggingface_hub.read_dduf_file
< source >( dduf_path: os.PathLike | str ) → dict[str, DDUFEntry]
Paramètres
Retourne
dict[str, DDUFEntry]
Un dictionnaire de DDUFEntry indexé par nom de fichier.
Lève
-
- —
DDUFCorruptedFileError: si le fichier DDUF est corrompu (c’est-à-dire s’il ne respecte pas le format DDUF).
- —
Lis un fichier DDUF et renvoie un dictionnaire d'entrées.
Seules les métadonnées sont lues, les données ne sont pas chargées en mémoire.
Exemple :
>>> 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)classe huggingface_hub.DDUFEntry
< source >( filename: strlength: intoffset: intdduf_path: Path )
Objet représentant une entrée de fichier dans un fichier DDUF.
Voir read_dduf_file() pour savoir comment lire un fichier DDUF.
Ouvrez le fichier en tant que fichier mappé en mémoire.
Utile pour charger les safetensors directement depuis le fichier.
Lisez le fichier en tant que texte.
Utile pour les entrées « .txt » et « .json ».
Erreurs
Exception de base pour les erreurs liées au format DDUF.
Exception levée lorsque le fichier DDUF est corrompu.
Exception de base pour les erreurs survenant lors de l'exportation DDUF.
Exception levée lorsque le nom de l'entrée est invalide.
Enregistrer des tenseurs
Le principal utilitaire du module serialization prend en entrée un nn.Module de torch et l'enregistre sur le disque. Il gère la logique d'enregistrement des tenseurs partagés (voir explication de safetensors) ainsi que la logique de division du dictionnaire d'état en fragments, en utilisant split_torch_state_dict_into_shards() en interne. Pour le moment, seul le framework torch est pris en charge.
Si vous souhaitez enregistrer un dictionnaire d'état (par exemple, une correspondance entre les noms de couches et les tenseurs associés) plutôt qu'un nn.Module, vous pouvez utiliser save_torch_state_dict() qui offre les mêmes fonctionnalités. Cela est utile, par exemple, si vous voulez appliquer une logique personnalisée au dictionnaire d'état avant de l'enregistrer.
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 )
Paramètres
- model (
torch.nn.Module) — Le modèle à enregistrer sur le disque. - save_directory (
strouPath) — Le répertoire dans lequel le modèle sera enregistré. - filename_pattern (
str, facultatif) — Le motif à utiliser pour générer les noms des fichiers dans lesquels le modèle sera enregistré. Le motif doit être une chaîne de caractères qui peut être formatée avecfilename_pattern.format(suffix=...)et doit contenir le mot-clésuffixPar défaut,"model{suffix}.safetensors"oupytorch_model{suffix}.binselon le paramètresafe_serialization. - force_contiguous (
boolean, facultatif) — Force la sauvegarde du state_dict sous forme de tenseurs contigus. Cela n'a aucun effet sur la justesse du modèle, mais cela pourrait potentiellement modifier les performances si la disposition du tenseur avait été choisie spécifiquement pour cette raison. La valeur par défaut estTrue. - max_shard_size (
intoustr, facultatif) — La taille maximale de chaque shard, en octets. La valeur par défaut est de 5 Go. - metadata (
dict[str, str], facultatif) — Informations supplémentaires à enregistrer avec le modèle. Certaines métadonnées seront ajoutées pour chaque tenseur supprimé. Ces informations ne suffiront pas à récupérer l’ensemble de la structure partagée, mais peuvent aider à comprendre les éléments en jeu. - safe_serialization (
bool, facultatif) — Indique s'il faut enregistrer au format safetensors, ce qui est le comportement par défaut. Si la valeur estFalse, les fragments sont enregistrés au format pickle. La sérialisation sécurisée est recommandée pour des raisons de sécurité. L'enregistrement au format pickle est obsolète et sera supprimé dans une version future. - is_main_process (
bool, facultatif) — Indique si le processus qui appelle cette fonction est le processus principal ou non. Utile lors d’une formation distribuée, par exemple sur des TPU, où il est nécessaire d’appeler cette fonction depuis tous les processus. Dans ce cas, définissezis_main_process=Trueuniquement sur le processus principal afin d’éviter les conditions de course. La valeur par défaut est True. - shared_tensors_to_discard (
list[str], facultatif) — Liste des noms de tenseurs à supprimer lors de l’enregistrement des tenseurs partagés. Si non fourni et que des tenseurs partagés sont détectés, le premier nom en ordre alphabétique sera supprimé.
Enregistre un modèle torch donné sur le disque, en gérant les problèmes de fragmentation et de tenseurs partagés.
Voir aussi save_torch_state_dict() pour enregistrer un state dict avec plus de flexibilité.
Pour plus d'informations sur le partage de tenseurs, consultez ce guide.
Le dictionnaire d'état du modèle est découpé en fragments afin que chaque fragment soit inférieur à une taille donnée. Les fragments sont
enregistrés dans le save_directory avec le filename_pattern indiqué. Si le modèle est trop volumineux pour tenir dans un seul fragment,
un fichier d'index est enregistré dans le save_directory pour indiquer où chaque tenseur est enregistré. Cet utilitaire utilise split_torch_state_dict_into_shards() en interne. Si safe_serialization est True, les fragments sont enregistrés au
format safetensors (par défaut). Sinon, les fragments sont enregistrés au format pickle.
Avant d'enregistrer le modèle, le save_directory est nettoyé de tout fichier de shard précédent.
Si l'un des tenseurs du modèle est plus grand que
max_shard_size, il finira dans son propre shard dont la taille sera supérieure àmax_shard_size.
Si votre modèle est un
transformers.PreTrainedModel, vous devez passermodel._tied_weights_keysen tant queshared_tensors_to_discardpour gérer correctement l'enregistrement des tenseurs partagés. Cela garantit que les tenseurs en double appropriés sont écartés lors de l'enregistrement.
Exemple :
>>> 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 )
Paramètres
- state_dict (
dict[str, torch.Tensor]) — Le dictionnaire d'état à enregistrer. - save_directory (
strouPath) — Le répertoire dans lequel le modèle sera enregistré. - filename_pattern (
str, facultatif) — Le motif à utiliser pour générer les noms des fichiers dans lesquels le modèle sera enregistré. Le motif doit être une chaîne de caractères qui peut être formatée avecfilename_pattern.format(suffix=...)et doit contenir le mot-clésuffixPar défaut,"model{suffix}.safetensors"oupytorch_model{suffix}.binselon le paramètresafe_serialization. - force_contiguous (
boolean, facultatif) — Force la sauvegarde du state_dict sous forme de tenseurs contigus. Cela n'a aucun effet sur la justesse du modèle, mais cela pourrait potentiellement modifier les performances si la disposition du tenseur avait été choisie spécifiquement pour cette raison. La valeur par défaut estTrue. - max_shard_size (
intoustr, facultatif) — La taille maximale de chaque shard, en octets. La valeur par défaut est de 5 Go. - metadata (
dict[str, str], facultatif) — Informations supplémentaires à enregistrer avec le modèle. Certaines métadonnées seront ajoutées pour chaque tenseur supprimé. Ces informations ne suffiront pas à récupérer l’ensemble de la structure partagée, mais peuvent aider à comprendre les éléments en jeu. - safe_serialization (
bool, facultatif) — Indique s'il faut enregistrer au format safetensors, ce qui est le comportement par défaut. Si la valeur estFalse, les fragments sont enregistrés au format pickle. La sérialisation sécurisée est recommandée pour des raisons de sécurité. L'enregistrement au format pickle est obsolète et sera supprimé dans une version future. - is_main_process (
bool, facultatif) — Indique si le processus qui appelle cette fonction est le processus principal ou non. Utile lors d’une formation distribuée, par exemple sur des TPU, où il est nécessaire d’appeler cette fonction depuis tous les processus. Dans ce cas, définissezis_main_process=Trueuniquement sur le processus principal afin d’éviter les conditions de course. La valeur par défaut est True. - shared_tensors_to_discard (
list[str], facultatif) — Liste des noms de tenseurs à supprimer lors de l’enregistrement des tenseurs partagés. Si non fourni et que des tenseurs partagés sont détectés, le premier nom en ordre alphabétique sera supprimé.
Enregistrer un dictionnaire d'état de modèle sur le disque, en gérant les problèmes de fragmentation et de tenseurs partagés.
Voir aussi save_torch_model() pour enregistrer directement un modèle PyTorch.
Pour plus d'informations sur le partage de tenseurs, consultez ce guide.
Le dictionnaire d'état du modèle est découpé en fragments afin que chaque fragment soit inférieur à une taille donnée. Les fragments sont
enregistrés dans le save_directory avec le filename_pattern indiqué. Si le modèle est trop volumineux pour tenir dans un seul fragment,
un fichier d'index est enregistré dans le save_directory pour indiquer où chaque tenseur est enregistré. Cet utilitaire utilise split_torch_state_dict_into_shards() en interne. Si safe_serialization est True, les fragments sont enregistrés au
format safetensors (par défaut). Sinon, les fragments sont enregistrés au format pickle.
Avant d'enregistrer le modèle, le save_directory est nettoyé de tout fichier de shard précédent.
Si l'un des tenseurs du modèle est plus grand que
max_shard_size, il finira dans son propre shard dont la taille sera supérieure àmax_shard_size.
Si votre modèle est un
transformers.PreTrainedModel, vous devez passermodel._tied_weights_keysen tant queshared_tensors_to_discardpour gérer correctement l'enregistrement des tenseurs partagés. Cela garantit que les tenseurs en double appropriés sont écartés lors de l'enregistrement.
Exemple :
>>> 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")Le module serialization contient également des utilitaires de bas niveau pour diviser un dictionnaire d'état en plusieurs fragments, tout en créant un index approprié au passage. Ces utilitaires sont disponibles pour les tenseurs torch et sont conçus pour être facilement étendus à tout autre framework de ML.
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
Paramètres
- state_dict (
dict[str, torch.Tensor]) — Le dictionnaire d'état à enregistrer. - filename_pattern (
str, facultatif) — Le motif à utiliser pour générer les noms des fichiers dans lesquels le modèle sera enregistré. Le motif doit être une chaîne de caractères qui peut être formatée avecfilename_pattern.format(suffix=...)et doit contenir le mot-clésuffixLa valeur par défaut est"model{suffix}.safetensors". - max_shard_size (
intoustr, facultatif) — La taille maximale de chaque shard, en octets. La valeur par défaut est de 5 Go.
Retourne
StateDictSplit
Un objet StateDictSplit contenant les shards et l'index pour les récupérer.
Diviser le dictionnaire d'état d'un modèle en fragments afin que chaque fragment soit inférieur à une taille donnée.
Les shards sont déterminés en parcourant le state_dict dans l'ordre de ses clés. Aucune optimisation n'est effectuée pour que chaque shard soit aussi proche que possible de la taille maximale passée. Par exemple, si la limite est de 10 Go et que nous avons des tenseurs de tailles [6 Go, 6 Go, 2 Go, 6 Go, 2 Go, 2 Go], ils seront shardés en [6 Go], [6+2 Go], [6+2+2 Go] et non en [6+2+2 Go], [6+2 Go], [6 Go].
Pour enregistrer un dictionnaire d'état de modèle sur le disque, consultez save_torch_state_dict(). Cet utilitaire utilise
split_torch_state_dict_into_shardsen interne.
Si l'un des tenseurs du modèle est plus grand que
max_shard_size, il finira dans son propre shard dont la taille sera supérieure àmax_shard_size.
Exemple :
>>> 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
C'est la fabrique sous-jacente à partir de laquelle chaque assistant spécifique à un framework est dérivé. En pratique, vous n'êtes pas censé utiliser directement cette fabrique, sauf si vous devez l'adapter à un framework non encore pris en charge. Si c'est le cas, merci de nous en informer en ouvrant un nouveau problème sur le dépôt 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
Paramètres
- state_dict (
dict[str, Tensor]) — Le dictionnaire d'état à enregistrer. - get_storage_size (
Callable[[Tensor], int]) — Une fonction qui renvoie la taille d'un tenseur lorsqu'il est enregistré sur disque, en octets. - get_storage_id (
Callable[[Tensor], Optional[Any]], facultatif) — Une fonction qui renvoie un identifiant unique pour le stockage d’un tenseur. Plusieurs tenseurs différents peuvent partager le même stockage sous-jacent. Cet identifiant est garanti unique et constant pour le stockage de ce tenseur pendant sa durée de vie. Deux stockages de tenseurs dont les durées de vie ne se chevauchent pas peuvent avoir le même identifiant. - filename_pattern (
str, facultatif) — Le modèle à utiliser pour générer les noms des fichiers dans lesquels le modèle sera enregistré. Le modèle doit être une chaîne de caractères qui peut être formatée avecfilename_pattern.format(suffix=...)et doit contenir le mot-clésuffix - max_shard_size (
intoustr, facultatif) — La taille maximale de chaque shard, en octets. La valeur par défaut est de 5 Go.
Retourne
StateDictSplit
Un objet StateDictSplit contenant les shards et l'index pour les récupérer.
Diviser le dictionnaire d'état d'un modèle en fragments afin que chaque fragment soit inférieur à une taille donnée.
Les shards sont déterminés en parcourant le state_dict dans l'ordre de ses clés. Aucune optimisation n'est effectuée pour que chaque shard soit aussi proche que possible de la taille maximale passée. Par exemple, si la limite est de 10 Go et que nous avons des tenseurs de tailles [6 Go, 6 Go, 2 Go, 6 Go, 2 Go, 2 Go], ils seront shardés en [6 Go], [6+2 Go], [6+2+2 Go] et non en [6+2+2 Go], [6+2 Go], [6 Go].
Si l'un des tenseurs du modèle est plus grand que
max_shard_size, il finira dans son propre shard dont la taille sera supérieure àmax_shard_size.
Chargement des tenseurs
Les utilitaires de chargement prennent en charge les points de contrôle monofichier et fragmentés, au format safetensors ou pickle. load_torch_model() prend en entrée un nn.Module et un chemin de point de contrôle (fichier unique ou répertoire) et charge les poids dans le modèle.
Les deux utilitaires utilisent par défaut
safe=True, ce qui signifie que le point de contrôle est toujours désérialisé avec le chargeur safetensors — quel que soit le nom du fichier. Le chargement d'un point de contrôle pickle nécessite une opt-in explicite, car le dépickling exécute du code arbitraire au moment du chargement :>>> 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)Le chemin pickle utilise par défaut
weights_only=True, c’est-à-dire le dépickleur restreint de torch. Un point de contrôle contenant des objets non tenseurs (états de l’optimiseur, un modèle entier, …) nécessiteweights_only=Falseen plus desafe=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
Paramètres
- model (
torch.nn.Module) — Le modèle dans lequel charger le point de contrôle. - checkpoint_path (
strouos.PathLike) — Chemin vers le fichier de point de contrôle ou le répertoire contenant les points de contrôle. - strict (
bool, facultatif, par défautFalse) — Indique s'il faut imposer strictement que les clés du dictionnaire d'état du modèle correspondent aux clés du point de contrôle. Comme pourtorch.nn.Module.load_state_dict, la vérification a lieu une fois le point de contrôle chargé, de sorte que le modèle peut avoir été partiellement mis à jour lorsque l'erreur est levée. - safe (
bool, facultatif, par défautTrue) — Sisafeest True, les fichiers safetensors seront chargés. Sisafeest False, la fonction tentera d’abord de charger les fichiers safetensors s’ils sont disponibles, sinon elle basculera sur le chargement des fichiers pickle. Unfilename_patternqui ne décrit pas des fichiers safetensors est rejeté lorsquesafe=True. - weights_only (
bool, facultatif, valeur par défautTrue) — Si True, ne charge que les poids du modèle, sans les états de l’optimiseur ni les autres métadonnées, en utilisant le dépickleur restreint de torch. Définissez False pour autoriser des objets Python arbitraires dans un point de contrôle pickle (ce qui exécute du code arbitraire au moment du chargement). N’a aucun effet sur PyTorch < 1.13, qui ne dispose pas de dépickleur restreint et effectue toujours le dépickling sans restriction. - map_location (
stroutorch.device, facultatif) — Un objettorch.device, une chaîne de caractères ou un dictionnaire spécifiant comment remapper les emplacements de stockage. Il indique l’emplacement où tous les tenseurs doivent être chargés. - mmap (
bool, facultatif, valeur par défautFalse) — Indique s'il faut utiliser le chargement de fichiers par mappage mémoire. Le mappage mémoire peut améliorer les performances de chargement pour les grands modèles dans PyTorch >= 2.1.0 avec des points de contrôle basés sur zipfile. - filename_pattern (
str, facultatif) — Le motif à rechercher pour le fichier d’index. Le motif doit être une chaîne de caractères qui peut être formatée avecfilename_pattern.format(suffix=...)et doit contenir le mot-clésuffixValeur par défaut :"model{suffix}.safetensors".
Retourne
NamedTuple
Un tuple nommé avec les champs missing_keys et unexpected_keys.
missing_keysest une liste de str contenant les clés manquantes, c’est-à-dire les clés présentes dans le modèle mais absentes du checkpoint.unexpected_keysest une liste de str contenant les clés inattendues, c’est-à-dire les clés présentes dans le checkpoint mais absentes du modèle.
Lève
FileNotFoundError ou ImportError ou ValueError
FileNotFoundError— Si le fichier ou le répertoire de point de contrôle n'existe pas.ImportError— Si safetensors ou torch n'est pas installé lors de la tentative de chargement d'un fichier .safetensors ou d'un checkpoint PyTorch, respectivement.ValueError— Si le format du point de contrôle ne peut pas être déterminé.
Charger un point de contrôle dans un modèle, en gérant à la fois les points de contrôle fragmentés et non fragmentés.
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]
Paramètres
- checkpoint_file (
strouos.PathLike) — Chemin du fichier de point de contrôle à charger. Peut être un point de contrôle safetensors ou pickle (.bin). - map_location (
stroutorch.device, facultatif) — Un objettorch.device, une chaîne de caractères ou un dictionnaire spécifiant comment remapper les emplacements de stockage. Il indique l’emplacement où tous les tenseurs doivent être chargés. - weights_only (
bool, facultatif, valeur par défautTrue) — Si True, ne charge que les poids du modèle, sans les états de l’optimiseur ni les autres métadonnées, en utilisant le dépickleur restreint de torch. Définissez False pour autoriser des objets Python arbitraires dans un point de contrôle pickle (ce qui exécute du code arbitraire au moment du chargement). N’a aucun effet lors du chargement de fichiers safetensors, ni sur PyTorch < 1.13 qui ne dispose pas de dépickleur restreint — ces versions dépicklent toujours sans restriction et un avertissement est journalisé. - mmap (
bool, facultatif, valeur par défautFalse) — Indique s'il faut utiliser le chargement de fichiers par mappage mémoire. Le mappage mémoire peut améliorer les performances de chargement pour les grands modèles dans PyTorch >= 2.1.0 avec des points de contrôle basés sur zipfile. N'a aucun effet lors du chargement de fichiers safetensors, car la bibliothèquesafetensorsutilise le mappage mémoire par défaut. - safe (
bool, facultatif, par défautTrue) — Si True, le point de contrôle est toujours chargé au format safetensors, quel que soit son nom. Tout autre format (par exemple un fichier pickle.bin) provoque uneValueErrorau lieu d’être désérialisé : les points de contrôle pickle peuvent exécuter du code arbitraire au moment du chargement. Si False, le fichier est chargé au format safetensors si son nom l’indique, et avectorch.loaddans le cas contraire.
Retourne
Union[dict[str, "torch.Tensor"], Any]
Le point de contrôle chargé.
- Pour les fichiers safetensors : renvoie toujours un dictionnaire associant les noms de paramètres aux tenseurs.
- Pour les fichiers pickle : renvoie n'importe quel objet Python qui a été picklé (généralement un state dict, mais cela peut être un modèle entier, l'état d'un optimiseur, ou tout autre objet Python).
Lève
FileNotFoundError ou ImportError ou OSError ou ValueError
FileNotFoundError— Si le fichier de point de contrôle n'existe pas.ImportError— Si safetensors ou torch n'est pas installé lors de la tentative de chargement d'un fichier .safetensors ou d'un checkpoint PyTorch, respectivement.OSError— Si le format du fichier de point de contrôle est invalide ou si les fichiers git-lfs ne sont pas téléchargés correctement.ValueError— Si le chemin du fichier de point de contrôle est vide ou invalide, ou s'il ne peut pas être désérialisé en tant que safetensors lorsquesafe=True(passezsafe=Falsepour autoriser les points de contrôle pickle).
Charge un fichier de point de contrôle, en gérant à la fois les formats de point de contrôle safetensors et pickle.
Exemple :
>>> 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)Aides pour les tenseurs
get_torch_storage_id
Retourne un identifiant unique pour un stockage de tenseur.
Plusieurs tenseurs différents peuvent partager le même stockage sous-jacent. Cet identifiant est garanti unique et constant pour le stockage de ce tenseur pendant toute sa durée de vie. Deux stockages de tenseurs dont les durées de vie ne se chevauchent pas peuvent avoir le même id. Dans le cas des tenseurs meta, nous renvoyons None car nous ne pouvons pas déterminer s’ils partagent le même stockage.