リポジトリの入門

この初心者向けのガイドでは、Hub上でリポジトリを作成・管理するために必要な基本的なスキルを身につけるお手伝いをします。各セクションは前のセクションの内容を前提として進められているため、どこから始めるかは自由です！

要件

このドキュメントでは、Webインターフェースおよびターミナルを介してリポジトリを扱う方法を示します。UIで作業する場合は、特別な要件はありません。ターミナルで作業する場合は、これらのインストール手順に従ってください。

CLI コマンドとして git がまだ利用できない場合は、お使いのプラットフォーム用に Git をインストール する必要があります。また、画像やモデルの重みなどの大きなファイルを処理するために使用される Git-Xet もインストールする必要があります。

Gitから大規模なファイルをダウンロードおよびアップロードするには、Git Xet拡張機能をインストールする必要があります。

Hubにコードをプッシュするには、何らかの方法で認証する必要があります。最も簡単な方法は、hf CLIをインストールしてログインコマンドを実行することです:

# Install hf:
#   brew install hf
#   or
#   pip install hf
hf auth login

このドキュメントのGetting Startedセクションの内容は、動画でもご覧いただけます！

リポジトリの作成

HubのWebインターフェースを使用すると、リポジトリの作成、ファイルの追加（大きなファイルでも！）、モデルの探索、差分の可視化など、さまざまな操作を簡単に実行できます。Hubには3種類のリポジトリがあり、このガイドではデモ目的でモデルリポジトリを作成します。モデル、データセット、Spacesの作成および管理に関する情報は、それぞれのドキュメントを参照してください。

1. 新しいリポジトリを作成するには、huggingface.co/newにアクセスします:

2. リポジトリの所有者を指定します。これは、あなた自身または所属している組織のいずれかです。

3. モデル名を入力してください。これがリポジトリの名前にもなります。

4. モデルを公開にするか非公開にするかを指定します。

5. ライセンスを指定します。Licenseフィールドは、当面は空欄のままにしておいてください。ライセンスについて詳しく知るには、Licensesドキュメントをご覧ください。

モデルリポジトリを作成した後、次のようなページが表示されるはずです:

HubではModel Cardの作成を促されますが、その詳細はModel Cardsのドキュメントで確認できます。モデルリポジトリにModel Cardを含めることがベストプラクティスですが、ここではテスト用のリポジトリを作成しているだけなので、この手順をスキップできます。

リポジトリにファイルを追加する（Web UI）

Web UIからリポジトリにファイルを追加するには、まずFilesタブを選択し、対象のディレクトリに移動してから、Add fileをクリックします。新規ファイルの作成と、コンピューターから直接ファイルをアップロードする、という2つのオプションが提示されます。

新しいファイルの作成

新しいファイルの作成を選択すると、次のエディタ画面に移動します。ここでは、ファイル名を選択し、コンテンツを追加し、変更内容を要約するメッセージを付けてファイルを保存できます。新しいファイルをリポジトリのmainブランチに直接コミットする代わりに、Open as a pull requestを選択してPull Requestを作成することもできます。

ファイルのアップロード

Upload file を選択すると、リポジトリへの変更内容を要約するメッセージとともに、アップロードするローカルファイルを選択できます。

新しいファイルを作成する場合と同様に、Open as a pull request を選択して、リポジトリの main ブランチに直接変更を追加する代わりに Pull Request を作成することもできます。

リポジトリにファイルを追加する（CLI）

hf CLI を使用して、ターミナルからリポジトリにファイルを直接アップロードできます。ローカルファイルやフォルダ全体をプッシュするには、hf upload コマンドを使用します。

# Upload a single file to your model repo
hf upload your-username/your-model-name model.safetensors

# Upload an entire directory
hf upload your-username/your-model-name ./my-model-directory

# Upload to a dataset repo
hf upload your-username/your-dataset-name ./data --repo-type dataset

hf CLI は大きなファイルを自動的に処理します。追加のセットアップは不要です。

リポジトリにファイルを追加する（git）

リポジトリのクローン

リポジトリをローカルマシンにダウンロードすることをクローンと呼びます。以下のコマンドを使用して、リポジトリを読み込み、そのディレクトリに移動できます。

git clone https://huggingface.co/<your-username>/<your-model-name>
cd <your-model-name>

または、データセットのリポジトリの場合:

git clone https://huggingface.co/datasets/<your-username>/<your-dataset-name>
cd <your-dataset-name>

以下のコマンドで、SSH経由でクローンできます。

git clone git@hf.co:<your-username>/<your-model-name>
cd <your-model-name>

変更をプッシュしたり、プライベートリポジトリにアクセスするには、ユーザー設定にSSH公開鍵を追加する必要があります。

セットアップ

今こそ、リポジトリに任意のファイルを追加できるタイミングです！🔥

10MBを超えるファイルがありますか？そのようなファイルは、git-xetで管理する必要があります。以下のコマンドで初期化できます。

git xet install

Hugging Face でリポジトリを作成すると、Hugging Face は .gitattributes ファイルに、一般的な機械学習の大きなファイルの拡張子の一覧を自動的に提供します。git-xet はこのファイルを使用して、大きなファイルの変更を効率的に追跡します。ただし、ファイルの種類がまだ処理されていない場合は、新しい拡張子を追加する必要がある場合があります。git xet track "*.your_extension" を使用してこれを行うことができます。

ファイルのプッシュ

Git を使用して、新規ファイルや既存ファイルの変更を、プロジェクトの「リビジョン」と考えられる変更のバンドルである commit として保存できます。commit を作成するには、まず変更を保存する予定であることを Git に伝えるためにファイルを add し、その後、これらの変更を commit します。新しい commit を Hugging Face Hub と同期するには、commit を Hub に push します。

# Create any files you like! Then...
git add .
git commit -m "First model version"  # You can choose any descriptive message
git push

これで完了です! Hugging Face上で、最近追加されたファイルを含むリポジトリを確認できます。例えば、下のスクリーンショットでは、ユーザーが複数のファイルを追加しています。この例では、一部のファイルのサイズが1.04 GBであるため、リポジトリはXetを使用して追跡しています。

リポジトリをHTTPでクローンした場合、プッシュ操作のたびにユーザー名とパスワードの入力を求められることがあります。この繰り返しを避ける最も簡単な方法は、HTTPではなくSSHに切り替えることです。あるいは、HTTPを使用しなければならない場合は、ユーザー名とパスワードを自動入力するためのgit credential helperを設定すると便利です。

リポジトリの履歴を表示する

add-commit-pushサイクルを毎回実行すると、リポジトリはファイルに行ったすべての変更を追跡します。UIでは、モデルファイルとコミットを閲覧し、各コミットによって導入された差分（diffとも呼ばれます）を確認できます。履歴を表示するには、History: X commitsリンクをクリックしてください。

個々のコミットをクリックすると、そのコミットで導入された変更を確認できます: