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

lớp huggingface_hub.ModelHubMixin

< source >

( *args**kwargs )

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 về thư viện. Được dùng để tạo model card.
docs_url (str, tùy chọn) — URL của tài liệu thư viện. Được dùng để tạo model card.
model_card_template (str, tùy chọn) — Mẫu của model card. Được sử dụng để tạo model card. 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 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 trỏ đến giấy phép của thư viện tích hợp ModelHubMixin. Được dùng để tạo model card. Chỉ được sử dụng nếu 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 dùng để tạo model card. Ví dụ: “text-classification”.
tags (list[str], tùy chọn) — Các thẻ cần thêm vào model card. Được dùng để tạo model card. Ví dụ: [“computer-vision”]
coders (dict[Type, tuple[Callable, Callable]], tuỳ 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 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 của chúng tôi để biết thêm chi tiết.

Khi kế thừa từ 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.

Để 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.

Ví dụ:

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

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 của chúng tôi để biết các bước thực hiện.

_from_pretrained

< source >

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, thẻ git hoặc bất kỳ id commit 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) trọng số mô hình và các 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 xác thực HTTP bearer cho các tệp từ xa. Mặc định, nó sẽ sử dụng token được lưu đệm khi chạy hf auth login.
cache_dir (str, Path, tùy chọn) — Đường dẫn đến thư mục 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().

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() hoặc 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 của chúng tôi để biết thêm chi tiết.

from_pretrained

< source >

Tham số

pretrained_model_name_or_path (str, Path) —
- Hoặc model_id (chuỗi) của một mô hình được lưu trữ trên Hub, ví dụ bigscience/bloom.
- Hoặc một đường dẫn đến directory chứa trọng số mô hình đượ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, thẻ git hoặc bất kỳ id commit 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) trọng số mô hình và các 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 xác thực HTTP bearer cho các tệp từ xa. Mặc định, nó sẽ sử dụng token được lưu đệm khi chạy hf auth login.
cache_dir (str, Path, tùy chọn) — Đường dẫn đến thư mục 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

< source >

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 báo để commit khi đẩy lên.
private (bool, tuỳ chọn) — Xác định xem kho được tạo có nên là kho 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 trong danh sách 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 trong danh sách 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.

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() để biết thêm chi tiết.

save_pretrained

< source >

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

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

lớp huggingface_hub.PyTorchModelHubMixin

< source >

( *args**kwargs )

Cài đặt 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 mặc định được đặt ở chế độ đánh giá 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ó về chế độ huấn luyện bằng model.train().

Xem ModelHubMixin để biết thêm chi tiết về cách sử dụng mixin.

Ví dụ:

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

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 tôi sử dụng hệ thống dựa trên git để lưu trữ các 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 thẻ hoặc id commit.
- Được lưu trữ cục bộ. repo_id sẽ là một 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 tại đó các tệp của kho được tải xuống. Xem tài liệu của snapshot_download.

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

< source >

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 mô hình 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`, không bắt buộc*) — Thông báo để commit khi đẩy. Mặc định là "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), 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 của tài khoản Hugging Face để sử dụng làm HTTP bearer authorization 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, tùy chọn) — 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 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 trong danh sách sẽ bị xóa khỏi kho.

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.

Gây ra lỗi sau:

ValueError nếu người dùng không đăng nhập vào Hugging Face Hub.

Update on GitHub

Hub Python Library

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

Mixins

Tổng quát

lớp huggingface_hub.ModelHubMixin

_save_pretrained

_from_pretrained

from_pretrained

push_to_hub

save_pretrained

PyTorch

lớp huggingface_hub.PyTorchModelHubMixin

Fastai

huggingface_hub.from_pretrained_fastai

huggingface_hub.push_to_hub_fastai