共享預訓練模型

在下面的步驟中，我們將介紹將預訓練模型共享到 🤗 Hub 的最簡單方法。有可用的工具和實用程式可以簡化直接在 Hub 上共享和更新模型，我們將在下面探討。

我們鼓勵所有訓練模型使用者透過與社群共享來做出貢獻——即使在非常特定的資料集上訓練的模型，共享模型也將幫助他人，節省他們的時間和計算資源，並提供對有用的訓練構件的訪問。反過來，您可以從他人所做的工作中受益！

有三種建立新模型倉庫的方法

使用 push_to_hub API
使用 huggingface_hub Python 庫
使用網頁介面

建立倉庫後，您可以透過 git 和 git-lfs 將檔案上傳到其中。我們將在以下部分中指導您建立模型倉庫並向其上傳檔案。

使用 push_to_hub API

將檔案上傳到 Hub 的最簡單方法是利用 push_to_hub API。

在繼續之前，您需要生成一個身份驗證令牌，以便 huggingface_hub API 知道您是誰以及您擁有哪些名稱空間的寫入許可權。確保您處於已安裝 transformers 的環境中（請參閱設定）。如果您在 Jupyter Notebook 中，可以使用以下函式登入：

from huggingface_hub import notebook_login

notebook_login()

在終端中，您可以執行：

huggingface-cli login

在這兩種情況下，您都應該被提示輸入使用者名稱和密碼，這與您登入 Hub 時使用的使用者名稱和密碼相同。如果您還沒有 Hub 個人資料，則應在此處建立一個。

太棒了！您現在已將身份驗證令牌儲存在快取資料夾中。讓我們建立一些倉庫！

如果您嘗試過使用 Trainer API 訓練模型，那麼將模型上傳到 Hub 的最簡單方法是在定義 TrainingArguments 時設定 push_to_hub=True：

from transformers import TrainingArguments

training_args = TrainingArguments(
    "bert-finetuned-mrpc", save_strategy="epoch", push_to_hub=True
)

當您呼叫 `trainer.train()` 時，`Trainer` 會在每次模型儲存時（這裡是每個 epoch）將您的模型上傳到您名稱空間中的一個倉庫。該倉庫將以您選擇的輸出目錄（這裡是 `bert-finetuned-mrpc`）命名，但您可以使用 `hub_model_id = "a_different_name"` 選擇不同的名稱。

要將您的模型上傳到您所屬的組織，只需使用 hub_model_id = "my_organization/my_repo_name" 傳入即可。

訓練完成後，您應該執行最後的 trainer.push_to_hub() 來上傳模型的最新版本。它還將生成一個包含所有相關元資料的模型卡，報告使用的超引數和評估結果！以下是您可能會在這樣的模型卡中找到的內容示例：

An example of an auto-generated model card.

在較低級別上，可以直接透過模型、分詞器和配置物件的 push_to_hub() 方法訪問模型中心。此方法負責倉庫建立以及將模型和分詞器檔案直接推送到倉庫。不需要手動處理，這與我們將在下面看到的 API 不同。

為了瞭解它的工作原理，我們首先初始化一個模型和一個分詞器：

from transformers import AutoModelForMaskedLM, AutoTokenizer

checkpoint = "camembert-base"

model = AutoModelForMaskedLM.from_pretrained(checkpoint)
tokenizer = AutoTokenizer.from_pretrained(checkpoint)

您可以隨意使用它們 — 向分詞器新增 token，訓練模型，微調它。一旦您對結果模型、權重和分詞器滿意，您就可以直接利用 model 物件上可用的 push_to_hub() 方法：

model.push_to_hub("dummy-model")

這將在您的配置檔案中建立新倉庫 `dummy-model`，並使用您的模型檔案填充它。對分詞器執行相同的操作，以便所有檔案現在都可以在此倉庫中使用：

tokenizer.push_to_hub("dummy-model")

如果您屬於某個組織，只需指定 organization 引數即可上傳到該組織的名稱空間：

tokenizer.push_to_hub("dummy-model", organization="huggingface")

如果您希望使用特定的 Hugging Face token，也可以將其指定給 push_to_hub() 方法：

tokenizer.push_to_hub("dummy-model", organization="huggingface", use_auth_token="<TOKEN>")

現在前往模型中心，找到您新上傳的模型：https://huggingface.co/user-or-organization/dummy-model。

點選“檔案和版本”選項卡，您應該會看到以下螢幕截圖中顯示的檔案：

Dummy model containing both the tokenizer and model files.

✏️ 試一試！ 獲取與 bert-base-cased 檢查點關聯的模型和分詞器，並使用 push_to_hub() 方法將它們上傳到您名稱空間中的一個倉庫。在刪除它之前，請仔細檢查該倉庫是否正確顯示在您的頁面上。

如您所見，push_to_hub() 方法接受多個引數，使其可以將檔案上傳到特定倉庫或組織名稱空間，或者使用不同的 API 令牌。我們建議您檢視🤗 Transformers 文件中直接提供的該方法規範，以瞭解可能的選項。

push_to_hub() 方法由 huggingface_hub Python 包提供支援，該包提供了 Hugging Face Hub 的直接 API。它已整合到 🤗 Transformers 和其他幾個機器學習庫中，例如 allenlp。儘管本章我們重點介紹 🤗 Transformers 的整合，但將其整合到您自己的程式碼或庫中很簡單。

跳到最後一節，檢視如何將檔案上傳到您新建立的倉庫！

使用 huggingface_hub Python 庫

huggingface_hub Python 庫是一個為模型和資料集中心提供一套工具的包。它提供簡單的方法和類，用於執行常見的任務，例如獲取有關中心上的倉庫資訊以及管理它們。它提供了在 Git 之上工作的簡單 API，用於管理這些倉庫的內容並將中心整合到您的專案和庫中。

與使用 push_to_hub API 類似，這需要將您的 API 令牌儲存在快取中。為此，您需要使用 CLI 中的 login 命令，如上一節所述（再次強調，如果在 Google Colab 中執行，請務必在這些命令前加上 ! 字元）：

huggingface-cli login

huggingface_hub 包提供了幾個對我們有用的方法和類。首先，有幾個用於管理倉庫建立、刪除和其他操作的方法：

from huggingface_hub import (
    # User management
    login,
    logout,
    whoami,

    # Repository creation and management
    create_repo,
    delete_repo,
    update_repo_visibility,

    # And some methods to retrieve/change information about the content
    list_models,
    list_datasets,
    list_metrics,
    list_repo_files,
    upload_file,
    delete_file,
)

此外，它還提供了功能非常強大的 Repository 類來管理本地倉庫。我們將在接下來的幾節中探討這些方法和該類，以瞭解如何利用它們。

create_repo 方法可用於在 Hub 上建立新倉庫：

from huggingface_hub import create_repo

create_repo("dummy-model")

這將在您的名稱空間中建立倉庫 `dummy-model`。如果您願意，可以使用 `organization` 引數指定倉庫所屬的組織：

from huggingface_hub import create_repo

create_repo("dummy-model", organization="huggingface")

這將在 huggingface 名稱空間中建立 dummy-model 倉庫，前提是您屬於該組織。其他可能有用的引數是：

private，用於指定倉庫是否對他人可見。
token，如果您想用給定令牌覆蓋快取中儲存的令牌。
repo_type，如果您想建立 dataset 或 space 而不是模型。可接受的值為 "dataset" 和 "space"。

倉庫建立後，我們應該向其中新增檔案！跳到下一節，檢視三種處理方式。

使用網頁介面

網頁介面提供了直接在 Hub 中管理倉庫的工具。使用該介面，您可以輕鬆建立倉庫、新增檔案（甚至大型檔案！）、探索模型、視覺化差異等等。

要建立新倉庫，請訪問 huggingface.co/new

Page showcasing the model used for the creation of a new model repository.

首先，指定倉庫的所有者：可以是您自己或您所屬的任何組織。如果您選擇一個組織，該模型將顯示在組織的頁面上，並且組織的所有成員都將能夠為該倉庫做出貢獻。

接下來，輸入您的模型名稱。這也將是倉庫的名稱。最後，您可以指定您的模型是公開還是私有。私有模型將對公眾隱藏。

建立模型倉庫後，您應該會看到如下頁面：

An empty model page after creating a new repository.

這裡是您模型託管的地方。要開始填充它，您可以直接從網頁介面新增一個 README 檔案。

The README file showing the Markdown capabilities.

README 檔案是 Markdown 格式的 — 盡情發揮吧！本章的第三部分專門介紹如何構建模型卡。這些對於為您的模型帶來價值至關重要，因為它們是您向他人介紹模型功能的場所。

如果您檢視“檔案和版本”選項卡，您會發現那裡沒有太多檔案 — 只有您剛剛建立的 README.md 和用於跟蹤大檔案的 .gitattributes 檔案。

The 'Files and versions' tab only shows the .gitattributes and README.md files.

接下來我們將介紹如何新增一些新檔案。

上傳模型檔案

Hugging Face Hub 上的檔案管理系統基於 Git 處理常規檔案，以及 Git Large File Storage (Git LFS) 處理較大檔案。

在下一節中，我們將介紹三種不同的檔案上傳方式：透過 huggingface_hub 和透過 Git 命令。

upload_file 方法

使用 upload_file 不需要您的系統上安裝 Git 和 Git LFS。它使用 HTTP POST 請求直接將檔案推送到 🤗 Hub。這種方法的侷限性在於它無法處理大於 5GB 的檔案。如果您的檔案大於 5GB，請按照下面詳細介紹的另外兩種方法操作。

API 可以按如下方式使用：

from huggingface_hub import upload_file

upload_file(
    "<path_to_file>/config.json",
    path_in_repo="config.json",
    repo_id="<namespace>/dummy-model",
)

這將把位於 <path_to_file> 的 config.json 檔案作為 config.json 上傳到倉庫的根目錄，即 dummy-model 倉庫。其他可能有用的引數是：

token，如果您想用給定令牌覆蓋快取中儲存的令牌。
repo_type，如果您想上傳到 dataset 或 space 而不是模型。可接受的值為 "dataset" 和 "space"。

Repository 類

Repository 類以類似 Git 的方式管理本地倉庫。它抽象了 Git 可能帶來的大部分痛點，以提供我們所需的所有功能。

使用此類別需要安裝 Git 和 Git LFS，因此在開始之前，請確保您已安裝 Git LFS（有關安裝說明，請參閱此處）並進行設定。

為了開始使用我們剛剛建立的倉庫，我們可以透過克隆遠端倉庫將其初始化到本地資料夾中：

from huggingface_hub import Repository

repo = Repository("<path_to_dummy_folder>", clone_from="<namespace>/dummy-model")

這將在我們的工作目錄中建立了 <path_to_dummy_folder> 資料夾。該資料夾只包含 .gitattributes 檔案，因為這是透過 create_repo 例項化倉庫時建立的唯一檔案。

從現在開始，我們可以利用傳統的 Git 方法中的幾種：

repo.git_pull()
repo.git_add()
repo.git_commit()
repo.git_push()
repo.git_tag()

還有更多！我們建議您檢視 Repository 文件，以瞭解所有可用方法。

目前，我們有一個模型和一個分詞器，我們想將其推送到 Hub。我們已經成功克隆了倉庫，因此我們可以將檔案儲存在該倉庫中。

我們首先透過拉取最新更改來確保我們的本地克隆是最新的：

repo.git_pull()

完成後，我們儲存模型和分詞器檔案：

model.save_pretrained("<path_to_dummy_folder>")
tokenizer.save_pretrained("<path_to_dummy_folder>")

<path_to_dummy_folder> 現在包含所有模型和分詞器檔案。我們遵循通常的 Git 工作流程，將檔案新增到暫存區，提交它們並將其推送到 Hub：

repo.git_add()
repo.git_commit("Add model and tokenizer files")
repo.git_push()

恭喜！您剛剛將第一個檔案推送到 Hub。

基於 Git 的方法

這是上傳檔案的最基本方法：我們將直接使用 Git 和 Git LFS。大多數困難都已被之前的方法抽象掉，但以下方法有一些注意事項，因此我們將遵循更復雜的用例。

使用此類別需要安裝 Git 和 Git LFS，因此在開始之前，請確保您已安裝 Git LFS（有關安裝說明，請參閱此處）並進行設定。

首先透過初始化 git-lfs 開始：

git lfs install

Updated git hooks.
Git LFS initialized.

完成此操作後，第一步是克隆您的模型倉庫：

git clone https://huggingface.co/<namespace>/<your-model-id>

我的使用者名稱是 lysandre，我使用的模型名稱是 dummy，所以對我來說，命令最終看起來像這樣：

git clone https://huggingface.co/lysandre/dummy

我的工作目錄中現在有一個名為 dummy 的資料夾。我可以 cd 進入該資料夾並檢視其內容：

cd dummy && ls

README.md

如果您剛剛使用 Hugging Face Hub 的 create_repo 方法建立了倉庫，此資料夾應該只包含一個隱藏的 .gitattributes 檔案。如果您按照上一節中的說明使用網頁介面建立了倉庫，該資料夾應該包含一個 README.md 檔案以及隱藏的 .gitattributes 檔案，如下所示。

新增常規大小的檔案，例如配置檔案、詞彙檔案或基本上任何小於幾兆位元組的檔案，其操作與在任何基於 Git 的系統中完全相同。但是，更大的檔案必須透過 Git LFS 註冊才能將其推送到 huggingface.co。

讓我們回到 Python 一會兒，生成一個我們想要提交到虛擬倉庫的模型和分詞器：

from transformers import AutoModelForMaskedLM, AutoTokenizer

checkpoint = "camembert-base"

model = AutoModelForMaskedLM.from_pretrained(checkpoint)
tokenizer = AutoTokenizer.from_pretrained(checkpoint)

# Do whatever with the model, train it, fine-tune it...

model.save_pretrained("<path_to_dummy_folder>")
tokenizer.save_pretrained("<path_to_dummy_folder>")

現在我們已經儲存了一些模型和分詞器工件，讓我們再看看 dummy 資料夾：

ls

config.json  pytorch_model.bin  README.md  sentencepiece.bpe.model  special_tokens_map.json tokenizer_config.json  tokenizer.json

如果您檢視檔案大小（例如，使用 ls -lh），您應該會看到模型狀態字典檔案（pytorch_model.bin）是唯一一個異常值，大小超過 400 MB。

✏️ 當從網頁介面建立倉庫時，*.gitattributes* 檔案會自動設定為將具有某些副檔名（如 *.bin* 和 *.h5*）的檔案視為大檔案，並且 Git LFS 將跟蹤它們，無需您進行任何設定。

我們現在可以繼續，像通常處理傳統 Git 倉庫一樣進行操作。我們可以使用 git add 命令將所有檔案新增到 Git 的暫存環境：

git add .

然後我們可以檢視當前暫存的檔案：

git status

On branch main
Your branch is up to date with 'origin/main'.

Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
  modified:   .gitattributes
	new file:   config.json
	new file:   pytorch_model.bin
	new file:   sentencepiece.bpe.model
	new file:   special_tokens_map.json
	new file:   tokenizer.json
	new file:   tokenizer_config.json

同樣，我們可以使用 Git LFS 的 status 命令來確保它正在跟蹤正確的檔案：

git lfs status

On branch main
Objects to be pushed to origin/main:


Objects to be committed:

	config.json (Git: bc20ff2)
	pytorch_model.bin (LFS: 35686c2)
	sentencepiece.bpe.model (LFS: 988bc5a)
	special_tokens_map.json (Git: cb23931)
	tokenizer.json (Git: 851ff3e)
	tokenizer_config.json (Git: f0f7783)

Objects not staged for commit:

我們可以看到所有檔案都以 Git 作為處理程式，除了 pytorch_model.bin 和 sentencepiece.bpe.model，它們使用 LFS。太棒了！

讓我們繼續最後的步驟，提交併推送到 huggingface.co 遠端倉庫：

git commit -m "First model version"

[main b08aab1] First model version
 7 files changed, 29027 insertions(+)
  6 files changed, 36 insertions(+)
 create mode 100644 config.json
 create mode 100644 pytorch_model.bin
 create mode 100644 sentencepiece.bpe.model
 create mode 100644 special_tokens_map.json
 create mode 100644 tokenizer.json
 create mode 100644 tokenizer_config.json

推送可能需要一些時間，具體取決於您的網際網路連線速度和檔案大小。

git push

Uploading LFS objects: 100% (1/1), 433 MB | 1.3 MB/s, done.
Enumerating objects: 11, done.
Counting objects: 100% (11/11), done.
Delta compression using up to 12 threads
Compressing objects: 100% (9/9), done.
Writing objects: 100% (9/9), 288.27 KiB | 6.27 MiB/s, done.
Total 9 (delta 1), reused 0 (delta 0), pack-reused 0
To https://huggingface.co/lysandre/dummy
   891b41d..b08aab1  main -> main

如果在此完成後檢視模型倉庫，我們可以看到所有最近新增的檔案：

The 'Files and versions' tab now contains all the recently uploaded files.

UI 允許您探索模型檔案和提交，並檢視每個提交引入的差異。

The diff introduced by the recent commit.

< > 在 GitHub 上更新

LLM 課程