Hub Python Library documentation
ミックスインとシリアライズメソッド
ミックスインとシリアライズメソッド
ミックスイン
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, 任意) — ModelHubMixin を統合するライブラリのライセンスの URL です。モデルカードの生成に使用されます。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 などです。
ANY機械学習フレームワークをHubに統合するための汎用的なミックスインです。
フレームワークを統合するには、モデルクラスがこのクラスを継承する必要があります。モデルの保存/読み込みに関するカスタムロジックは、_from_pretrainedおよび_save_pretrainedでオーバーライドする必要があります。PyTorchModelHubMixinは、Hubとのmixin統合の良い例です。詳細な手順については、統合ガイドをご覧ください。
ModelHubMixinを継承する場合、クラスレベルの属性を定義できます。これらの属性は__init__ではなく、クラス定義自体に渡されます。ModelHubMixinを統合するライブラリに関するメタデータを定義するのに便利です。
ライブラリへのmixin統合の詳細については、統合ガイドを参照してください。
例:
>>> 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 )
サブクラスでこのメソッドをオーバーライドして、モデルの保存方法を定義します。 手順については、統合ガイドを参照してください。
_from_pretrained
< source >( model_id: strrevision: str | Nonecache_dir: str | pathlib.Path | Noneforce_download: boollocal_files_only: booltoken: str | bool | None**model_kwargs )
パラメータ
- model_id (
str) — Huggingface Hub から読み込むモデルの ID (例:bigscience/bloom)。 - revision (
str, 任意) — Hub 上のモデルのリビジョンです。ブランチ名、git タグ、または任意のコミット ID を指定できます。デフォルトでは、mainブランチの最新のコミットが使用されます。 - force_download (
bool、省略可、デフォルトはFalse) — 既存のキャッシュを上書きして、Hub からモデルの重みと設定ファイルを強制的に(再)ダウンロードするかどうか。 - token (
strまたはbool、省略可能) — リモートファイルの HTTP ベアラ認証に使用するトークン。デフォルトでは、hf auth loginを実行した際にキャッシュされたトークンが使用されます。 - cache_dir (
str,Path, 省略可) — キャッシュされたファイルを保存するフォルダへのパス。 - local_files_only (
bool、任意、デフォルトはFalse) —Trueの場合、ファイルのダウンロードを回避し、ローカルにキャッシュされたファイルが存在する場合はそのパスを返します。 - model_kwargs — _from_pretrained() メソッドに渡される追加のキーワード引数。
サブクラスでこのメソッドをオーバーライドして、事前学習済みモデルからモデルを読み込む方法を定義します。
ファイルをロードする前に、hf_hub_download()またはsnapshot_download()を使用してHubからファイルをダウンロードします。入力として受け取るほとんどの引数は、これら2つのメソッドに直接渡すことができます。必要に応じて、PyTorchModelHubMixin._from_pretrained()などのメソッドに「model_kwargs」を使用して追加の引数を渡すことができます。例えば、PyTorchModelHubMixin._from_pretrained()は、モデルをロードするデバイスを設定するためのmap_locationパラメータを入力として受け取ります。
詳細な手順については、統合ガイドをご覧ください。
from_pretrained
< source >( pretrained_model_name_or_path: str | pathlib.Pathforce_download: bool = Falsetoken: str | bool | None = Nonecache_dir: str | pathlib.Path | None = Nonelocal_files_only: bool = Falserevision: str | None = None**model_kwargs )
パラメータ
- pretrained_model_name_or_path (
str,Path) —- Hub にホストされているモデルの
model_id（文字列）、例えばbigscience/bloomなど。 - または、save_pretrainedを使用してモデルの重みを保存した
directoryへのパス。例:../path/to/my_model_directory/。
- Hub にホストされているモデルの
- revision (
str, 任意) — Hub 上のモデルのリビジョンです。ブランチ名、git タグ、または任意のコミット ID を指定できます。 デフォルトでは、mainブランチの最新のコミットが使用されます。 - force_download (
bool、省略可、デフォルトはFalse) — 既存のキャッシュを上書きして、Hub からモデルの重みと設定ファイルを強制的に(再)ダウンロードするかどうか。 - token (
strまたはbool、省略可能) — リモートファイルの HTTP ベアラ認証に使用するトークン。デフォルトでは、hf auth loginを実行した際にキャッシュされたトークンが使用されます。 - cache_dir (
str,Path, 省略可) — キャッシュされたファイルを保存するフォルダへのパス。 - local_files_only (
bool、任意、デフォルトはFalse) —Trueの場合、ファイルのダウンロードを回避し、ローカルにキャッシュされたファイルが存在する場合はそのパスを返します。 - model_kwargs (
dict, 任意) — モデルの初期化時に渡す追加の kwargs。
Huggingface Hubからモデルをダウンロードして、インスタンス化します。
push_to_hub
< source >( repo_id: strconfig: dict | huggingface_hub.hub_mixin.DataclassInstance | None = Nonecommit_message: str = 'Push model using huggingface_hub.'private: bool | None = Nonetoken: str | None = Nonebranch: str | None = Nonecreate_pr: bool | None = Noneallow_patterns: list[str] | str | None = Noneignore_patterns: list[str] | str | None = Nonedelete_patterns: list[str] | str | None = Nonemodel_card_kwargs: dict[str, typing.Any] | None = None )
パラメータ
- repo_id (
str) — プッシュ先のリポジトリのID(例:"username/my-model")。 - config (
dictまたはDataclassInstance、省略可) — キー/値の辞書または dataclass インスタンスとして指定されたモデルの設定。 - commit_message (
str, 任意) — プッシュ時にコミットするメッセージ。 - private (
bool、省略可) — 作成するリポジトリをプライベートにするかどうか。None（デフォルト）の場合、組織のデフォルトがプライベートでない限り、リポジトリはパブリックになります。 - token (
str, 任意) — リモートファイルのHTTPベアラ認証に使用するトークン。デフォルトでは、hf auth loginの実行時にキャッシュされたトークンが使用されます。 - branch (
str, 任意) — モデルをプッシュする git ブランチです。デフォルト値は"main"です。 - create_pr (
boolean、省略可) — そのコミットを含むbranchからPull Requestを作成するかどうか。デフォルトはFalseです。 - allow_patterns (
list[str]またはstr、省略可) — 指定された場合、少なくとも1つのパターンに一致するファイルのみがプッシュされます。 - 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 | pathlib.Pathconfig: dict | huggingface_hub.hub_mixin.DataclassInstance | None = Nonerepo_id: str | None = Nonepush_to_hub: bool = Falsemodel_card_kwargs: dict[str, typing.Any] | None = None**push_to_hub_kwargs ) → str or None
パラメータ
- save_directory (
strまたはPath) — モデルの重みと設定を保存するディレクトリのパス。 - config (
dictまたはDataclassInstance、省略可) — キー/値の辞書または dataclass インスタンスとして指定されたモデルの設定。 - push_to_hub (
bool、任意、デフォルトはFalse) — モデルを保存した後、Huggingface Hub にプッシュするかどうかを指定します。 - repo_id (
str, 省略可) — Hub 上のリポジトリの ID。push_to_hub=Trueの場合のみ使用されます。指定しない場合、フォルダ名がデフォルトとして使用されます。 - model_card_kwargs (
dict[str, Any]、省略可) — モデルカードのテンプレートに渡され、モデルカードをカスタマイズするための追加引数です。 - push_to_hub_kwargs — push_to_hub() メソッドに渡される追加のキーワード引数。
戻り値
str または None
push_to_hub=True の場合、Hub 上のコミットの URL。それ以外の場合は None。
重みをローカルディレクトリに保存します。
PyTorch
PyTorchモデルにモデルハブのアップロード/ダウンロード機能を提供するためのModelHubMixinの実装です。モデルはデフォルトで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
256Fastai
huggingface_hub.from_pretrained_fastai
< source >( repo_id: strrevision: str | None = None )
パラメータ
- repo_id (
str) — ピクルス化された fastai.Learner の場所です。以下のいずれかになります:- Hugging Face Hub にホストされています。例: ‘espejelomar/fatai-pet-breeds-classification’ または ‘distilgpt2’。
repo_idの末尾に@を追加することで、revisionを指定できます。例:dbmdz/bert-base-german-cased@main。 Revision は使用する特定のモデルのバージョンです。Hugging Face Hub ではモデルやその他の成果物を保存するために git ベースのシステムを使用しているため、ブランチ名、タグ名、またはコミット ID を指定できます。 - ローカルにホストされています。
repo_idは、pickleと、fastai.Learnerの構築に使用されたfastaiおよびfastcoreのバージョンを示すpyproject.tomlを含むディレクトリになります。例:./my_model_directory/。
- Hugging Face Hub にホストされています。例: ‘espejelomar/fatai-pet-breeds-classification’ または ‘distilgpt2’。
- revision (
str, 任意) — リポジトリのファイルをダウンロードするリビジョン。snapshot_downloadのドキュメントを参照してください。
Hubまたはローカルディレクトリから事前学習済みのfastaiモデルを読み込みます。
huggingface_hub.push_to_hub_fastai
< source >( learnerrepo_id: strcommit_message: str = 'Push FastAI model using huggingface_hub.'private: bool | None = Nonetoken: str | None = Noneconfig: dict | None = Nonebranch: str | None = Nonecreate_pr: bool | None = Noneallow_patterns: list[str] | str | None = Noneignore_patterns: list[str] | str | None = Nonedelete_patterns: list[str] | str | None = Noneapi_endpoint: str | None = None )
パラメータ
- learner (Learner) — Hub にプッシュしたい *fastai.Learner’
- repo_id (str) — Hub 上のモデルのリポジトリ ID。「namespace/repo_name」の形式です。namespace は、書き込みアクセス権を持つ個人アカウントまたは組織を指定します（例: ‘stanfordnlp/stanza-de’）。
- commit_message (str`, 任意*) — push 時にコミットするメッセージ。デフォルトは
"add model"です。 - private (bool, optional) — 作成するリポジトリをプライベートにするかどうかを指定します。 None（デフォルト）の場合、組織のデフォルトがプライベートでない限り、パブリックになります。
- token (str, optional) —
リモートファイルの HTTP ベアラ認証に使用する Hugging Face アカウントのトークンです。
Noneの場合、プロンプトでトークンの入力を求められます。 - config (dict、任意) — モデルの重みとともに保存される設定オブジェクト。
- branch (str, optional) — モデルをプッシュする git ブランチです。デフォルトでは、リポジトリで指定されたデフォルトブランチが使用され、それがデフォルトで “main” になります。
- create_pr (boolean、任意) — そのコミットを含む branch から Pull Request を作成するかどうか。 デフォルトは False です。
- api_endpoint (str, optional) — モデルをハブにプッシュする際に使用する API エンドポイント。
- allow_patterns (list[str] または str、任意) — 指定された場合、少なくとも1つのパターンに一致するファイルのみがプッシュされます。
- ignore_patterns (list[str] または str、任意) — 指定された場合、いずれかのパターンに一致するファイルはプッシュされません。
- delete_patterns (list[str] または str、任意) — 指定された場合、いずれかのパターンに一致するリモートファイルがリポジトリから削除されます。
学習者チェックポイントファイルをHubにアップロードします。
allow_patterns と ignore_patterns を使用して、ハブにプッシュするファイルを正確にフィルタリングできます。既存のリモートファイルを同じコミットで削除するには、delete_patterns を使用します。詳細については、[upload_folder] のリファレンスを参照してください。
次のエラーを発生させます:
- ユーザーが Hugging Face Hub にログインしていない場合、ValueError が発生します。