開始使用儲存庫

這份適合初學者的指南將幫助您掌握在 Hub 上建立與管理儲存庫所需的基本技能。每個章節都是以前述內容為基礎，因此您可以自由選擇從哪裡開始！

需求

本文件將說明如何透過網頁介面以及終端機來處理儲存庫。若使用網頁介面 (UI)，則無需任何額外要求。若您希望使用終端機，請遵循相關安裝說明。

如果您尚未將 git 作為 CLI 指令使用，您需要為您的平台安裝 Git。您還需要安裝 Git-Xet，它將用於處理大型檔案，例如圖像和模型權重。

為了能夠從 Git 下載與上傳大型檔案，您需要安裝 Git Xet 擴充功能。

為了能夠將您的程式碼推送 (push) 至 Hub，您需要進行身分驗證。最簡單的方法是安裝 hf CLI 並執行登入指令。

# Install hf:
#   brew install hf
#   or
#   pip install hf
hf auth login

本文件「開始使用」章節的內容也提供了影片版本！

建立儲存庫

使用 Hub 的網頁介面，您可以輕鬆建立儲存庫、新增檔案（甚至是大型檔案！）、瀏覽模型、視覺化差異 (diff) 等等。Hub 上有三種儲存庫，本指南將示範如何建立一個模型儲存庫。關於如何建立與管理模型、資料集與 Spaces，請參閱各自的說明文件。

1. 若要建立新儲存庫，請訪問 huggingface.co/new

2. 指定儲存庫的擁有者：這可以是您個人，或是您所屬的任何組織。

3. 輸入您的模型名稱。這也將成為儲存庫的名稱。

4. 指定您的模型是要公開還是私有。

5. 指定授權條款 (license)。您目前可以先將「授權 (License)」欄位留空。若要了解更多關於授權的資訊，請參閱 授權 (Licenses) 文件。

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

請注意，Hub 會提示您建立「模型卡 (Model Card)」，您可以在 模型卡說明文件 中了解詳情。在模型儲存庫中包含模型卡是最佳實踐，但由於我們目前只是在建立測試用儲存庫，可以先跳過此步驟。

新增檔案至儲存庫 (網頁介面)

若要透過網頁介面將檔案新增至儲存庫，請先點選「檔案 (Files)」分頁，導航至目標目錄，然後點擊「新增檔案 (Add file)」。您可以選擇建立新檔案或直接從電腦上傳檔案。

建立新檔案

選擇建立新檔案後，您將進入編輯器畫面，可以為檔案命名、新增內容，並輸入一段總結變更的訊息來儲存檔案。除了直接將新檔案 commit 到儲存庫的 main 分支外，您也可以選擇 Open as a pull request 來建立一個 Pull Request。

上傳檔案

若您選擇「上傳檔案 (Upload file)」，您將能夠選擇要上傳的本機檔案，並輸入一段總結儲存庫變更的訊息。

與建立新檔案一樣，您也可以選擇 Open as a pull request 來建立一個 Pull Request，而不是直接將變更新增至儲存庫的 main 分支。

新增檔案至儲存庫 (CLI)

您可以使用 hf CLI 從終端機直接將檔案上傳至您的儲存庫。使用 hf upload 指令來推送本機檔案或整個資料夾。

# Upload a single file to your model repo
hf upload your-username/your-model-name model.safetensors

# Upload an entire directory
hf upload your-username/your-model-name ./my-model-directory

# Upload to a dataset repo
hf upload your-username/your-dataset-name ./data --repo-type dataset

hf CLI 會自動處理大型檔案，無需額外設定。

新增檔案至儲存庫 (git)

複製 (Cloning) 儲存庫

將儲存庫下載到您的本機稱為「複製 (cloning)」。您可以使用下列指令載入並進入您的儲存庫：

git clone https://huggingface.co/<your-username>/<your-model-name>
cd <your-model-name>

或是資料集儲存庫：

git clone https://huggingface.co/datasets/<your-username>/<your-dataset-name>
cd <your-dataset-name>

您可以使用下列指令透過 SSH 進行複製：

git clone git@hf.co:<your-username>/<your-model-name>
cd <your-model-name>

您需要將您的 SSH 公鑰新增至 使用者設定，才能推送變更或存取私有儲存庫。

設定

現在開始吧，您可以將任何想要檔案新增至儲存庫！🔥

有大於 10MB 的檔案嗎？這些檔案應使用 git-xet 進行追蹤，您可以透過以下方式初始化：

git xet install

當您使用 Hugging Face 建立儲存庫時，系統會自動在 .gitattributes 檔案中列出常見機器學習大型檔案的副檔名，git-xet 會利用這些資訊高效追蹤大型檔案的變更。然而，如果您的檔案類型尚未被處理，您可能需要新增副檔名。您可以使用 git xet track "*.your_extension" 來達成。

推送 (Pushing) 檔案

您可以使用 Git 將新檔案或既有檔案的變更儲存為一個稱為「提交 (commit)」的變更集合，這可以被視為您專案的一個「版本」。若要建立 commit，您必須執行 add 將檔案加入 Git 的追蹤清單，然後再 commit 這些變更。最後，為了與 Hugging Face Hub 同步，您需要將 commit push 至 Hub。

# Create any files you like! Then...
git add .
git commit -m "First model version"  # You can choose any descriptive message
git push

大功告成！您可以在 Hugging Face 上查看您的儲存庫，確認所有剛新增的檔案。例如，在下方的截圖中，使用者新增了許多檔案。請注意，此範例中有些檔案大小達到 1.04 GB，因此儲存庫使用了 Xet 來進行追蹤。

如果您使用 HTTP 複製儲存庫，系統可能會在每次執行推送操作時要求您輸入使用者名稱與密碼。避免重複輸入最簡單的方法是改用 SSH，而非 HTTP。或者，若您必須使用 HTTP，設定 git credential helper 來自動填入帳號密碼會非常有幫助。

查看儲存庫歷史紀錄

每次當您執行 add-commit-push 循環時，儲存庫都會記錄您對檔案所做的所有變更。網頁介面允許您瀏覽模型檔案與 commits，並查看每次 commit 所帶來的差異（即 diff）。若要查看歷史紀錄，您可以點擊「歷史紀錄：X 次提交 (History: X commits)」連結。

您可以點擊個別的 commit 來查看該次提交引入了哪些變更。