Mixins & métodos de serialização

Mixins

A biblioteca huggingface_hub oferece uma variedade de mixins que podem ser usados como classe pai para seus objetos, a fim de fornecer funções simples de upload e download. Consulte nosso guia de integração para aprender como integrar qualquer framework de ML com o Hub.

Genérico

classe huggingface_hub.ModelHubMixin

< source >

( *args**kwargs )

Parâmetros

repo_url (str, opcional) — URL do repositório da biblioteca. Usado para gerar o cartão do modelo.
paper_url (str, opcional) — URL do paper da biblioteca. Usado para gerar o model card.
docs_url (str, opcional) — URL da documentação da biblioteca. Usado para gerar o cartão do modelo.
model_card_template (str, opcional) — Modelo do cartão do modelo. Usado para gerar o cartão do modelo. O padrão é um modelo genérico.
language (str ou list[str], opcional) — Idioma suportado pela biblioteca. Usado para gerar o cartão do modelo.
library_name (str, opcional) — Nome da biblioteca que integra o ModelHubMixin. Usado para gerar o model card.
license (str, opcional) — Licença da biblioteca que integra o ModelHubMixin. Usada para gerar o cartão do modelo. Ex.: “apache-2.0”
license_name (str, opcional) — Nome da biblioteca que integra o ModelHubMixin. Usado para gerar o model card. Usado apenas se license estiver definido como other. Ex.: “coqui-public-model-license”.
license_link (str, opcional) — URL para a licença da biblioteca que integra o ModelHubMixin. Usado para gerar o model card. Usado apenas se license estiver definido como other e license_name estiver definido. Ex.: ”https://coqui.ai/cpml”.
pipeline_tag (str, opcional) — Tag do pipeline. Usada para gerar o model card. Ex.: “text-classification”.
tags (list[str], opcional) — Tags a serem adicionadas ao model card. Usado para gerar o model card. Ex.: [“computer-vision”]
coders (dict[Type, tuple[Callable, Callable]], opcional) — Dicionário de tipos personalizados e seus codificadores/decodificadores. Usado para codificar/decodificar argumentos que não são jsonable por padrão. Por exemplo, dataclasses, argparse.Namespace, OmegaConf, etc.

Um mixin genérico para integrar QUALQUER framework de aprendizado de máquina com o Hub.

Para integrar seu framework, sua classe de modelo deve herdar desta classe. A lógica personalizada para salvar/carregar modelos deve ser sobrescrita em _from_pretrained e _save_pretrained. PyTorchModelHubMixin é um bom exemplo de integração de mixin com o Hub. Consulte nosso guia de integração para mais instruções.

Ao herdar de ModelHubMixin, você pode definir atributos de nível de classe. Esses atributos não são passados para __init__, mas para a própria definição da classe. Isso é útil para definir metadados sobre a biblioteca que integra ModelHubMixin.

Para mais detalhes sobre como integrar o mixin com sua biblioteca, consulte o guia de integração.

Exemplo:

>>> from huggingface_hub import ModelHubMixin

# Inherit from ModelHubMixin
>>> class MyCustomModel(
...         ModelHubMixin,
...         library_name="my-library",
...         tags=["computer-vision"],
...         repo_url="https://github.com/huggingface/my-cool-library",
...         paper_url="https://arxiv.org/abs/2304.12244",
...         docs_url="https://huggingface.co/docs/my-cool-library",
...         # ^ optional metadata to generate model card
...     ):
...     def __init__(self, size: int = 512, device: str = "cpu"):
...         # define how to initialize your model
...         super().__init__()
...         ...
...
...     def _save_pretrained(self, save_directory: Path) -> None:
...         # define how to serialize your model
...         ...
...
...     @classmethod
...     def from_pretrained(
...         cls: type[T],
...         pretrained_model_name_or_path: Union[str, Path],
...         *,
...         force_download: bool = False,
...         token: Optional[Union[str, bool]] = None,
...         cache_dir: Optional[Union[str, Path]] = None,
...         local_files_only: bool = False,
...         revision: Optional[str] = None,
...         **model_kwargs,
...     ) -> T:
...         # define how to deserialize your model
...         ...

>>> model = MyCustomModel(size=256, device="gpu")

# Save model weights to local directory
>>> model.save_pretrained("my-awesome-model")

# Push model weights to the Hub
>>> model.push_to_hub("my-awesome-model")

# Download and initialize weights from the Hub
>>> reloaded_model = MyCustomModel.from_pretrained("username/my-awesome-model")
>>> reloaded_model.size
256

# Model card has been correctly populated
>>> from huggingface_hub import ModelCard
>>> card = ModelCard.load("username/my-awesome-model")
>>> card.data.tags
["x-custom-tag", "pytorch_model_hub_mixin", "model_hub_mixin"]
>>> card.data.library_name
"my-library"

_save_pretrained

< source >

( save_directory: Path )

Parâmetros

save_directory (str ou Path) — Caminho para o diretório em que os pesos do modelo e a configuração serão salvos.

Sobrescreva este método na subclasse para definir como salvar seu modelo. Consulte nosso guia de integração para obter instruções.

_from_pretrained

< source >

Parâmetros

model_id (str) — ID do modelo a ser carregado do Huggingface Hub (ex.: bigscience/bloom).
revision (str, opcional) — Revisão do modelo no Hub. Pode ser o nome de um branch, uma tag git ou qualquer id de commit. O padrão é o commit mais recente no branch main.
force_download (bool, opcional, padrão False) — Se deve forçar o (re-)download dos pesos do modelo e dos arquivos de configuração do Hub, sobrescrevendo o cache existente.
token (str ou bool, opcional) — O token a ser usado como autorização de bearer HTTP para arquivos remotos. Por padrão, será usado o token em cache obtido ao executar hf auth login.
cache_dir (str, Path, opcional) — Caminho para a pasta onde os arquivos em cache são armazenados.
local_files_only (bool, opcional, padrão False) — Se True, evita o download do arquivo e retorna o caminho do arquivo em cache local, se ele existir.
model_kwargs — Argumentos de palavra-chave adicionais passados ao método _from_pretrained().

Sobrescreva este método em uma subclasse para definir como carregar seu modelo a partir de um pré-treinado.

Use hf_hub_download() ou snapshot_download() para baixar arquivos do Hub antes de carregá-los. A maioria dos argumentos de entrada pode ser passada diretamente para esses 2 métodos. Se necessário, você pode adicionar mais argumentos a este método usando “model_kwargs”. Por exemplo, PyTorchModelHubMixin._from_pretrained() recebe como entrada um parâmetro map_location para definir em qual dispositivo o modelo deve ser carregado.

Confira nosso guia de integração para mais instruções.

from_pretrained

< source >

Parâmetros

pretrained_model_name_or_path (str, Path) —
- Ou o model_id (string) de um modelo hospedado no Hub, por exemplo, bigscience/bloom.
- Or a path to a directory containing model weights saved using save_pretrained, e.g., ../path/to/my_model_directory/.
revision (str, opcional) — Revisão do modelo no Hub. Pode ser o nome de um branch, uma tag git ou qualquer id de commit. Padrão: o commit mais recente no branch main.
force_download (bool, opcional, padrão False) — Se deve forçar o (re-)download dos pesos do modelo e dos arquivos de configuração do Hub, sobrescrevendo o cache existente.
token (str ou bool, opcional) — O token a ser usado como autorização de bearer HTTP para arquivos remotos. Por padrão, será usado o token em cache obtido ao executar hf auth login.
cache_dir (str, Path, opcional) — Caminho para a pasta onde os arquivos em cache são armazenados.
local_files_only (bool, opcional, padrão False) — Se True, evita o download do arquivo e retorna o caminho do arquivo em cache local, se ele existir.
model_kwargs (dict, opcional) — Kwargs adicionais para passar ao modelo durante a inicialização.

Baixe um modelo do Huggingface Hub e instancie-o.

push_to_hub

< source >

Parâmetros

repo_id (str) — ID do repositório para o qual será feito o push (exemplo: "username/my-model").
config (dict ou DataclassInstance, opcional) — Configuração do modelo especificada como um dicionário de chave/valor ou uma instância de dataclass.
commit_message (str, opcional) — Mensagem a ser commitada durante o push.
private (bool, opcional) — Se o repositório criado deve ser privado. Se None (padrão), o repositório será público, a menos que o padrão da organização seja privado.
token (str, opcional) — O token a ser usado como autorização de bearer HTTP para arquivos remotos. Por padrão, será usado o token em cache obtido ao executar hf auth login.
branch (str, opcional) — O branch do git no qual o modelo será enviado. O padrão é "main".
create_pr (boolean, opcional) — Se deve ou não criar um Pull Request a partir de branch com esse commit. O padrão é False.
allow_patterns (list[str] ou str, opcional) — Se fornecido, apenas os arquivos que corresponderem a pelo menos um padrão serão enviados.
ignore_patterns (list[str] ou str, opcional) — Se fornecido, os arquivos que corresponderem a qualquer um dos padrões não serão enviados.
delete_patterns (list[str] ou str, opcional) — Se fornecido, os arquivos remotos que corresponderem a qualquer um dos padrões serão excluídos do repositório.
model_card_kwargs (dict[str, Any], opcional) — Argumentos adicionais passados para o modelo do cartão do modelo para personalizar o cartão do modelo.

Envie o checkpoint do modelo para o Hub.

Use allow_patterns e ignore_patterns para filtrar com precisão quais arquivos devem ser enviados para o hub. Use delete_patterns para excluir arquivos remotos existentes no mesmo commit. Consulte a referência de upload_folder() para mais detalhes.

save_pretrained

< source >

Parâmetros

save_directory (str ou Path) — Caminho para o diretório em que os pesos do modelo e a configuração serão salvos.
config (dict ou DataclassInstance, opcional) — Configuração do modelo especificada como um dicionário de chave/valor ou uma instância de dataclass.
push_to_hub (bool, opcional, padrão False) — Se deve ou não enviar seu modelo para o Huggingface Hub após salvá-lo.
repo_id (str, opcional) — ID do seu repositório no Hub. Usado apenas se push_to_hub=True. Se não for fornecido, o padrão será o nome da pasta.
model_card_kwargs (dict[str, Any], opcional) — Argumentos adicionais passados para o modelo do cartão do modelo para personalizar o cartão do modelo.
push_to_hub_kwargs — Argumentos de palavra-chave adicionais passados ao método push_to_hub().

Retorna

str ou None

URL do commit no Hub se push_to_hub=True, None caso contrário.

Salve os pesos em um diretório local.

PyTorch

classe huggingface_hub.PyTorchModelHubMixin

< source >

( *args**kwargs )

Implementação de ModelHubMixin para fornecer capacidades de upload/download no Hub para modelos PyTorch. O modelo é definido no modo de avaliação por padrão usando model.eval() (módulos de dropout são desativados). Para treinar o modelo, você deve primeiro redefinir o modo de treinamento com model.train().

Veja ModelHubMixin para mais detalhes sobre como usar o mixin.

Exemplo:

>>> import torch
>>> import torch.nn as nn
>>> from huggingface_hub import PyTorchModelHubMixin

>>> class MyModel(
...         nn.Module,
...         PyTorchModelHubMixin,
...         library_name="keras-nlp",
...         repo_url="https://github.com/keras-team/keras-nlp",
...         paper_url="https://arxiv.org/abs/2304.12244",
...         docs_url="https://keras.io/keras_nlp/",
...         # ^ optional metadata to generate model card
...     ):
...     def __init__(self, hidden_size: int = 512, vocab_size: int = 30000, output_size: int = 4):
...         super().__init__()
...         self.param = nn.Parameter(torch.rand(hidden_size, vocab_size))
...         self.linear = nn.Linear(output_size, vocab_size)

...     def forward(self, x):
...         return self.linear(x + self.param)
>>> model = MyModel(hidden_size=256)

# Save model weights to local directory
>>> model.save_pretrained("my-awesome-model")

# Push model weights to the Hub
>>> model.push_to_hub("my-awesome-model")

# Download and initialize weights from the Hub
>>> model = MyModel.from_pretrained("username/my-awesome-model")
>>> model.hidden_size
256

Fastai

huggingface_hub.from_pretrained_fastai

< source >

( repo_id: strrevision: str | None = None )

Parâmetros

repo_id (str) — A localização onde o fastai.Learner serializado (pickled) está. Pode ser uma das duas opções:
- Hospedado no Hugging Face Hub. Ex.: ‘espejelomar/fatai-pet-breeds-classification’ ou ‘distilgpt2’. Você pode adicionar uma revision acrescentando @ ao final de repo_id. Ex.: dbmdz/bert-base-german-cased@main. Revision é a versão específica do modelo a ser usada. Como usamos um sistema baseado em git para armazenar modelos e outros artefatos no Hugging Face Hub, ela pode ser um nome de branch, um nome de tag ou um id de commit.
- Hospedado localmente. repo_id seria um diretório contendo o pickle e um pyproject.toml indicando as versões do fastai e do fastcore usadas para construir o fastai.Learner. Ex.: ./my_model_directory/.
revision (str, opcional) — Revisão na qual os arquivos do repositório são baixados. Consulte a documentação de snapshot_download.

Carregue um modelo fastai pré-treinado do Hub ou de um diretório local.

huggingface_hub.push_to_hub_fastai

< source >

Parâmetros

learner (Learner) — O *fastai.Learner’ que você deseja enviar para o Hub.
repo_id (str) — O id do repositório do seu modelo no Hub, no formato “namespace/repo_name”. O namespace pode ser sua conta individual ou uma organização à qual você tem acesso de escrita (por exemplo, ‘stanfordnlp/stanza-de’).
commit_message (str`, opcional*) — Mensagem para o commit ao fazer push. O padrão é "add model".
private (bool, opcional) — Se o repositório criado deve ser privado ou não. Se None (padrão), será público por padrão, exceto se o padrão da organização for privado.
token (str, opcional) — O token da conta do Hugging Face a ser usado como autorização bearer HTTP para arquivos remotos. Se None, o token será solicitado por meio de um prompt.
config (dict, optional) — Configuration object to be saved alongside the model weights.
branch (str, opcional) — O branch do git no qual o modelo será enviado. O padrão é o branch padrão especificado no seu repositório, que por padrão é “main”.
create_pr (boolean, opcional) — Se deve ou não criar um Pull Request a partir de branch com esse commit. Padrão é False.
api_endpoint (str, opcional) — O endpoint da API a ser usado ao enviar o modelo para o hub.
allow_patterns (list[str] ou str, opcional) — Se fornecido, apenas os arquivos que corresponderem a pelo menos um padrão serão enviados.
ignore_patterns (list[str] ou str, opcional) — Se fornecido, os arquivos que corresponderem a qualquer um dos padrões não serão enviados.
delete_patterns (list[str] ou str, opcional) — Se fornecido, os arquivos remotos que corresponderem a qualquer um dos padrões serão excluídos do repositório.

Envie os arquivos de checkpoint do aprendiz para o Hub.

Use allow_patterns e ignore_patterns para filtrar com precisão quais arquivos devem ser enviados ao hub. Use delete_patterns para excluir arquivos remotos existentes no mesmo commit. Consulte a referência de [upload_folder] para mais detalhes.

Gera o seguinte erro:

ValueError se o usuário não estiver conectado ao Hugging Face Hub.

Update on GitHub

Hub Python Library

Mixins & métodos de serialização

Mixins

Genérico

classe huggingface_hub.ModelHubMixin

_save_pretrained

_from_pretrained

from_pretrained

push_to_hub

save_pretrained

PyTorch

classe huggingface_hub.PyTorchModelHubMixin

Fastai

huggingface_hub.from_pretrained_fastai

huggingface_hub.push_to_hub_fastai