Hub Python Library documentation

Миксины и методы сериализации

Hub Python Library

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

Миксины и методы сериализации

Миксины

Библиотека huggingface_hub предлагает набор миксинов, которые можно использовать в качестве родительского класса для ваших объектов, чтобы обеспечить простые функции загрузки и скачивания. Ознакомьтесь с нашим руководством по интеграции, чтобы узнать, как интегрировать любой ML-фреймворк с Hub.

Универсальный

класс huggingface_hub.ModelHubMixin

< source >

( *args**kwargs )

Параметры

repo_url (str, необязательный) — URL репозитория библиотеки. Используется для генерации карточки модели.
paper_url (str, необязательный) — URL статьи библиотеки. Используется для генерации карточки модели.
docs_url (str, необязательный) — URL документации библиотеки. Используется для генерации карточки модели.
model_card_template (str, необязательный) — Шаблон карточки модели. Используется для генерации карточки модели. По умолчанию используется универсальный шаблон.
language (str или list[str], необязательный) — Язык, поддерживаемый библиотекой. Используется для генерации карточки модели.
library_name (str, необязательный) — Название библиотеки, интегрирующей ModelHubMixin. Используется для генерации карточки модели.
license (str, необязательный) — Лицензия библиотеки, интегрирующей ModelHubMixin. Используется для генерации карточки модели. Например: “apache-2.0”
license_name (str, необязательный) — Название библиотеки, интегрирующей ModelHubMixin. Используется для генерации карточки модели. Применяется только в том случае, если license установлен в значение other. Например: “coqui-public-model-license”.
license_link (str, необязательный) — URL лицензии библиотеки, интегрирующей ModelHubMixin. Используется для генерации карточки модели. Применяется только в том случае, если license установлен в значение other и задан license_name. Например: ”https://coqui.ai/cpml”.
pipeline_tag (str, необязательный) — Тег пайплайна. Используется для генерации карточки модели. Например, “text-classification”.
tags (list[str], необязательный) — Теги, которые будут добавлены в карточку модели. Используются для генерации карточки модели. Например, [“computer-vision”]
coders (dict[Type, tuple[Callable, Callable]], необязательный) — Словарь пользовательских типов и их кодировщиков/декодировщиков. Используется для кодирования/декодирования аргументов, которые по умолчанию не являются jsonable. Например, dataclasses, argparse.Namespace, OmegaConf и т. д.

Универсальный миксин для интеграции любого фреймворка машинного обучения с Hub.

Чтобы интегрировать ваш фреймворк, класс вашей модели должен наследоваться от этого класса. Пользовательская логика сохранения/загрузки моделей должна быть переопределена в _from_pretrained и _save_pretrained. PyTorchModelHubMixin — хороший пример интеграции миксина с Hub. Дополнительные инструкции см. в нашем руководстве по интеграции.

При наследовании от ModelHubMixin можно определить атрибуты на уровне класса. Эти атрибуты не передаются в __init__, а задаются непосредственно в определении класса. Это удобно для описания метаданных библиотеки, интегрирующей ModelHubMixin.

Для получения подробной информации о том, как интегрировать миксин с вашей библиотекой, ознакомьтесь с руководством по интеграции.

Пример:

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

Параметры

save_directory (str или Path) — Путь к каталогу, в котором будут сохранены веса модели и конфигурация.

Переопределите этот метод в подклассе, чтобы определить, как сохранять вашу модель. Инструкции см. в нашем руководстве по интеграции.

_from_pretrained

< source >

Параметры

model_id (str) — идентификатор модели для загрузки из Huggingface Hub (например, bigscience/bloom).
revision (str, необязательный) — Ревизия модели на Hub. Может быть именем ветки, git-тегом или любым идентификатором коммита. По умолчанию используется последний коммит ветки main.
force_download (bool, необязательный, по умолчанию False) — Следует ли принудительно (пере)скачивать веса модели и файлы конфигурации с Hub, игнорируя существующий кэш.
token (str или bool, необязательный) — Токен, используемый в качестве HTTP bearer-авторизации для удалённых файлов. По умолчанию используется токен, кэшированный при выполнении hf auth login.
cache_dir (str, Path, необязательный) — Путь к папке, в которой хранятся кэшированные файлы.
local_files_only (bool, необязательный, по умолчанию False) — Если True, не загружать файл, а вернуть путь к локальному кэшированному файлу, если он существует.
model_kwargs — Дополнительные именованные аргументы, передаваемые в метод _from_pretrained().

Переопределите этот метод в подклассе, чтобы определить, как загружать вашу модель из предобученной.

Используйте hf_hub_download() или snapshot_download() для загрузки файлов с Hub перед их чтением. Большинство аргументов, принимаемых на входе, можно напрямую передать этим двум методам. При необходимости вы можете добавить дополнительные аргументы к этому методу с помощью «model_kwargs». Например, PyTorchModelHubMixin._from_pretrained() принимает на вход параметр map_location, чтобы задать устройство, на котором должна быть загружена модель.

См. нашу инструкцию по интеграции для получения дополнительных сведений.

from_pretrained

< source >

Параметры

pretrained_model_name_or_path (str, Path) —
- Либо model_id (строка) модели, размещённой на Hub, например bigscience/bloom.
- Or a path to a directory containing model weights saved using save_pretrained, e.g., ../path/to/my_model_directory/.
revision (str, необязательный) — Ревизия модели на Hub. Может быть именем ветки, git-тегом или идентификатором любого коммита. По умолчанию используется последний коммит ветки main.
force_download (bool, необязательный, по умолчанию False) — Следует ли принудительно (пере)скачивать веса модели и файлы конфигурации с Hub, игнорируя существующий кэш.
token (str или bool, необязательный) — Токен, используемый в качестве HTTP bearer-авторизации для удалённых файлов. По умолчанию используется токен, кэшированный при выполнении hf auth login.
cache_dir (str, Path, необязательный) — Путь к папке, в которой хранятся кэшированные файлы.
local_files_only (bool, необязательный, по умолчанию False) — Если True, не загружать файл, а вернуть путь к локальному кэшированному файлу, если он существует.
model_kwargs (dict, необязательный) — Дополнительные аргументы, передаваемые в модель при инициализации.

Скачайте модель из Huggingface Hub и создайте её экземпляр.

push_to_hub

< source >

Параметры

repo_id (str) — идентификатор репозитория, в который выполняется публикация (пример: "username/my-model").
config (dict или DataclassInstance, необязательный) — Конфигурация модели, заданная в виде словаря ключ/значение или экземпляра dataclass.
commit_message (str, необязательный) — Сообщение для коммита при отправке.
private (bool, необязательный) — Определяет, должна ли созданная репозитория быть закрытой. Если None (по умолчанию), репозитория будет публичной, если только по умолчанию для организации не задан закрытый доступ.
token (str, необязательный) — Токен, используемый в качестве HTTP bearer-авторизации для удалённых файлов. По умолчанию используется токен, кэшированный при выполнении hf auth login.
branch (str, необязательный) — Git-ветка, на которую будет выполнена отправка модели. По умолчанию используется "main".
create_pr (boolean, необязательный) — Создавать ли Pull Request из ветки branch с этим коммитом. По умолчанию False.
allow_patterns (list[str] или str, необязательный) — Если указано, загружаются только файлы, соответствующие хотя бы одному шаблону.
ignore_patterns (list[str] или str, необязательный) — Если указано, файлы, соответствующие любому из шаблонов, не отправляются.
delete_patterns (list[str] или str, необязательный) — Если указано, удалённые файлы, соответствующие любому из шаблонов, будут удалены из репозитория.
model_card_kwargs (dict[str, Any], необязательный) — Дополнительные аргументы, передаваемые в шаблон карточки модели для её настройки.

Загрузите контрольную точку модели в Hub.

Используйте allow_patterns и ignore_patterns, чтобы точно отфильтровать файлы, которые следует отправить в хаб. Используйте delete_patterns, чтобы удалить существующие удалённые файлы в том же коммите. Подробнее см. в справке по upload_folder().

save_pretrained

< source >

Параметры

save_directory (str или Path) — Путь к каталогу, в котором будут сохранены веса модели и конфигурация.
config (dict или DataclassInstance, необязательный) — Конфигурация модели, заданная в виде словаря ключ/значение или экземпляра dataclass.
push_to_hub (bool, необязательный, по умолчанию False) — Следует ли загружать модель в Huggingface Hub после её сохранения.
repo_id (str, необязательный) — идентификатор вашего репозитория на Hub. Используется только при push_to_hub=True. Если не указан, по умолчанию используется имя папки.
model_card_kwargs (dict[str, Any], необязательный) — Дополнительные аргументы, передаваемые в шаблон карточки модели для её настройки.
push_to_hub_kwargs — Дополнительные именованные аргументы, передаваемые в метод push_to_hub().

Возвращает

str или None

URL коммита на Hub, если push_to_hub=True, иначе None.

Сохранить веса в локальный каталог.

PyTorch

класс huggingface_hub.PyTorchModelHubMixin

< source >

( *args**kwargs )

Реализация ModelHubMixin для предоставления PyTorch-моделям возможностей загрузки и скачивания с Hub. По умолчанию модель переводится в режим оценки с помощью model.eval() (модули dropout отключаются). Для обучения модели сначала необходимо вернуть её в режим обучения с помощью model.train().

См. ModelHubMixin для получения подробной информации о том, как использовать миксин.

Пример:

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

Параметры

repo_id (str) — Место, где находится pickle-файл fastai.Learner. Это может быть одно из двух:
- Размещено на Hugging Face Hub. Например: ‘espejelomar/fatai-pet-breeds-classification’ или ‘distilgpt2’. Вы можете добавить revision, добавив @ в конце repo_id. Например: dbmdz/bert-base-german-cased@main. Revision — это конкретная версия модели, которую следует использовать. Поскольку для хранения моделей и других артефактов на Hugging Face Hub используется система на базе git, это может быть имя ветки, имя тега или идентификатор коммита.
- Размещено локально. repo_id будет каталогом, содержащим pickle и pyproject.toml, указывающим версии fastai и fastcore, использованные для сборки fastai.Learner. Например: ./my_model_directory/.
revision (str, необязательный) — Ревизия, в которой загружаются файлы репозитория. См. документацию snapshot_download.

Загрузите предобученную модель fastai из Hub или из локального каталога.

huggingface_hub.push_to_hub_fastai

< source >

Параметры

learner (Learner) — *fastai.Learner’ для загрузки в Hub.
repo_id (str) — Идентификатор репозитория вашей модели на Hub в формате «namespace/repo_name». Пространство имён может быть вашим личным аккаунтом или организацией, к которой у вас есть права на запись (например, ‘stanfordnlp/stanza-de’).
commit_message (str`, необязательный*) — Сообщение для коммита при выполнении push. По умолчанию — "add model".
private (bool, optional) — Определяет, должна ли созданная репозитория быть закрытой. Если None (по умолчанию), репозитория будет публичной, если только по умолчанию для организации не задан закрытый доступ.
token (str, optional) — Токен аккаунта Hugging Face, используемый в качестве HTTP bearer-авторизации для удалённых файлов. Если None, токен будет запрошен через подсказку.
config (dict, необязательный) — Объект конфигурации, который сохраняется вместе с весами модели.
branch (str, optional) — Git-ветка, на которую будет выполнена отправка модели. По умолчанию используется ветка по умолчанию, указанная в вашем репозитории, которая по умолчанию равна “main”.
create_pr (boolean, необязательный) — Создавать ли Pull Request из ветки branch с этим коммитом. По умолчанию False.
api_endpoint (str, optional) — Точка входа API, используемая при отправке модели на хаб.
allow_patterns (list[str] или str, необязательный) — Если указано, загружаются только файлы, соответствующие хотя бы одному шаблону.
ignore_patterns (list[str] или str, необязательный) — Если указано, файлы, соответствующие любому из шаблонов, не загружаются.
delete_patterns (list[str] или str, необязательный) — Если указано, удалённые файлы, соответствующие любому из шаблонов, будут удалены из репозитория.

Загрузите файлы контрольных точек обучающего агента в Hub.

Используйте allow_patterns и ignore_patterns, чтобы точно отфильтровать файлы, которые следует отправить в хаб. Используйте delete_patterns, чтобы удалить существующие удалённые файлы в том же коммите. Подробнее см. в справке по [upload_folder].

Вызывает следующую ошибку:

ValueError, если пользователь не вошёл в аккаунт на Hugging Face Hub.

Update on GitHub

←Загрузка файлов Типы инференса→