為什麼你該學會這個？

你有沒有碰過這種情況？在HuggingFace上看到一個超讚的AI模型，結果下載下來是一堆亂七八糟的檔案，不知道怎麼管理。或者，你明明下載了模型，卻因為路徑不對、版本搞錯，浪費好幾個小時在除錯上。

這不是你的問題。AI模型的世界本來就亂——動輒好幾GB的權重檔、一堆設定檔、不同版本迭代，光是用手動管理就夠你頭痛。但好消息是，HuggingFace早就幫你想好了解決方案：HuggingFace Hub CLI（命令列工具）。

學會這個工具，你就能：

  • 一鍵下載任何模型，不用手動點擊檔案
  • 自動管理模型版本，再也不會搞混
  • 直接從程式碼載入模型，路徑永遠正確
  • 甚至上傳你自己的模型，跟全世界分享

這篇文章會用最簡單的方式，帶你從零開始學會HuggingFace Hub。你不需要會寫程式，只要懂得打開終端機（命令提示字元）就可以。準備好了嗎？我們開始吧。

第一步：安裝HuggingFace Hub

首先，你需要安裝huggingface_hub這個Python套件。如果你還沒有安裝Python，先去python.org下載最新版本（建議3.10以上）。

打開你的終端機（Windows用戶按Win+R，輸入cmd；Mac用戶打開「終端機」應用程式），輸入以下指令：

pip install huggingface_hub

看到「Successfully installed」的訊息就代表安裝成功了。如果你用的是Mac或Linux，可能需要加上pip3而不是pip。

小技巧：如果你怕弄亂系統環境，可以用虛擬環境（virtual environment）來安裝。不過對初學者來說，直接裝在全域也沒問題。

第二步：登入你的HuggingFace帳號

雖然不登入也能下載公開模型，但登入後可以享有更多功能——比如下載需要授權的模型、上傳你自己的模型。而且登入只需要一次，之後就不用再重複輸入。

先到HuggingFace官網註冊一個免費帳號。然後在你的帳號設定頁面（Settings → Access Tokens）建立一個Token，記得選「Read」權限就好。

回到終端機，輸入：

huggingface-cli login

系統會問你Token，貼上去按Enter就完成了。你會看到「Login successful」的訊息。

真實案例：我朋友小明之前不知道可以這樣做，每次下載模型都要手動在網頁上一個一個點檔案，下載了十幾個檔案後還得自己整理路徑。學會登入後，他只要一行指令就能搞定，省下的時間夠他多看兩集Netflix。

第三步：用一行指令下載模型

現在來到最實用的部分。假設你想下載最近很紅的deepseek-ai/DeepSeek-V4-Pro這個模型（就是最近在HuggingFace上爆紅的那個），你只需要輸入：

huggingface-cli download deepseek-ai/DeepSeek-V4-Pro

系統就會自動把整個模型的所有檔案下載到你的電腦上。預設路徑是~/.cache/huggingface/hub/，但你也可以指定下載位置：

huggingface-cli download deepseek-ai/DeepSeek-V4-Pro --local-dir ./my-models

這樣就會下載到你當前目錄下的my-models資料夾。是不是超簡單？

進階技巧：如果你只需要某個特定檔案（比如模型權重檔），可以加上檔案名稱：

huggingface-cli download deepseek-ai/DeepSeek-V4-Pro model.safetensors

只下載你需要的檔案，省空間又省時間。

第四步：從程式碼直接載入模型

這才是HuggingFace Hub真正的威力所在。你不需要手動管理模型檔案，直接在你的Python程式碼裡這樣寫：

from huggingface_hub import snapshot_download

# 下載整個模型到指定資料夾
model_path = snapshot_download(repo_id="deepseek-ai/DeepSeek-V4-Pro")
print(f"模型下載到：{model_path}")

# 之後你就可以用這個路徑載入模型

更常見的做法是，如果你在用Transformers或Diffusers這類套件，它們已經內建了HuggingFace Hub的支援：

from transformers import AutoModel

# 直接從模型名稱載入，不用管路徑
model = AutoModel.from_pretrained("deepseek-ai/DeepSeek-V4-Pro")

看到沒？一行程式碼搞定。你不用擔心模型存在哪裡、檔案叫什麼名字，這些都交給HuggingFace Hub處理。

為什麼這很重要？想像你今天在寫一個AI繪圖的應用，需要載入Stable Diffusion模型。如果你用手動管理，程式碼裡到處都是絕對路徑，換一台電腦就全部壞掉。但用HuggingFace Hub，你只需要改一個模型名稱，其他地方都不用動。

第五步：上傳你自己的模型（進階）

如果你訓練了自己的模型，想分享給全世界，HuggingFace Hub也讓上傳變得超簡單。

首先，在HuggingFace網站上建立一個新的Repository（點右上角的「New Model」）。然後在你的終端機輸入：

huggingface-cli upload 你的使用者名稱/你的模型名稱 ./本地資料夾

就這樣，你的模型就上傳到HuggingFace了。其他人只要用from_pretrained就能載入你的模型。

真實場景：我認識一個台灣的AI工程師，他訓練了一個繁體中文專用的文字嵌入模型。他用這個方法上傳後，短短一週就有超過5000次下載，還收到好幾封感謝信。這就是開源社群的魅力。

延伸閱讀

常見問題

Q: 下載模型會不會很慢？ A: 要看模型大小和你的網路速度。一般幾GB的模型可能需要幾分鐘到半小時。HuggingFace Hub支援斷點續傳，如果下載中斷，重新執行指令會從中斷處繼續下載。

Q: 我可以只下載模型的一部分嗎？ A: 可以。用huggingface-cli download加上檔案名稱，就能只下載特定檔案。或者用--include和--exclude參數來過濾檔案類型。

Q: 為什麼我執行huggingface-cli出現「command not found」？ A: 這代表Python的Scripts資料夾沒有加到系統PATH。解決方法：重新安裝時勾選「Add Python to PATH」，或者直接用python -m huggingface_hub.commands來執行。

Q: 上傳模型需要什麼權限？ A: 你需要一個Write權限的Token。在HuggingFace設定頁面建立Token時，選擇「Write」或「Fine-grained」權限。上傳前先用huggingface-cli login登入。

Q: 我可以刪除上傳的模型嗎？ A: 可以，但只能在HuggingFace網站上操作。到你的模型頁面，點Settings → Delete repository。注意：刪除後無法復原，所有下載次數和評論都會消失。