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

## Миксины

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

### Универсальный[[huggingface_hub.ModelHubMixin]]

#### huggingface_hub.ModelHubMixin[[huggingface_hub.ModelHubMixin]]

```python
huggingface_hub.ModelHubMixin(*args, **kwargs)
```

[Источник](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/hub_mixin.py#L66)

**Параметры:**

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]]`, *необязательный*) : Словарь пользовательских типов и их кодировщиков/декодировщиков. Используется для кодирования/декодирования аргументов, которые по умолчанию не поддерживаются форматом JSON. Например, dataclasses, argparse.Namespace, OmegaConf и т. д.

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

Чтобы интегрировать ваш фреймворк, класс вашей модели должен наследоваться от этого класса. Пользовательская логика сохранения/загрузки моделей должна быть переопределена в `_from_pretrained` и `_save_pretrained`. [PyTorchModelHubMixin](/docs/huggingface_hub/v2.4.0/ru/package_reference/mixins#huggingface_hub.PyTorchModelHubMixin) — хороший пример интеграции миксина с Hub. Подробнее см. в нашем [руководстве по интеграции](../guides/integrations).

При наследовании от [ModelHubMixin](/docs/huggingface_hub/v2.4.0/ru/package_reference/mixins#huggingface_hub.ModelHubMixin) можно определить атрибуты на уровне класса. Эти атрибуты не передаются в `__init__`, а задаются непосредственно в определении класса. Это удобно для описания метаданных библиотеки, интегрирующей [ModelHubMixin](/docs/huggingface_hub/v2.4.0/ru/package_reference/mixins#huggingface_hub.ModelHubMixin).

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

Пример:

```python
>>> 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[[huggingface_hub.ModelHubMixin._save_pretrained]]

```python
_save_pretrained(save_directory: Path)
```

[Источник](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/hub_mixin.py#L440)

**Параметры:**

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

Переопределите этот метод в подклассе, чтобы определить способ сохранения вашей модели. Инструкции см. в нашем [руководстве по интеграции](../guides/integrations).

#### _from_pretrained[[huggingface_hub.ModelHubMixin._from_pretrained]]

```python
_from_pretrained(model_id: str, revision: str | None, cache_dir: str | pathlib.Path | None, force_download: bool, local_files_only: bool, token: str | bool | None, **model_kwargs)
```

[Источник](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/hub_mixin.py#L567)

**Параметры:**

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()](/docs/huggingface_hub/v2.4.0/ru/package_reference/mixins#huggingface_hub.ModelHubMixin._from_pretrained).

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

Используйте [hf_hub_download()](/docs/huggingface_hub/v2.4.0/ru/package_reference/file_download#huggingface_hub.hf_hub_download) или [snapshot_download()](/docs/huggingface_hub/v2.4.0/ru/package_reference/file_download#huggingface_hub.snapshot_download) для загрузки файлов с Hub перед их чтением. Большинство входных аргументов можно напрямую передать этим двум методам. При необходимости вы можете добавить дополнительные аргументы к этому методу с помощью "model_kwargs". Например, `PyTorchModelHubMixin._from_pretrained()` принимает параметр `map_location` для указания устройства, на котором должна быть загружена модель.

См. нашу [инструкцию по интеграции](../guides/integrations) для получения дополнительных сведений.

#### from_pretrained[[huggingface_hub.ModelHubMixin.from_pretrained]]

```python
from_pretrained(pretrained_model_name_or_path: str | pathlib.Path, force_download: bool = False, token: str | bool | None = None, cache_dir: str | pathlib.Path | None = None, local_files_only: bool = False, revision: str | None = None, **model_kwargs)
```

[Источник](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/hub_mixin.py#L451)

**Параметры:**

pretrained_model_name_or_path (`str`, `Path`) : - Either the `model_id` (string) of a model hosted on the Hub, e.g. `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[[huggingface_hub.ModelHubMixin.push_to_hub]]

```python
push_to_hub(repo_id: str, config: dict | huggingface_hub.hub_mixin.DataclassInstance | None = None, commit_message: str = 'Push model using huggingface_hub.', private: bool | None = None, token: str | None = None, branch: str | None = None, create_pr: bool | None = None, allow_patterns: list[str] | str | None = None, ignore_patterns: list[str] | str | None = None, delete_patterns: list[str] | str | None = None, model_card_kwargs: dict[str, typing.Any] | None = None)
```

[Источник](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/hub_mixin.py#L609)

**Параметры:**

repo_id (`str`) : идентификатор репозитория, в который выполняется отправка (пример: `"username/my-model"`).

config (`dict` или `DataclassInstance`, *необязательный*) : Конфигурация модели, заданная в виде словаря ключ/значение или экземпляра dataclass.

commit_message (`str`, *необязательный*) : Сообщение для коммита при выполнении push.

private (`bool`, *optional*) : Указывает, должна ли созданная репозитория быть закрытой. Если `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]`, *необязательный*) : Дополнительные аргументы, передаваемые в шаблон карточки модели для её настройки.

**Возвращает:**

URL коммита вашей модели в указанном репозитории.

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

Используйте `allow_patterns` и `ignore_patterns`, чтобы точно отфильтровать файлы, которые следует отправить в хаб. Используйте `delete_patterns`, чтобы удалить существующие удалённые файлы в том же коммите. Подробнее см. в справке по [upload_folder()](/docs/huggingface_hub/v2.4.0/ru/package_reference/hf_api#huggingface_hub.HfApi.upload_folder).

#### save_pretrained[[huggingface_hub.ModelHubMixin.save_pretrained]]

```python
save_pretrained(save_directory: str | pathlib.Path, config: dict | huggingface_hub.hub_mixin.DataclassInstance | None = None, repo_id: str | None = None, push_to_hub: bool = False, model_card_kwargs: dict[str, typing.Any] | None = None, **push_to_hub_kwargs)
```

[Источник](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/hub_mixin.py#L372)

**Параметры:**

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()](/docs/huggingface_hub/v2.4.0/ru/package_reference/mixins#huggingface_hub.ModelHubMixin.push_to_hub).

**Возвращает:** `str` или `None`

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

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

### PyTorch[[huggingface_hub.PyTorchModelHubMixin]]

#### huggingface_hub.PyTorchModelHubMixin[[huggingface_hub.PyTorchModelHubMixin]]

```python
huggingface_hub.PyTorchModelHubMixin(*args, **kwargs)
```

[Источник](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/hub_mixin.py#L692)

Реализация [ModelHubMixin](/docs/huggingface_hub/v2.4.0/ru/package_reference/mixins#huggingface_hub.ModelHubMixin) для предоставления PyTorch-моделям возможностей загрузки и скачивания с Hub. По умолчанию модель переводится в режим оценки с помощью `model.eval()` (модули dropout отключаются). Для обучения модели сначала необходимо вернуть её в режим обучения с помощью `model.train()`.

См. [ModelHubMixin](/docs/huggingface_hub/v2.4.0/ru/package_reference/mixins#huggingface_hub.ModelHubMixin) для получения подробной информации о том, как использовать миксин.

Пример:

```python
>>> 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]]

#### huggingface_hub.from_pretrained_fastai[[huggingface_hub.from_pretrained_fastai]]

```python
huggingface_hub.from_pretrained_fastai(repo_id: str, revision: str | None = None)
```

[Источник](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/fastai_utils.py#L289)

**Параметры:**

repo_id (`str`) : Расположение файла с сериализованным объектом 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.Learner` в репозитории `repo_id`.

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

#### huggingface_hub.push_to_hub_fastai[[huggingface_hub.push_to_hub_fastai]]

```python
huggingface_hub.push_to_hub_fastai(learner, repo_id: str, commit_message: str = 'Push FastAI model using huggingface_hub.', private: bool | None = None, token: str | None = None, config: dict | None = None, branch: str | None = None, create_pr: bool | None = None, allow_patterns: list[str] | str | None = None, ignore_patterns: list[str] | str | None = None, delete_patterns: list[str] | str | None = None, api_endpoint: str | None = None)
```

[Источник](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/fastai_utils.py#L334)

**Параметры:**

learner (*Learner*) : объект *fastai.Learner', который вы хотите загрузить в Hub.

repo_id (*str*) : Идентификатор репозитория вашей модели в Hub в формате "namespace/repo_name". Пространство имён (namespace) может указывать на вашу личную учётную запись или организацию, к которой у вас есть права на запись (например, 'stanfordnlp/stanza-de').

commit_message (*str`, *optional*) : Message to commit while pushing. Will default to `"add model"`.

private (*bool*, *optional*) : Указывает, должен ли созданный репозиторий быть закрытым. Если *None* (по умолчанию), репозиторий будет открытым, если только по умолчанию для организации не задан закрытый доступ.

token (*str*, *optional*) : Токен аккаунта Hugging Face, используемый в качестве HTTP bearer-авторизации для удалённых файлов. Если `None`, токен будет запрошен через подсказку.

config (*dict*, *optional*) : Объект конфигурации, который сохраняется вместе с весами модели.

branch (*str*, *optional*) : ветка git, на которую нужно отправить модель. По умолчанию используется ветка по умолчанию, указанная в вашем репозитории, которая по умолчанию равна *"main"*.

create_pr (*boolean*, *optional*) : Создавать ли Pull Request из ветки *branch* с этим коммитом. По умолчанию *False*.

api_endpoint (*str*, *optional*) : API-эндпоинт, используемый при отправке модели на хаб.

allow_patterns (*list[str]* или *str*, *необязательный*) : Если указано, загружаются только файлы, соответствующие хотя бы одному шаблону.

ignore_patterns (*list[str]* или *str*, *необязательный*) : Если указано, файлы, соответствующие любому из шаблонов, не будут загружены.

delete_patterns (*list[str]* или *str*, *необязательный*) : Если указано, удалённые файлы, соответствующие любому из шаблонов, будут удалены из репозитория.

**Возвращает:**

URL коммита вашей модели в указанном репозитории.

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

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

> [!TIP]
> Вызывает следующую ошибку:
>
> - [*ValueError*](https://docs.python.org/3/library/exceptions.html#ValueError), если пользователь не вошёл в аккаунт Hugging Face Hub.