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

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

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

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

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

開始する前に、リポジトリとファイルを管理できる[Hugging Face アカウント](https://huggingface.co/join)の作成をお勧めします。

統合に関するご支援が必要な場合は、[issue](https://github.com/huggingface/huggingface_hub/issues/new/choose)を作成してください。喜んでお手伝いいたします。

## 実装

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

### インストール

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

```bash
pip install huggingface_hub
```

`huggingface_hub` のインストールに関する詳細については、[このガイド](https://huggingface.co/docs/huggingface_hub/installation)を参照してください。

> [!TIP]
> このガイドでは、Pythonライブラリに焦点を当てます。JavaScriptでライブラリを実装した場合は、代わりに[`@huggingface/hub`](https://www.npmjs.com/package/@huggingface/hub)を使用できます。残りのロジック（ファイルのホスティング、コードサンプルなど）は、コードの言語に依存しません。
>
> ```
> npm add @huggingface/hub
> ```

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

```
hf auth login
```

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

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

```py
from huggingface_hub import login
login()
```

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

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

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

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

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

```python
>>> 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`](https://huggingface.co/docs/huggingface_hub/main/en/package_reference/file_download#huggingface_hub.snapshot_download)を使用してください。これにより、すべてのファイルが並列でダウンロードされます。戻り値は、ダウンロードされたファイルを含むディレクトリへのパスです。

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

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

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

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

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

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

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

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

[`upload_file`](https://huggingface.co/docs/huggingface_hub/en/package_reference/hf_api#huggingface_hub.HfApi.upload_file) メソッドは、ファイルを Hub にアップロードします。このメソッドには、以下が必要です:

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

例えば:

```python
>>> 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`](https://huggingface.co/docs/huggingface_hub/en/package_reference/hf_api#huggingface_hub.HfApi.upload_folder)を使用して実行できます。

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

ファイルのアップロード方法の詳細については、[アップロードガイド](https://huggingface.co/docs/huggingface_hub/en/guides/upload)を参照してください。

## モデルカード

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

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

## ライブラリを登録する

お見事です! これで、Hubからモデルを読み込み、最終的には新しいモデルをプッシュできるライブラリが完成しました。次のステップは、Hub上のモデルが適切にドキュメント化され、プラットフォームと統合されていることを確認することです。そのために、ライブラリをHubに登録できます。これにより、ユーザーにはいくつかの利点があります:
- モデルページに、より見やすいラベルを表示できます（例: `keras-nlp` ではなく `KerasNLP` など）。
- 各モデルページに、ライブラリのリポジトリとドキュメントへのリンクが追加されます
- カスタムのダウンロード数ルールを定義できます
- code snippetsを生成して、ライブラリを使用してモデルを読み込む方法を示すことができます

新しいライブラリを登録するには、以下の手順に従って、[こちら](https://github.com/huggingface/huggingface.js/blob/main/packages/tasks/src/model-libraries.ts)から 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`、[こちら](https://huggingface.co/docs/hub/models-download-stats#which-are-the-query-files-for-different-libraries)を参照)のいずれかを使用している場合、ダウンロードカウントルールを手動で定義する必要はありません。
- （任意）`snippets` を定義して、ユーザーがモデルを素早くインスタンス化する方法を伝えます。詳細は以下を参照してください。

PR を作成する前に、https://huggingface.co/models?other=my-library-name に少なくとも 1 つのモデルが参照されていることを確認してください。参照されていない場合は、該当するモデルのモデルカードのメタデータを `library_name: my-library-name` に更新する必要があります（[例](https://huggingface.co/google/gemma-scope/blob/main/README.md?code=true#L3)を参照）。Hub 上のモデルの所有者でない場合は、PR を作成してください（[例](https://huggingface.co/MCG-NJU/VFIMamba/discussions/1)を参照）。

VFIMambaの統合を追加する最小限の[例](https://github.com/huggingface/huggingface.js/pull/885/files)を以下に示します。

### コードスニペット

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

コードスニペットを追加するには、[model-libraries-snippets.ts](https://github.com/huggingface/huggingface.js/blob/main/packages/tasks/src/model-libraries-snippets.ts) ファイルをモデルの指示で更新する必要があります。例えば、[Asteroid](https://huggingface.co/asteroid-team) 統合には、Asteroid モデルを読み込んで使用する方法を示す簡潔なコードスニペットが含まれています。

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

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

スニペットが[model-libraries-snippets.ts](https://github.com/huggingface/huggingface.js/blob/main/packages/tasks/src/model-libraries-snippets.ts)に追加されたら、上記の手順に従って[model-libraries.ts](https://github.com/huggingface/huggingface.js/blob/main/packages/tasks/src/model-libraries.ts)内で参照できます。

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

最後に、ライブラリを Hub のドキュメントに追加できます。例えば、[SetFit](./setfit)をドキュメントに追加した[Setfit PR](https://github.com/huggingface/hub-docs/pull/1150)を参照してください。