ライブラリをHubに統合する

Hugging Face Hubは、機械学習モデル、チェックポイント、成果物の共有を促進することを目的としています。この取り組みには、コミュニティの多くの優れたサードパーティ製ライブラリへのHubの統合が含まれます。すでに統合されているものには、spaCy、Sentence Transformers、OpenCLIP、timmなど、多数のライブラリがあります。統合により、ユーザーはライブラリから直接Hubにファイルをダウンロードおよびアップロードできるようになります。皆様のライブラリも統合し、すべての人々のための人工知能の民主化に一緒に取り組んでいただければ幸いです。

Hubをライブラリに統合することには、以下のような多くの利点があります。

• あなたとあなたのユーザーのための無料モデルホスティング。
• 巨大なファイルにも対応する、Git-Xetによる組み込みのファイルバージョン管理。
• コミュニティ機能（ディスカッション、プルリクエスト、いいね）。
• あなたのライブラリで実行されたすべてのモデルの使用状況メトリクス。

このチュートリアルでは、Hubをライブラリに統合する方法を説明します。これにより、ユーザーはHubが提供するすべての機能を利用できるようになります。

開始する前に、リポジトリとファイルを管理できるHugging Face アカウントの作成をお勧めします。

統合に関するご支援が必要な場合は、issueを作成してください。喜んでお手伝いいたします。

実装

ライブラリを Hub に統合するには、通常、Hub からモデルを読み込むための組み込みメソッドを提供し、ユーザーが新しいモデルを Hub にプッシュできるようにする必要があります。このセクションでは、huggingface_hub ライブラリを使用してこれを行う基本的な方法について説明します。より詳細なガイダンスについては、このガイドを参照してください。

インストール

ライブラリをHubに統合するには、huggingface_hubライブラリを依存関係として追加する必要があります:

pip install huggingface_hub

huggingface_hub のインストールに関する詳細については、このガイドを参照してください。

このガイドでは、Pythonライブラリに焦点を当てます。JavaScriptでライブラリを実装した場合は、代わりに@huggingface/hubを使用できます。残りのロジック（ファイルのホスティング、コードサンプルなど）は、コードの言語に依存しません。

コピーしました

npm add @huggingface/hub

huggingface_hub ライブラリを正常にインストールした後、ユーザーは認証を行う必要があります。最も簡単な認証方法は、トークンをマシンに保存することです。ユーザーはターミナルでlogin()コマンドを使用して、これを行うことができます。

hf auth login

このコマンドは、ユーザーがすでにログインしているかどうかを通知し、トークンの入力を促します。その後、トークンは検証され、HF_HOME ディレクトリ（デフォルトは ~/.cache/huggingface/token）に保存されます。Hub とやり取りするスクリプトやライブラリは、リクエストを送信する際にこのトークンを使用します。

代わりに、ノートブックやスクリプト内でlogin()をプログラム的に使用してログインすることもできます。

from huggingface_hub import login
login()

Hub上のパブリックリポジトリからファイルをダウンロードする際、認証は任意です。

Hubからファイルをダウンロード

Integrationsにより、ユーザーはHubからモデルをダウンロードし、あなたのライブラリから直接インスタンス化できます。これは通常、あなたのライブラリに固有のメソッド（一般的にはfrom_pretrainedまたはload_from_hfと呼ばれる）を提供することで実現されます。Hubからモデルをインスタンス化するには、あなたのライブラリは以下を行う必要があります：

• Hubからファイルをダウンロードします。ここではこれを説明します。
• これらのファイルからPythonモデルをインスタンス化します。

hf_hub_download メソッドを使用して、Hub 上のリポジトリからファイルをダウンロードします。ダウンロードされたファイルはキャッシュ ~/.cache/huggingface/hub に保存されます。次回以降、ユーザーがそのファイルを使用する際に再ダウンロードする必要がないため、大規模なファイルでは多くの時間を節約できます。さらに、リポジトリがファイルの新しいバージョンで更新された場合、huggingface_hub は自動的に最新バージョンをダウンロードしてキャッシュに保存します。ユーザーはファイルの手動更新を心配する必要はありません。

例えば、lysandre/arxiv-nlp リポジトリからconfig.jsonファイルをダウンロードします:

>>> from huggingface_hub import hf_hub_download
>>> config_path = hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json")
>>> config_path
'/home/lysandre/.cache/huggingface/hub/models--lysandre--arxiv-nlp/snapshots/894a9adde21d9a3e3843e6d5aeaaf01875c7fade/config.json'

config_pathには、ダウンロードされたファイルへのパスが含まれています。ファイルが存在し、最新の状態であることが保証されています。

ライブラリでリポジトリ全体をダウンロードする必要がある場合は、snapshot_downloadを使用してください。これにより、すべてのファイルが並列でダウンロードされます。戻り値は、ダウンロードされたファイルを含むディレクトリへのパスです。

>>> from huggingface_hub import snapshot_download
>>> snapshot_download(repo_id="lysandre/arxiv-nlp")
'/home/lysandre/.cache/huggingface/hub/models--lysandre--arxiv-nlp/snapshots/894a9adde21d9a3e3843e6d5aeaaf01875c7fade'

特定のリビジョンからファイルをダウンロードする、ダウンロードするファイルをフィルタリングする、カスタムキャッシュディレクトリを指定する、ローカルディレクトリにダウンロードする、など、多くのオプションが用意されています。詳細については、ダウンロードガイドを参照してください。

ファイルをHubにアップロードする

ユーザーが独自のモデルをHubにプッシュできるようにするメソッドも提供するとよいでしょう。これにより、コミュニティがあなたのライブラリと互換性のあるモデルのエコシステムを構築できるようになります。huggingface_hubライブラリには、リポジトリの作成やファイルのアップロードを行うメソッドが提供されています:

• create_repo は、Hub にリポジトリを作成します。
• upload_file と upload_folder は、ファイルを Hub 上のリポジトリにアップロードします。

create_repo メソッドは、Hub にリポジトリを作成します。リポジトリの名前を指定するには、repo_id パラメータを使用します:

>>> from huggingface_hub import create_repo
>>> create_repo(repo_id="test-model")
'https://huggingface.co/lysandre/test-model'

Hugging Face のアカウントを確認すると、名前空間の下に test-model リポジトリが表示されているはずです。

upload_file メソッドは、ファイルを Hub にアップロードします。このメソッドには、以下が必要です:

• アップロードするファイルへのパス。
• リポジトリ内の最終パス。
• ファイルをプッシュする対象のリポジトリ。

例えば:

>>> from huggingface_hub import upload_file
>>> upload_file(
...    path_or_fileobj="/home/lysandre/dummy-test/README.md", 
...    path_in_repo="README.md", 
...    repo_id="lysandre/test-model"
... )
'https://huggingface.co/lysandre/test-model/blob/main/README.md'

Hugging Face のアカウントを確認すると、リポジトリ内にファイルが表示されるはずです。

通常、ライブラリはモデルをローカルディレクトリにシリアライズし、その後、Hubにフォルダ全体を一度にアップロードします。これはupload_folderを使用して実行できます。

>>> from huggingface_hub import upload_folder
>>> upload_folder(
...     folder_path="/home/lysandre/dummy-test",
...     repo_id="lysandre/test-model",
... )

ファイルのアップロード方法の詳細については、アップロードガイドを参照してください。

モデルカード

モデルカードは、モデルに付随するファイルで、便利な情報を提供します。内部構造としては、追加のメタデータを持つシンプルなMarkdownファイルです。モデルカードは、発見可能性、再現性、共有のために不可欠です。モデルカードは、どのモデルリポジトリでもREADME.mdファイルとして確認できます。優れたモデルカードの作成方法の詳細については、モデルカードのガイドを参照してください。

ライブラリがモデルを Hub にプッシュすることを許可している場合、事前入力されたメタデータ（通常は library_name、pipeline_tag または tags）と、モデルの学習方法に関する情報を含む最小限のモデルカードを生成することをお勧めします。これにより、あなたのライブラリで構築されたすべてのモデルに標準化された説明を付与できます。

ライブラリを登録する

お見事です! これで、Hubからモデルを読み込み、最終的には新しいモデルをプッシュできるライブラリが完成しました。次のステップは、Hub上のモデルが適切にドキュメント化され、プラットフォームと統合されていることを確認することです。そのために、ライブラリをHubに登録できます。これにより、ユーザーにはいくつかの利点があります:

• モデルページに、より見やすいラベルを表示できます（例: keras-nlp ではなく KerasNLP など）。
• 各モデルページに、ライブラリのリポジトリとドキュメントへのリンクが追加されます
• カスタムのダウンロード数ルールを定義できます
• code snippetsを生成して、ライブラリを使用してモデルを読み込む方法を示すことができます

新しいライブラリを登録するには、以下の手順に従って、こちらから Pull Request を作成してください。

• ライブラリ ID は小文字とハイフン区切りで指定する必要があります（例: "adapter-transformers"）。PR を作成する際は、アルファベット順が保たれていることを確認してください。
• repoName と prettyLabel を、ユーザーフレンドリーな大文字小文字の表記で設定します(例: DeepForest)。
• repoUrl に、ライブラリのソースコードへのリンク（通常は GitHub リポジトリ）を設定します。
• （任意）ライブラリのドキュメントへのリンクをdocsUrlに設定します。上記で参照した GitHub リポジトリにドキュメントが含まれている場合は、2回設定する必要はありません。
• filterをfalseに設定します。
• （任意）countDownload を設定して、ダウンロードの集計方法を定義します。ダウンロードは、ファイル拡張子またはファイル名で追跡できます。集計の重複に注意してください。例えば、モデルの読み込みに 3 つのファイルが必要な場合、ダウンロードカウントのルールは、その 3 つのファイルのうち 1 つのダウンロードのみをカウントするように設定する必要があります。そうしないと、ダウンロード数が過大評価されてしまいます。注: ライブラリがデフォルトの構成ファイル（config.json、config.yaml、hyperparams.yaml、params.json、meta.yaml、こちらを参照）のいずれかを使用している場合、ダウンロードカウントのルールを手動で定義する必要はありません。
• （任意）snippets を定義して、ユーザーがモデルを素早くインスタンス化する方法を伝えます。詳細は以下を参照してください。

PR を作成する前に、https://huggingface.co/models?other=my-library-name に少なくとも 1 つのモデルが参照されていることを確認してください。参照されていない場合は、該当するモデルのモデルカードのメタデータを library_name: my-library-name に更新する必要があります（例を参照）。Hub 上のモデルの所有者でない場合は、PR を作成してください（例を参照）。

VFIMambaの統合を追加する最小限の例を以下に示します。

コードスニペット

下流のライブラリでモデルを使用する方法を説明するために、コードスニペットを追加することをお勧めします。

コードスニペットを追加するには、model-libraries-snippets.ts ファイルをモデルの指示で更新する必要があります。例えば、Asteroid 統合には、Asteroid モデルを読み込んで使用する方法を示す簡潔なコードスニペットが含まれています。

const asteroid = (model: ModelData) =>
`from asteroid.models import BaseModel
  
model = BaseModel.from_pretrained("${model.id}")`;

これを行うと、モデルにタグが追加され、ユーザーがライブラリのモデルを素早く識別できるようになります。

スニペットがmodel-libraries-snippets.tsに追加されたら、上記の手順に従ってmodel-libraries.ts内で参照できます。

ライブラリのドキュメント作成

最後に、ライブラリを Hub のドキュメントに追加できます。例えば、SetFitをドキュメントに追加したSetfit PRを参照してください。