Hub Python 函式庫文件
建立與管理儲存庫
並獲得增強的文件體驗
開始使用
建立與管理儲存庫
Hugging Face Hub 是 Git 儲存庫的集合。Git 是一個廣泛用於軟體開發的工具，可在協作時輕鬆管理專案版本。本指南將向您展示如何與 Hub 上的儲存庫互動，尤其是
- 建立與刪除儲存庫。
- 管理分支與標籤。
- 重新命名您的儲存庫。
- 更新您的儲存庫可見性。
- 管理您儲存庫的本地副本。
如果您習慣使用 GitLab/GitHub/Bitbucket 等平台，您的第一直覺可能是使用
gitCLI 來複製儲存庫 (git clone)、提交變更 (git add, git commit) 並推送它們 (git push)。這在使用 Hugging Face Hub 時是有效的。然而，軟體工程和機器學習有著不同的要求和工作流程。模型儲存庫可能會為不同的框架和工具維護大型模型權重文件，因此複製儲存庫可能會導致您維護大量龐大的本地資料夾。因此，使用我們的自訂 HTTP 方法可能會更有效率。您可以閱讀我們的Git 與 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'或透過 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() 函數。
如果您是擁有企業方案的組織成員，您可以透過將
resource_group_id作為參數傳遞給 create_repo()，在特定的資源群組中建立儲存庫。資源群組是一個安全功能，用於控制您的組織中哪些成員可以存取給定的資源。您可以從 Hub 上的組織設定頁面 URL 複製資源群組 ID（例如"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',...)搜尋 Spaces
Hub 提供了一個語義搜尋 API，用於探索 Spaces。您可以使用 search_spaces() 進行自然語言查詢
>>> from huggingface_hub import search_spaces
>>> results = list(search_spaces("generate image"))
>>> results[0].id
'mrfakename/Z-Image-Turbo'有關更多詳細資訊和篩選選項，請參閱管理您的 Spaces 指南。
上傳與下載檔案
現在您已建立儲存庫，您會對向其推送變更以及從中下載檔案感興趣。
這兩個主題都值得各自的指南。請參考上傳和下載指南，以了解如何使用您的儲存庫。
分支與標籤
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。
列出所有分支與標籤
您也可以使用 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)或透過 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重新命名您的儲存庫
您可以使用 move_repo() 在 Hub 上重新命名您的儲存庫。使用此方法，您也可以將儲存庫從使用者移動到組織。在這樣做時，您應該注意一些限制。例如，您不能將您的儲存庫轉移給另一個使用者。
>>> 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" 儲存庫類型，用於託管計算核心。這不是一個完全相容的儲存庫類型。只有有限的方法集經過測試並獲得官方支援
- kernel_info()
- hf_hub_download()
- snapshot_download()
- list_repo_refs()
- list_repo_files()
- list_repo_tree()
請注意，create_repo() 和 delete_repo() 也相容，但僅限於 Hub 上一小部分允許的使用者和組織。
對於建構、發布和使用核心儲存庫，請改用專用的 kernels 套件。請參閱 Kernels 文件以獲取更多詳細資訊。