# Mixins & các phương thức serialize

## Mixins

Thư viện `huggingface_hub` cung cấp một loạt các mixin có thể được sử dụng làm lớp cha cho các đối tượng của bạn, nhằm cung cấp các hàm tải lên và tải xuống đơn giản. Xem [hướng dẫn tích hợp](../guides/integrations) của chúng tôi để tìm hiểu cách tích hợp bất kỳ framework ML nào với Hub.

### Tổng quát[[huggingface_hub.ModelHubMixin]]

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

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

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/hub_mixin.py#L66)

**Tham số:**

repo_url (`str`, *tùy chọn*) : URL của kho thư viện. Được dùng để tạo thẻ mô hình.

paper_url (`str`, *tùy chọn*) : URL của bài báo thư viện. Được sử dụng để tạo thẻ mô hình.

docs_url (`str`, *tùy chọn*) : URL của tài liệu thư viện. Được dùng để tạo thẻ mô hình.

model_card_template (`str`, *tùy chọn*) : Mẫu của thẻ mô hình. Được sử dụng để tạo thẻ mô hình. Mặc định là một mẫu chung chung.

language (`str` hoặc `list[str]`, *tùy chọn*) : Ngôn ngữ được thư viện hỗ trợ. Được sử dụng để tạo thẻ mô hình.

library_name (`str`, *tùy chọn*) : Tên của thư viện tích hợp ModelHubMixin. Được dùng để tạo model card.

license (`str`, *tùy chọn*) : Giấy phép của thư viện tích hợp ModelHubMixin. Được sử dụng để tạo thẻ mô hình. Ví dụ: "apache-2.0"

license_name (`str`, *tùy chọn*) : Tên của thư viện tích hợp ModelHubMixin. Được dùng để tạo model card. Chỉ được dùng nếu `license` được đặt thành `other`. Ví dụ: "coqui-public-model-license".

license_link (`str`, *tùy chọn*) : URL của giấy phép cho thư viện tích hợp ModelHubMixin. Được sử dụng để tạo thẻ mô hình. Chỉ được dùng khi `license` được đặt thành `other` và `license_name` được đặt. Ví dụ: "https://coqui.ai/cpml".

pipeline_tag (`str`, *tùy chọn*) : Thẻ của pipeline. Được sử dụng để tạo thẻ mô hình. Ví dụ: "text-classification".

tags (`list[str]`, *tùy chọn*) : Các thẻ cần thêm vào thẻ mô hình. Được sử dụng để tạo thẻ mô hình. Ví dụ: ["computer-vision"]

coders (`dict[Type, tuple[Callable, Callable]]`, *tùy chọn*) : Từ điển các kiểu dữ liệu tùy chỉnh cùng bộ mã hóa/giải mã tương ứng. Được dùng để mã hóa/giải mã các đối số không thể chuyển đổi sang JSON theo mặc định. Ví dụ: dataclasses, argparse.Namespace, OmegaConf, v.v.

Một mixin tổng quát để tích hợp BẤT KỲ framework machine learning nào với Hub.

Để tích hợp framework của bạn, lớp model của bạn phải kế thừa từ lớp này. Logic tùy chỉnh cho việc lưu/tải model phải được ghi đè trong `_from_pretrained` và `_save_pretrained`. [PyTorchModelHubMixin](/docs/huggingface_hub/v2.4.0/vi/package_reference/mixins#huggingface_hub.PyTorchModelHubMixin) là một ví dụ tốt về tích hợp mixin với Hub. Xem [hướng dẫn tích hợp](../guides/integrations) của chúng tôi để biết thêm chi tiết.

Khi kế thừa từ [ModelHubMixin](/docs/huggingface_hub/v2.4.0/vi/package_reference/mixins#huggingface_hub.ModelHubMixin), bạn có thể định nghĩa các thuộc tính ở cấp lớp. Các thuộc tính này không được truyền vào `__init__` mà vào chính định nghĩa của lớp. Điều này hữu ích để định nghĩa các siêu dữ liệu về thư viện tích hợp [ModelHubMixin](/docs/huggingface_hub/v2.4.0/vi/package_reference/mixins#huggingface_hub.ModelHubMixin).

Để biết thêm chi tiết về cách tích hợp mixin với thư viện của bạn, hãy xem [hướng dẫn tích hợp](../guides/integrations).

Ví dụ:

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

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/hub_mixin.py#L440)

**Tham số:**

save_directory (`str` hoặc `Path`) : Đường dẫn đến thư mục mà trọng số và cấu hình của mô hình sẽ được lưu.

Ghi đè phương thức này trong lớp con để định nghĩa cách lưu mô hình của bạn. Xem [hướng dẫn tích hợp](../guides/integrations) của chúng tôi để biết các bước thực hiện.

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

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/hub_mixin.py#L567)

**Tham số:**

model_id (`str`) : ID của model cần tải từ Huggingface Hub (ví dụ: `bigscience/bloom`).

revision (`str`, *tùy chọn*) : Phiên bản của mô hình trên Hub. Có thể là tên nhánh, một git tag hoặc bất kỳ commit id nào. Mặc định là commit mới nhất trên nhánh `main`.

force_download (`bool`, *tùy chọn*, mặc định là `False`) : Có nên buộc (tải lại) các trọng số mô hình và tệp cấu hình từ Hub, ghi đè lên bộ nhớ đệm hiện có hay không.

token (`str` hoặc `bool`, *tùy chọn*) : Token được sử dụng làm HTTP bearer authorization cho các tệp từ xa. Mặc định, nó sẽ sử dụng token được lưu cache khi chạy `hf auth login`.

cache_dir (`str`, `Path`, *tùy chọn*) : Đường dẫn đến thư mục nơi lưu trữ các tệp được lưu trong bộ nhớ đệm.

local_files_only (`bool`, *tùy chọn*, mặc định là `False`) : Nếu `True`, tránh tải xuống tệp và trả về đường dẫn đến tệp được lưu trong bộ nhớ đệm cục bộ nếu tệp đó tồn tại.

model_kwargs : Các đối số từ khóa bổ sung được truyền đến phương thức [_from_pretrained()](/docs/huggingface_hub/v2.4.0/vi/package_reference/mixins#huggingface_hub.ModelHubMixin._from_pretrained).

Ghi đè phương thức này trong lớp con để định nghĩa cách tải mô hình của bạn từ mô hình được huấn luyện trước.

Sử dụng [hf_hub_download()](/docs/huggingface_hub/v2.4.0/vi/package_reference/file_download#huggingface_hub.hf_hub_download) hoặc [snapshot_download()](/docs/huggingface_hub/v2.4.0/vi/package_reference/file_download#huggingface_hub.snapshot_download) để tải các tệp từ Hub trước khi nạp chúng. Hầu hết các đối số được nhận làm đầu vào có thể được truyền trực tiếp vào 2 phương thức đó. Nếu cần, bạn có thể thêm nhiều đối số hơn vào phương thức này bằng cách sử dụng "model_kwargs". Ví dụ, `PyTorchModelHubMixin._from_pretrained()` nhận một tham số `map_location` làm đầu vào để thiết bị mà mô hình nên được nạp lên.

Xem [hướng dẫn tích hợp](../guides/integrations) của chúng tôi để biết thêm chi tiết.

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

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/hub_mixin.py#L451)

**Tham số:**

pretrained_model_name_or_path (`str`, `Path`) : - Hoặc là `model_id` (chuỗi) của một model được lưu trữ trên Hub, ví dụ `bigscience/bloom`. - Hoặc là đường dẫn đến một `directory` chứa model weights được lưu bằng `save_pretrained`, ví dụ, `../path/to/my_model_directory/`.

revision (`str`, *tùy chọn*) : Phiên bản của mô hình trên Hub. Có thể là tên nhánh, một git tag hoặc bất kỳ commit id nào. Mặc định là commit mới nhất trên nhánh `main`.

force_download (`bool`, *tùy chọn*, mặc định là `False`) : Có nên buộc (tải lại) các trọng số mô hình và tệp cấu hình từ Hub, ghi đè lên bộ nhớ đệm hiện có hay không.

token (`str` hoặc `bool`, *tùy chọn*) : Token được sử dụng làm HTTP bearer authorization cho các tệp từ xa. Mặc định, nó sẽ sử dụng token được lưu cache khi chạy `hf auth login`.

cache_dir (`str`, `Path`, *tùy chọn*) : Đường dẫn đến thư mục nơi lưu trữ các tệp được lưu trong bộ nhớ đệm.

local_files_only (`bool`, *tùy chọn*, mặc định là `False`) : Nếu `True`, tránh tải xuống tệp và trả về đường dẫn đến tệp được lưu trong bộ nhớ đệm cục bộ nếu tệp đó tồn tại.

model_kwargs (`dict`, *tùy chọn*) : Các kwargs bổ sung để truyền cho model trong quá trình khởi tạo.

Tải một mô hình từ Huggingface Hub và khởi tạo nó.

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

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/hub_mixin.py#L609)

**Tham số:**

repo_id (`str`) : ID của kho cần đẩy lên (ví dụ: `"username/my-model"`).

config (`dict` hoặc `DataclassInstance`, *tùy chọn*) : Cấu hình mô hình được chỉ định dưới dạng từ điển khóa/giá trị hoặc một instance của dataclass.

commit_message (`str`, *tùy chọn*) : Thông điệp để cam kết khi đẩy.

private (`bool`, *tuỳ chọn*) : Xác định xem kho được tạo có nên là riêng tư hay không. Nếu là `None` (mặc định), kho sẽ là công khai trừ khi mặc định của tổ chức là riêng tư.

token (`str`, *tùy chọn*) : Token được sử dụng làm HTTP bearer authorization cho các tệp từ xa. Mặc định, nó sẽ sử dụng token được lưu cache khi chạy `hf auth login`.

branch (`str`, *tùy chọn*) : Nhánh git để đẩy mô hình lên. Mặc định là `"main"`.

create_pr (`boolean`, *tùy chọn*) : Có tạo Pull Request từ `branch` với commit đó hay không. Mặc định là `False`.

allow_patterns (`list[str]` hoặc `str`, *tùy chọn*) : Nếu được cung cấp, chỉ các tệp khớp với ít nhất một mẫu mới được đẩy lên.

ignore_patterns (`list[str]` hoặc `str`, *tùy chọn*) : Nếu được cung cấp, các tệp khớp với bất kỳ mẫu nào sẽ không được đẩy lên.

delete_patterns (`list[str]` hoặc `str`, *tùy chọn*) : Nếu được cung cấp, các tệp từ xa khớp với bất kỳ mẫu nào sẽ bị xóa khỏi kho.

model_card_kwargs (`dict[str, Any]`, *tùy chọn*) : Các đối số bổ sung được truyền vào mẫu thẻ mô hình để tùy chỉnh thẻ mô hình.

**Trả về:**

URL của commit của mô hình của bạn trong kho lưu trữ đã cho.

Tải checkpoint mô hình lên Hub.

Sử dụng `allow_patterns` và `ignore_patterns` để lọc chính xác các tệp cần đẩy lên hub. Sử dụng `delete_patterns` để xóa các tệp từ xa hiện có trong cùng một commit. Xem [upload_folder()](/docs/huggingface_hub/v2.4.0/vi/package_reference/hf_api#huggingface_hub.HfApi.upload_folder) để biết thêm chi tiết.

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

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/hub_mixin.py#L372)

**Tham số:**

save_directory (`str` hoặc `Path`) : Đường dẫn đến thư mục mà trọng số và cấu hình của mô hình sẽ được lưu.

config (`dict` hoặc `DataclassInstance`, *tùy chọn*) : Cấu hình mô hình được chỉ định dưới dạng từ điển khóa/giá trị hoặc một instance của dataclass.

push_to_hub (`bool`, *tùy chọn*, mặc định là `False`) : Có đẩy mô hình của bạn lên Huggingface Hub sau khi lưu hay không.

repo_id (`str`, *tùy chọn*) : ID của kho lưu trữ của bạn trên Hub. Chỉ được sử dụng nếu `push_to_hub=True`. Nếu không được cung cấp, giá trị mặc định sẽ là tên thư mục.

model_card_kwargs (`dict[str, Any]`, *tùy chọn*) : Các đối số bổ sung được truyền vào mẫu thẻ mô hình để tùy chỉnh thẻ mô hình.

push_to_hub_kwargs : Các đối số từ khóa bổ sung được truyền đến phương thức [push_to_hub()](/docs/huggingface_hub/v2.4.0/vi/package_reference/mixins#huggingface_hub.ModelHubMixin.push_to_hub).

**Trả về:** `str` hoặc `None`

đường dẫn URL của commit trên Hub nếu `push_to_hub=True`, `None` nếu không.

Lưu trọng số trong thư mục cục bộ.

### PyTorch[[huggingface_hub.PyTorchModelHubMixin]]

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

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

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/hub_mixin.py#L692)

Cài đặt của [ModelHubMixin](/docs/huggingface_hub/v2.4.0/vi/package_reference/mixins#huggingface_hub.ModelHubMixin) để cung cấp khả năng tải lên/tải xuống Hub cho các mô hình PyTorch. Mô hình được đặt ở chế độ đánh giá theo mặc định bằng `model.eval()` (các module dropout bị vô hiệu hóa). Để huấn luyện mô hình, bạn nên đặt lại nó ở chế độ huấn luyện bằng `model.train()`.

Xem [ModelHubMixin](/docs/huggingface_hub/v2.4.0/vi/package_reference/mixins#huggingface_hub.ModelHubMixin) để biết thêm chi tiết về cách sử dụng mixin.

Ví dụ:

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

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/fastai_utils.py#L289)

**Tham số:**

repo_id (`str`) : Vị trí chứa tệp pickle của fastai.Learner. Có thể là một trong hai trường hợp: - Được lưu trữ trên Hugging Face Hub. Ví dụ: 'espejelomar/fatai-pet-breeds-classification' hoặc 'distilgpt2'. Bạn có thể thêm `revision` bằng cách nối `@` vào cuối `repo_id`. Ví dụ: `dbmdz/bert-base-german-cased@main`. Revision là phiên bản cụ thể của mô hình cần sử dụng. Vì chúng ta sử dụng hệ thống dựa trên git để lưu trữ mô hình và các sản phẩm khác trên Hugging Face Hub, nên nó có thể là tên nhánh, tên tag hoặc id commit. - Được lưu trữ cục bộ. `repo_id` sẽ là thư mục chứa tệp pickle và tệp pyproject.toml chỉ định các phiên bản fastai và fastcore được sử dụng để xây dựng `fastai.Learner`. Ví dụ: `./my_model_directory/`.

revision (`str`, *tùy chọn*) : Phiên bản mà các tệp của kho sẽ được tải xuống. Xem tài liệu của `snapshot_download`.

**Trả về:**

Mô hình `fastai.Learner` trong kho `repo_id`.

Tải mô hình fastai được huấn luyện trước từ Hub hoặc từ một thư mục cục bộ.

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

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/fastai_utils.py#L334)

**Tham số:**

learner (*Learner*) : *fastai.Learner' mà bạn muốn đẩy lên Hub.

repo_id (*str*) : id của kho chứa cho model của bạn trên Hub, theo định dạng "namespace/repo_name". Namespace có thể là tài khoản cá nhân của bạn hoặc một tổ chức mà bạn có quyền ghi (ví dụ: 'stanfordnlp/stanza-de').

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

private (*bool*, *optional*) : Xác định xem kho được tạo có nên là riêng tư hay không. Nếu là *None* (mặc định), kho sẽ mặc định là công khai, trừ khi mặc định của tổ chức là riêng tư.

token (*str*, *optional*) : Token tài khoản Hugging Face để sử dụng làm xác thực HTTP bearer cho các tệp từ xa. Nếu là `None`, token sẽ được yêu cầu thông qua một lời nhắc.

config (*dict*, *optional*) : Đối tượng cấu hình để được lưu cùng với trọng số của mô hình.

branch (*str*, *optional*) : Nhánh git để đẩy mô hình lên. Mặc định là nhánh mặc định được chỉ định trong kho của bạn, mặc định là *"main"*.

create_pr (*boolean*, *optional*) : Có tạo Pull Request từ *branch* với commit đó hay không. Mặc định là *False*.

api_endpoint (*str*, *optional*) : Điểm cuối API (API endpoint) được sử dụng khi đẩy mô hình lên hub.

allow_patterns (*list[str]* hoặc *str*, *tùy chọn*) : Nếu được cung cấp, chỉ các tệp khớp với ít nhất một mẫu sẽ được đẩy lên.

ignore_patterns (*list[str]* hoặc *str*, *tùy chọn*) : Nếu được cung cấp, các tệp khớp với bất kỳ mẫu nào sẽ không được đẩy lên.

delete_patterns (*list[str]* hoặc *str*, *tuỳ chọn*) : Nếu được cung cấp, các tệp từ xa khớp với bất kỳ mẫu nào sẽ bị xoá khỏi kho.

**Trả về:**

URL của commit của mô hình của bạn trong kho lưu trữ đã cho.

Tải tệp checkpoint của learner lên Hub.

Sử dụng *allow_patterns* và *ignore_patterns* để lọc chính xác các tệp cần đẩy lên hub. Sử dụng *delete_patterns* để xóa các tệp từ xa hiện có trong cùng một commit. Xem tham chiếu [*upload_folder*] để biết thêm chi tiết.

> [!TIP]
> Gây ra lỗi sau:
>
> - [*ValueError*](https://docs.python.org/3/library/exceptions.html#ValueError) nếu người dùng không đăng nhập vào Hugging Face Hub.