Hugging Face's logo

Hub Python Library documentation

リポジトリの作成と管理

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v2.4.0).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

リポジトリの作成と管理

Hugging Face Hubはgitリポジトリのコレクションです。Gitは、協働作業時にプロジェクトのバージョン管理を容易に行うためにソフトウェア開発で広く使用されているツールです。このガイドでは、Hub上のリポジトリとの操作方法、特に以下の点について説明します。

  • リポジトリの作成と削除
  • ブランチとタグを管理します。
  • リポジトリの名前を変更します。
  • リポジトリの公開範囲を更新します。
  • リポジトリのローカルコピーを管理します。

GitLab/GitHub/Bitbucketなどのプラットフォームでの作業に慣れている場合、まずgit CLIを使用してリポジトリをクローン（git clone）し、変更をコミット（git add, git commit）してプッシュ（git push）しようとするのが自然な反応かもしれません。Hugging Face Hubを使用する場合は、この方法も有効です。ただし、ソフトウェアエンジニアリングと機械学習では、要件やワークフローが同じではありません。モデルリポジトリには、異なるフレームワークやツール用の大きなモデル重みファイルが含まれていることがあり、リポジトリをクローンすると、巨大なサイズの大きなローカルフォルダを管理することになります。そのため、独自のHTTPメソッドを使用する方が効率的な場合があります。詳細については、GitとHTTPのパラダイムの説明ページをご覧ください。

Hub上でリポジトリの作成と管理を行うには、お使いのマシンがログイン状態である必要があります。ログインしていない場合は、このセクションを参照してください。本ガイドの残りの部分では、お使いのマシンがログイン状態であることを前提とします。

リポジトリをリスト表示する

list_user_repos() を使用して、アカウントまたは組織のすべてのリポジトリ（モデル、データセット、スペース、バケット）をリスト表示できます。結果にはストレージ情報が含まれ、ストレージ使用量でソートされます。

>>> from huggingface_hub import list_user_repos

# List repos for the authenticated user
>>> repos = list(list_user_repos())
>>> for repo in repos[:3]:
...     print(f"{repo.id} ({repo.type}) - {repo.storage} bytes")
username/my-model (model) - 4828692480 bytes
username/my-dataset (dataset) - 598427559 bytes
username/my-space (space) - 120620146 bytes

# List repos from an organization
>>> repos = list(list_user_repos(namespace="my-org"))

またはCLI経由（デフォルトでは30リポジトリが表示されます。すべてを表示するには--limit 0を使用します）:

>>> hf repos ls
>>> hf repos ls --namespace my-org --type model
>>> hf repos ls --limit 0 --format json | jq '.[].id'

リポジトリの作成と削除

最初のステップは、リポジトリの作成と削除の方法を知ることです。管理できるのは、自分が所有しているリポジトリ（ユーザー名ネームスペース配下）または、書き込み権限を持つ組織のリポジトリのみです。

リポジトリを作成する

create_repo() を使用して空のリポジトリを作成し、repo_id パラメータで名前を指定します。repo_id は、名前空間にリポジトリ名を続けた形式です: username_or_org/repo_name。

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

または、CLI経由で:

>>> hf repos create lysandre/test-model
Successfully created lysandre/test-model on the Hub.
Your repo is now available at https://huggingface.co/lysandre/test-model

デフォルトでは、create_repo() はモデルのリポジトリを作成します。ただし、repo_type パラメータを使用して、別のリポジトリタイプを指定できます。例えば、データセットのリポジトリを作成したい場合は:

>>> from huggingface_hub import create_repo
>>> create_repo("lysandre/test-dataset", repo_type="dataset")
'https://huggingface.co/datasets/lysandre/test-dataset'

または、CLI経由で:

>>> hf repos create lysandre/test-dataset --repo-type dataset

リポジトリを作成する際、visibility パラメータでリポジトリの公開範囲を設定できます。

>>> from huggingface_hub import create_repo
>>> create_repo("lysandre/test-private", visibility="private")

または、CLI経由で:

>>> hf repos create lysandre/test-private --private

リポジトリの公開設定を後から変更したい場合は、update_repo_settings()関数を使用できます。

Enterprise プランの組織に属している場合、create_repo() に resource_group_id をパラメータとして渡すことで、特定のリソースグループ内にリポジトリを作成できます。リソースグループは、組織のどのメンバーが特定のリソースにアクセスできるかを制御するためのセキュリティ機能です。リソースグループの ID は、Hub 上の組織設定ページの URL からコピーすることで取得できます（例: "https://huggingface.co/organizations/huggingface/settings/resource-groups/66670e5163145ca562cb1988" => "66670e5163145ca562cb1988"）。リソースグループの詳細については、このガイドを参照してください。

region をパラメータとして渡すことで、特定のクラウドリージョンにリポジトリを作成することもできます。

>>> from huggingface_hub import create_repo
>>> create_repo("lysandre/test-model", region="us")

リポジトリの削除

delete_repo() を使用してリポジトリを削除できます。この操作は元に戻せないため、リポジトリの削除を本当に希望していることを確認してください。

削除するリポジトリのrepo_idを指定します:

>>> delete_repo(repo_id="lysandre/my-corrupted-dataset", repo_type="dataset")

リポジトリが存在しない場合に呼び出しを無視するには、missing_ok=True を渡します:

>>> delete_repo(repo_id="lysandre/my-corrupted-dataset", repo_type="dataset", missing_ok=True)

または、CLI経由で:

>>> hf repos delete lysandre/my-corrupted-dataset --repo-type dataset

リポジトリの複製

一部のケースでは、他のユーザーのリポジトリをコピーして、自分のユースケースに合わせて調整したい場合があります。 これはduplicate_repo()メソッドを使用することで可能です。リポジトリ全体が複製され、gitの履歴が完全に保持されます。 この機能は、モデル、データセット、Spacesで動作します。Spacesの場合、ハードウェア、スリープ時間、ストレージ、変数とシークレットなどの設定を自分で行う必要があります。詳細については、Spaceの管理ガイドをご覧ください。

>>> from huggingface_hub import duplicate_repo

# Duplicate a Space
>>> duplicate_repo("multimodalart/dreambooth-training", repo_type="space", private=False)
RepoUrl('https://huggingface.co/spaces/nateraw/dreambooth-training',...)

# Duplicate a dataset
>>> duplicate_repo("openai/gdpval", repo_type="dataset")
RepoUrl('https://huggingface.co/datasets/nateraw/gdpval',...)

create_repo()と同様に、duplicate_repo()はresource_group_idを受け取り、Enterprise組織のリソースグループ内にコピーを直接作成できます（hf repos duplicateでは--resource-group-idを使用）。

git の履歴は即座にコピーされますが、duplicate_repo() が返却された後でも、LFS/Xet ファイルはバックグラウンドでコピーされ続ける場合があります。コピーが完了するまで、新しいリポジトリからこれらのファイルをダウンロードすると失敗する可能性があります。コピーがまだ進行中かどうかを確認するには、返却値の files_copy_pending をチェックしてください。

>>> from huggingface_hub import duplicate_repo
>>> repo_url = duplicate_repo("openai/gdpval", repo_type="dataset")
>>> repo_url.files_copy_pending
True

Spacesを検索

Hubには、Spacesを発見するためのセマンティック検索APIが提供されています。search_spaces() を使用して、自然言語のクエリで検索できます。

>>> from huggingface_hub import search_spaces
>>> results = list(search_spaces("generate image"))
>>> results[0].id
'mrfakename/Z-Image-Turbo'

詳細およびフィルタリングオプションについては、Spacesの管理ガイドを参照してください。

ファイルのアップロードとダウンロード

リポジトリを作成したので、次にそのリポジトリへ変更をプッシュしたり、そこからファイルをダウンロードしたりする方法について見ていきましょう。

これら2つのトピックは、それぞれ専用のガイドがあります。リポジトリの使用方法については、アップロードガイドとダウンロードガイドを参照してください。

ファイルをコピー

Hub上で既にホストされているファイルをダウンロードして再アップロードすることなく、1つのリポジトリから別のリポジトリへ（同じリポジトリ内でも可）コピーするには、copy_files()を使用します。個別のファイルとフォルダ全体がサポートされており、XetまたはLFSでトラッキングされているファイルは、ハッシュによってサーバーサイドでコピーされます。

>>> from huggingface_hub import copy_files

# Copy a single file from one repo to another
>>> copy_files(
...     "hf://username/source-model/config.json",
...     "hf://username/dest-model/config.json",
... )

# Copy an entire folder (a trailing "/" copies the folder *contents*, rsync-style)
>>> copy_files(
...     "hf://datasets/username/my-dataset/data/",
...     "hf://datasets/username/my-dataset-copy/data/",
... )

または、統合されたhf cpコマンド（hf repos cpとしても利用可能）でCLIから実行できます:

# Copy a single file between repositories
>>> hf cp hf://username/source-model/config.json hf://username/dest-model/config.json

# Copy a file from a repo to your local machine
>>> hf repos cp hf://username/my-model/config.json ./config.json

# Upload a local file to a repository
>>> hf repos cp ./model.safetensors hf://username/my-model/model.safetensors

copy_files（およびhf cp）は、リポジトリからBucketへファイルをコピーすることもできます。from Bucket to リポジトリへのコピーはサポートされていません。詳細はBucketsガイドを参照してください。

サーバーサイドのコピーは、同じストレージリージョン内でのみ機能します。

ブランチとタグ

Git リポジトリでは、同じリポジトリの異なるバージョンを保存するためにブランチが頻繁に使用されます。 タグも、バージョンをリリースする際にリポジトリの特定の状態をマークするために使用できます。 より一般的には、ブランチとタグはgit リファレンスと呼ばれます。

ブランチとタグの作成

create_branch()とcreate_tag()を使用して、新しいブランチとタグを作成できます。

>>> from huggingface_hub import create_branch, create_tag

# Create a branch on a Space repo from `main` branch
>>> create_branch("Matthijs/speecht5-tts-demo", repo_type="space", branch="handle-dog-speaker")

# Create a tag on a Dataset repo from `v0.1-release` branch
>>> create_tag("bigcode/the-stack", repo_type="dataset", revision="v0.1-release", tag="v0.1.1", tag_message="Bump release version.")

または、CLI経由で:

>>> hf repos branch create Matthijs/speecht5-tts-demo handle-dog-speaker --repo-type space
>>> hf repos tag create bigcode/the-stack v0.1.1 --repo-type dataset --revision v0.1-release -m "Bump release version."

delete_branch()およびdelete_tag()関数を使用して、ブランチまたはタグを削除できます。CLIでは、それぞれhf repos branch deleteおよびhf repos tag deleteを使用します。

すべてのブランチとタグをリスト表示

リポジトリから既存のgit refsをlist_repo_refs()を使用して一覧表示することもできます。

>>> from huggingface_hub import list_repo_refs
>>> list_repo_refs("bigcode/the-stack", repo_type="dataset")
GitRefs(
   branches=[
         GitRefInfo(name='main', ref='refs/heads/main', target_commit='18edc1591d9ce72aa82f56c4431b3c969b210ae3'),
         GitRefInfo(name='v1.1.a1', ref='refs/heads/v1.1.a1', target_commit='f9826b862d1567f3822d3d25649b0d6d22ace714')
   ],
   converts=[],
   tags=[
         GitRefInfo(name='v1.0', ref='refs/tags/v1.0', target_commit='c37a8cd1e382064d8aced5e05543c5f7753834da')
   ]
)

リポジトリの設定を変更する

リポジトリには、設定可能ないくつかの設定があります。ほとんどの場合、ブラウザのリポジトリ設定ページで手動で設定することになります。リポジトリを設定するには、書き込みアクセス権が必要です（リポジトリの所有者であるか、組織のメンバーであること）。このセクションでは、huggingface_hub を使用してプログラム的にも設定できる設定について説明します。

一部の設定はSpacesに固有のものである（ハードウェア、環境変数など）。それらの設定については、Spacesの管理ガイドを参照してください。

可視性の更新

リポジトリは公開または非公開に設定できます。非公開リポジトリは、あなた自身またはリポジトリが属する組織のメンバーのみが参照できます。次の手順に従って、リポジトリを非公開に変更してください。

>>> from huggingface_hub import update_repo_settings
>>> update_repo_settings(repo_id=repo_id, private=True)

または、CLI経由で:

>>> hf repos settings lysandre/test-private --private true

ゲート付きアクセスのセットアップ

リポジトリの使用方法に対する制御を強化するため、Hub ではリポジトリの作成者がリポジトリに対してアクセスリクエストを有効にできます。有効化された場合、ユーザーはファイルにアクセスするために、リポジトリの作成者と連絡先情報（ユーザー名とメールアドレス）を共有することに同意する必要があります。アクセスリクエストが有効化されたリポジトリは、ゲート付きリポジトリと呼ばれます。

update_repo_settings() を使用して、リポジトリをゲート付きに設定できます:

>>> from huggingface_hub import HfApi

>>> api = HfApi()
>>> api.update_repo_settings(repo_id=repo_id, gated="auto")  # Set automatic gating for a model

または、CLI経由で:

>>> hf repos settings lysandre/test-private --gated auto

リポジトリの名前を変更する

Hubでは、move_repo()を使用してリポジトリの名前を変更できます。このメソッドを使用すると、リポジトリをユーザーから組織へ移動することもできます。その際、いくつかの制限事項がありますので、ご注意ください。例えば、リポジトリを別のユーザーに転送することはできません。

>>> from huggingface_hub import move_repo
>>> move_repo(from_id="Wauplin/cool-model", to_id="huggingface/cool-model")

または、CLI経由で:

>>> hf repos move Wauplin/cool-model huggingface/cool-model

カーネルリポジトリ

Hubは、計算カーネルのホスティング用に"kernel"リポジトリタイプをサポートしています。これは完全には互換性のあるリポジトリタイプではありません。テストが実施され、公式にサポートされているのは、限られたメソッドのみです:

create_repo()およびdelete_repo()も互換性がありますが、Hubでは許可されたユーザーと組織の小さなサブセットに制限されています。

カーネルリポジトリの構築、公開、および利用には、代わりに専用のkernelsパッケージを使用してください。詳細については、Kernels ドキュメントを参照してください。

Update on GitHub

←HfFileSystem 検索→