將您的庫與 Hub 整合

Hugging Face Hub 旨在促進機器學習模型、檢查點和工件的共享。這項工作包括將 Hub 整合到社群中的許多出色的第三方庫中。其中一些已整合的庫包括 spaCy、Sentence Transformers、OpenCLIP 和 timm 等。整合意味著使用者可以直接從您的庫中下載和上傳檔案到 Hub。我們希望您能整合您的庫，並與我們一起為所有人實現人工智慧的民主化。

將 Hub 與您的庫整合提供了許多好處，包括：

• 為您和您的使用者提供免費模型託管。
• 內建檔案版本控制——即使是巨型檔案——透過 Git-LFS 實現。
• 社群功能（討論、拉取請求、點贊）。
• 所有使用您的庫執行的模型的使用指標。

本教程將幫助您將 Hub 整合到您的庫中，以便您的使用者可以從 Hub 提供的所有功能中受益。

在開始之前，我們建議您建立一個 Hugging Face 帳戶，您可以從中管理您的倉庫和檔案。

如果您在整合方面需要幫助，請隨時提出 問題，我們將非常樂意為您提供幫助。

實現

實現庫與 Hub 的整合通常意味著提供內建方法來從 Hub 載入模型並允許使用者將新模型推送到 Hub。本節將介紹如何使用 huggingface_hub 庫實現這些功能的基礎知識。有關更深入的指導，請檢視 本指南。

安裝

要將您的庫與 Hub 整合，您需要將 huggingface_hub 庫新增為依賴項。

pip install huggingface_hub

有關 huggingface_hub 安裝的更多詳細資訊，請檢視 本指南。

npm add @huggingface/hub

使用者成功安裝 huggingface_hub 庫後，需要進行身份驗證。最簡單的身份驗證方法是將令牌儲存在機器上。使用者可以使用 login() 命令從終端執行此操作：

hf auth login

該命令會告訴他們是否已登入，並提示他們輸入令牌。然後，令牌會經過驗證並儲存在他們的 HF_HOME 目錄中（預設為 ~/.cache/huggingface/token）。任何與 Hub 互動的指令碼或庫在傳送請求時都將使用此令牌。

或者，使用者可以使用筆記本或指令碼中的 login() 進行程式設計登入：

from huggingface_hub import login
login()

從 Hub 上的公共倉庫下載檔案時，身份驗證是可選的。

從 Hub 下載檔案

整合允許使用者從 Hub 下載模型並直接從您的庫中例項化它。這通常透過提供一個特定於您的庫的方法（通常稱為 from_pretrained 或 load_from_hf）來實現。要從 Hub 例項化模型，您的庫必須：

• 從 Hub 下載檔案。這就是我們現在要討論的內容。
• 從這些檔案例項化 Python 模型。

使用 hf_hub_download 方法從 Hub 上的倉庫下載檔案。下載的檔案儲存在快取中：~/.cache/huggingface/hub。使用者下次使用時無需重新下載檔案，這為大型檔案節省了大量時間。此外，如果倉庫使用新版本的檔案進行了更新，huggingface_hub 將自動下載最新版本並將其儲存在快取中。使用者無需擔心手動更新檔案。

例如，從 lysandre/arxiv-nlp 倉庫下載 config.json 檔案：

>>> 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。它將負責並行下載所有檔案。返回值是包含下載檔案的目錄路徑。

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

有許多選項可以從特定版本下載檔案、過濾要下載的檔案、提供自定義快取目錄、下載到本地目錄等。有關更多詳細資訊，請檢視下載指南。

上傳檔案到 Hub

您可能還希望提供一個方法，以便使用者可以將自己的模型推送到 Hub。這允許社群構建與您的庫相容的模型生態系統。huggingface_hub 庫提供了建立倉庫和上傳檔案的方法：

• create_repo 在 Hub 上建立一個倉庫。
• upload_file 和 upload_folder 將檔案上傳到 Hub 上的倉庫。

create_repo 方法在 Hub 上建立一個倉庫。使用 repo_id 引數為您的倉庫提供一個名稱：

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

當您檢視您的 Hugging Face 帳戶時，您現在應該在您的名稱空間下看到一個 test-model 倉庫。

upload_file 方法將檔案上傳到 Hub。此方法需要以下引數：

• 要上傳檔案的路徑。
• 倉庫中的最終路徑。
• 您希望將檔案推送到的倉庫。

例如：

>>> 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 完成：

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

有關如何上傳檔案的更多詳細資訊，請檢視上傳指南。

模型卡

模型卡是隨模型附帶的檔案，提供有用的資訊。在底層，模型卡是帶有附加元資料的簡單 Markdown 檔案。模型卡對於可發現性、可復現性和共享至關重要！您可以在任何模型倉庫中找到一個名為 README.md 的模型卡檔案。有關如何建立良好模型卡的更多詳細資訊，請參閱模型卡指南。

如果您的庫允許將模型推送到 Hub，建議生成一個帶有預填充元資料（通常是 library_name、pipeline_tag 或 tags）和模型訓練資訊的最小模型卡。這將有助於為所有使用您的庫構建的模型提供標準化描述。

註冊您的庫

做得好！您現在應該有一個能夠從 Hub 載入模型並最終推送新模型的庫。下一步是確保您的 Hub 上的模型有充分的文件並與平臺整合。為此，庫可以在 Hub 上註冊，這為使用者帶來了以下好處：

• 模型頁面可以顯示一個漂亮的標籤（例如 KerasNLP 而不是 keras-nlp）
• 每個模型頁面都會新增指向您的庫倉庫和文件的連結
• 可以定義自定義下載計數規則
• 可以生成程式碼片段，以顯示如何使用您的庫載入模型

要註冊新庫，請按照以下說明在此處開啟拉取請求：here

• 庫 ID 應小寫並用連字元分隔（例如："adapter-transformers"）。請務必在開啟 PR 時保持字母順序。
• 使用使用者友好的命名設定 repoName 和 prettyLabel（例如：DeepForest）。
• 將 repoUrl 設定為指向庫原始碼的連結（通常是 GitHub 倉庫）。
• （可選）將 docsUrl 設定為指向庫文件的連結。如果文件在上述 GitHub 倉庫中，則無需重複設定。
• 將 filter 設定為 false。
• （可選）透過設定 countDownload 定義下載計數方式。下載可以透過副檔名或檔名進行跟蹤。確保不要重複計數。例如，如果載入一個模型需要 3 個檔案，則下載計數規則必須只計算其中 1 個檔案的下載量。否則，下載計數將被高估。**注意：** 如果庫使用預設配置檔案之一（config.json、config.yaml、hyperparams.yaml、params.json 和 meta.yaml，請參見此處），則無需手動定義下載計數規則。
• （可選）定義 snippets 以告知使用者如何快速例項化模型。更多詳細資訊見下文。

在開啟 PR 之前，請確保至少有一個模型在 https://huggingface.co/models?other=my-library-name 上引用。如果沒有，相關模型的模型卡元資料必須更新為 library_name: my-library-name（請參閱示例）。如果您不是 Hub 上模型的所有者，請開啟 PRs（請參閱示例）。

這裡是一個新增 VFIMamba 整合的最小 示例。

程式碼片段

我們建議新增一個程式碼片段來解釋如何在您的下游庫中使用模型。

要新增程式碼片段，您應該更新 model-libraries-snippets.ts 檔案，其中包含有關您的模型的說明。例如，Asteroid 整合包含一個簡短的程式碼片段，說明如何載入和使用 Asteroid 模型：

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

這樣做還會為您的模型新增一個標籤，以便使用者可以快速識別來自您的庫的模型。

一旦您的程式碼片段新增到 model-libraries-snippets.ts，您就可以在 model-libraries.ts 中引用它，如上所述。

文件化您的庫

最後，您可以將您的庫新增到 Hub 的文件中。例如，檢視新增 SetFit 到文件的 Setfit PR。