建立和管理儲存庫

Hugging Face Hub 是 Git 儲存庫的集合。Git 是一種在軟體開發中廣泛使用的工具，用於在協作時輕鬆管理專案版本。本指南將向您展示如何與 Hub 上的儲存庫進行互動，特別是：

建立和刪除儲存庫。
管理分支和標籤。
重新命名您的儲存庫。
更新您的儲存庫可見性。
管理您的儲存庫的本地副本。

如果您習慣於使用 GitLab/GitHub/Bitbucket 等平臺，您的第一反應可能是使用 `git` CLI 克隆您的倉庫 (`git clone`)、提交更改 (`git add, git commit`) 並推送它們 (`git push`)。這在使用 Hugging Face Hub 時是有效的。但是，軟體工程和機器學習不共享相同的需求和工作流程。模型倉庫可能為不同的框架和工具維護大型模型權重檔案，因此克隆倉庫可能導致您維護包含大量檔案的大型本地資料夾。因此，使用我們自定義的 HTTP 方法可能更有效率。您可以閱讀我們的Git vs HTTP 範例解釋頁面以獲取更多詳細資訊。

如果您想在 Hub 上建立和管理儲存庫，您的機器必須已登入。如果您尚未登入，請參閱此部分。本指南的其餘部分將假設您的機器已登入。

倉庫建立和刪除

第一步是瞭解如何建立和刪除儲存庫。您只能管理您擁有的（在您的使用者名稱名稱空間下）或您具有寫入許可權的組織的儲存庫。

建立儲存庫

使用 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'

預設情況下，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'

建立儲存庫時，可以使用 `private` 引數設定儲存庫的可見性。

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

如果以後要更改儲存庫可見性，可以使用 update_repo_settings() 函式。

如果您是具有企業計劃的組織成員，您可以透過將 `resource_group_id` 作為引數傳遞給 create_repo() 來在特定的資源組中建立倉庫。資源組是一種安全功能，用於控制您的組織成員可以訪問哪些給定資源。您可以從 Hub 上的組織設定頁面 URL 複製資源組 ID (例如 `“https://huggingface.co/organizations/huggingface/settings/resource-groups/66670e5163145ca562cb1988”` => `“66670e5163145ca562cb1988”`)。有關資源組的更多詳細資訊，請檢視此指南。

刪除儲存庫

使用 delete_repo() 刪除儲存庫。請確保您確實要刪除儲存庫，因為此過程不可逆！

指定要刪除的儲存庫的 `repo_id`

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

複製儲存庫（僅適用於 Spaces）

在某些情況下，您希望複製別人的倉庫以適應您的用例。這可以透過 duplicate_space() 方法在 Spaces 中實現。它將複製整個倉庫。您仍然需要配置自己的設定（硬體、睡眠時間、儲存、變數和機密）。有關更多詳細資訊，請檢視我們的管理您的 Space 指南。

>>> from huggingface_hub import duplicate_space
>>> duplicate_space("multimodalart/dreambooth-training", private=False)
RepoUrl('https://huggingface.co/spaces/nateraw/dreambooth-training',...)

上傳和下載檔案

現在您已經建立了儲存庫，您有興趣將更改推送到它並從它下載檔案。

這兩個主題值得單獨的指南。請參閱上傳和下載指南，瞭解如何使用您的儲存庫。

分支和標籤

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.")

您可以使用 delete_branch() 和 delete_tag() 函式以相同的方式刪除分支或標籤。

列出所有分支和標籤

您還可以使用 list_repo_refs() 列出儲存庫中現有的 Git 引用。

>>> 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)

設定受限訪問

為了更好地控制倉庫的使用，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

重新命名您的儲存庫

您可以使用 move_repo() 在 Hub 上重新命名您的儲存庫。使用此方法，您還可以將儲存庫從使用者移動到組織。這樣做時，您應該注意一些限制。例如，您無法將您的儲存庫轉移給其他使用者。

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

管理您的儲存庫的本地副本

上述所有操作都可以使用 HTTP 請求完成。但是，在某些情況下，您可能希望擁有儲存庫的本地副本，並使用您熟悉的 Git 命令與其進行互動。

Repository 類允許您使用類似於 Git 命令的函式與 Hub 上的檔案和儲存庫進行互動。它是 Git 和 Git-LFS 方法的包裝器，用於使用您已經瞭解和喜愛的 Git 命令。在開始之前，請確保您已安裝 Git-LFS（有關安裝說明，請參閱此處）。

Repository 已被棄用，轉而使用 HfApi 中實現的基於 HTTP 的替代方案。考慮到其在舊程式碼中的廣泛採用，Repository 的完全移除只會在 `v1.0` 版本中發生。有關更多詳細資訊，請閱讀此解釋頁面。

使用本地儲存庫

使用指向本地儲存庫路徑的 Repository 物件進行例項化

>>> from huggingface_hub import Repository
>>> repo = Repository(local_dir="<path>/<to>/<folder>")

克隆

`clone_from` 引數將儲存庫從 Hugging Face 儲存庫 ID 克隆到 `local_dir` 引數指定的本地目錄。

>>> from huggingface_hub import Repository
>>> repo = Repository(local_dir="w2v2", clone_from="facebook/wav2vec2-large-960h-lv60")

`clone_from` 也可以使用 URL 克隆儲存庫

>>> repo = Repository(local_dir="huggingface-hub", clone_from="https://huggingface.co/facebook/wav2vec2-large-960h-lv60")

您可以將 `clone_from` 引數與 create_repo() 結合使用，以建立和克隆儲存庫。

>>> repo_url = create_repo(repo_id="repo_name")
>>> repo = Repository(local_dir="repo_local_path", clone_from=repo_url)

您還可以在克隆儲存庫時透過指定 `git_user` 和 `git_email` 引數來為克隆的儲存庫配置 Git 使用者名稱和電子郵件。當用戶向該儲存庫提交時，Git 將知道提交作者。

>>> repo = Repository(
...   "my-dataset",
...   clone_from="<user>/<dataset_id>",
...   token=True,
...   repo_type="dataset",
...   git_user="MyName",
...   git_email="me@cool.mail"
... )

分支

分支對於協作和實驗非常重要，不會影響您當前的檔案和程式碼。使用 git_checkout() 在分支之間切換。例如，如果您想從 `branch1` 切換到 `branch2`：

>>> from huggingface_hub import Repository
>>> repo = Repository(local_dir="huggingface-hub", clone_from="<user>/<dataset_id>", revision='branch1')
>>> repo.git_checkout("branch2")

拉取

git_pull() 允許您使用遠端倉庫的更改來更新當前的本地分支。

>>> from huggingface_hub import Repository
>>> repo.git_pull()

如果您希望本地提交發生在分支更新遠端新提交之後，請設定 `rebase=True`。

>>> repo.git_pull(rebase=True)

< > 在 GitHub 上更新

Hub Python 庫