遷移至 huggingface_hub v1.0

v1.0 版本是 huggingface_hub 函式庫的一個重要里程碑。它標誌著我們對 API 穩定性與函式庫成熟度的承諾。我們進行了多項改進與重大變更，旨在使函式庫更加強大且易於使用。

本指南旨在協助您將現有程式碼遷移至新版本。如果您有任何問題或意見，請透過在 GitHub 上開啟 Issue 通知我們。

Python 3.9+

huggingface_hub 現在要求使用 Python 3.9 或更高版本。不再支援 Python 3.8。

HTTPX 遷移

huggingface_hub 函式庫現在使用 httpx 而非 requests 來進行 HTTP 請求。此變更是為了提升效能並以相同方式支援同步與非同步請求。因此，我們移除了 requests 與 aiohttp 的依賴。

重大變更

這是一項影響整個函式庫的重大變更。雖然我們已盡量讓此過程平滑過渡，但在某些情況下，您可能仍需更新程式碼。以下是此過程中導入的重大變更清單：

Proxy 設定：不再支援「個別方法」的 Proxy 設定。Proxy 必須透過 HTTP_PROXY 與 HTTPS_PROXY 環境變數進行全域設定。
自訂 HTTP 後端：configure_http_backend 函式已被移除。您現在應使用 set_client_factory() 與 set_async_client_factory() 來設定 HTTP 客戶端。
錯誤處理：HTTP 錯誤不再繼承自 requests.HTTPError，而是繼承自 httpx.HTTPError。我們建議捕捉 huggingface_hub.HfHubHttpError，它是 v0.x 中 requests.HTTPError 的子類，也是 v1.x 中 httpx.HTTPError 的子類。捕捉 huggingface_hub 的錯誤可確保您的程式碼同時相容於函式庫的新舊版本。
SSLError：httpx 沒有 SSLError 的概念。現在統一為通用的 httpx.ConnectError。
LocalEntryNotFoundError：此錯誤不再繼承自 HTTPError。我們現在定義了一個（新的）EntryNotFoundError，由 LocalEntryNotFoundError（若檔案在本地快取中找不到）與 RemoteEntryNotFoundError（若檔案在 Hub 的儲存庫中找不到）共同繼承。僅遠端錯誤會繼承自 HTTPError。
InferenceClient：InferenceClient 現在可用作內容管理器（context manager）。這在從語言模型串流傳輸 Token 時特別有用，可確保連接能正確關閉。
AsyncInferenceClient：trust_env 參數已從 AsyncInferenceClient 的建構函式中移除。httpx 預設會信任環境變數。如果您明確不想信任環境變數，必須使用 set_client_factory() 進行設定。

欲了解更多詳情，請查看引入 httpx 的 PR #3328。

為什麼選擇 httpx？

從 requests 遷移至 httpx 帶來了數項關鍵改進，提升了函式庫的效能、可靠性與可維護性：

執行緒安全與連接複用：httpx 在設計上即具備執行緒安全，允許我們在多個執行緒中安全地重複使用同一個客戶端。這種連接複用減少了為每個 HTTP 請求建立新連接的開銷，特別是在頻繁向 Hub 發送請求時，能顯著提升效能。

HTTP/2 支援：httpx 提供原生的 HTTP/2 支援，在向同一伺服器進行多次請求時（這正是我們的使用場景）能提供更高的效率。與 HTTP/1.1 相比，這能降低延遲並減少資源消耗。

統一的同步/非同步 API：與我們之前依賴 requests（同步）與 aiohttp（非同步）的分離設定不同，httpx 提供了行為一致的同步與非同步客戶端。這確保了 InferenceClient 與 AsyncInferenceClient 擁有一致的功能，並消除了以往在兩種實作之間存在的細微行為差異。

改進的 SSL 錯誤處理：httpx 能更優雅地處理 SSL 錯誤，使偵錯連接問題變得更輕鬆且可靠。

前瞻性架構：httpx 獲得積極維護且專為現代 Python 應用程式而設計。相對地，requests 已進入維護模式，不會再獲得如執行緒安全改進或 HTTP/2 支援等重大更新。

更好的環境變數處理：httpx 在同步與非同步環境下都能提供更一致的環境變數處理，消除了以往 requests 預設會讀取本地環境變數而 aiohttp 不會的差異。

轉向 httpx 使 huggingface_hub 具備了現代化、高效且易於維護的 HTTP 後端。儘管大多數使用者應能感受到順暢的操作，但這些底層改進為所有 Hub 的互動提供了更好的效能與可靠性。

hf_transfer

鑑於 Hub 上的所有儲存庫現在都已啟用 Xet，且 hf_xet 成為下載/上傳檔案的預設方式，我們移除了對 hf_transfer 選用套件的支援。因此，HF_HUB_ENABLE_HF_TRANSFER 環境變數將被忽略。請改用 HF_XET_HIGH_PERFORMANCE。

Repository 類別

Repository 類別已在 v1.0 中移除。它曾是 git CLI 的輕量級封裝，用於管理儲存庫。您仍然可以直接在終端機中使用 git，但建議的方式是使用 huggingface_hub 函式庫中的 HTTP API，以獲得更流暢的體驗，特別是在處理大型檔案時。

以下是從舊版 Repository 類別到新版 HfApi 的對應表：

`Repository` 方法	`HfApi` 方法
`repo.clone_from`	`snapshot_download`
`repo.git_add` + `git_commit` + `git_push`	upload_file(), upload_folder(), create_commit()
`repo.git_tag`	`create_tag`
`repo.git_branch`	`create_branch`

HfFolder 類別

HfFolder 曾用於管理使用者存取權杖（Token）。請使用 login() 來儲存新 Token，使用 logout() 刪除它，並使用 whoami() 來檢查當前 Token 關聯的使用者。最後，在指令碼中使用 get_token() 來獲取使用者 Token。

InferenceApi 類別

InferenceApi 曾是用於與 Inference API 互動的類別。現在建議改用 InferenceClient 類別。

其他已棄用功能

部分方法與參數已在 v1.0 中移除。下述項目在 v0.x 中已標記為棄用並伴隨警告訊息。

constants.hf_cache_home 已移除。請改用 HF_HOME。
所有方法中的 use_auth_token 參數已移除。請改用 token。
get_token_permission 方法已移除。
update_repo_visibility 方法已移除。請改用 update_repo_settings。
build_hf_headers 中的 is_write_action 參數，以及 login 中的 write_permission 參數已移除。「寫入權限」的概念已被移除，隨著精細化存取控制（fine-grained tokens）成為推薦方案，該概念已不再適用。
login 中的 new_session 參數已更名為 skip_if_logged_in，以提高清晰度。
hf_hub_download 與 snapshot_download 中的 resume_download、force_filename 與 local_dir_use_symlinks 參數已移除。
list_models 中的 library、language、tags 與 task 參數已移除。

CLI 快取指令

CLI 的快取管理已重新設計，採用類似 Docker 的工作流程。舊版的 huggingface-cli 已被移除，由 hf（於 v0.34 引入）取代，提供更清晰的資源-動作式 CLI。舊有的 hf cache scan 與 hf cache delete 指令在 v1.0 中也已移除，改由以下三組新指令取代：

hf cache ls：以簡潔的表格、JSON 或 CSV 格式列出快取項目。使用 --revisions 可檢查個別修訂版本，加入 --filter 表達式（如 size>1GB 或 accessed>30d），並在僅需識別碼時搭配 --quiet 使用。
hf cache rm：刪除選定的快取項目。傳入一個或多個儲存庫 ID（例如 model/bert-base-uncased）或修訂雜湊值，並可選擇添加 --dry-run 進行預覽，或使用 --yes 跳過確認提示。這取代了先前指令中的互動式 TUI 與 --disable-tui 工作流程。
hf cache prune：執行常見的清理工作，一次性刪除未引用的修訂版本。與 hf cache rm 一樣，可添加 --dry-run 或 --yes。

最後，[cli] 安裝額外項目已移除 - CLI 現在直接隨核心 huggingface_hub 套件一同發布。

TensorFlow 與 Keras 2.x 支援

所有與 TensorFlow 相關的程式碼與依賴項已在 v1.0 中移除。這包含以下重大變更：

huggingface_hub[tensorflow] 不再是受支援的額外依賴項。
split_tf_state_dict_into_shards 與 get_tf_storage_size 公用函式已移除。
tensorflow、fastai 與 fastcore 版本不再包含在內建標頭中。

Keras 2.x 的整合也已移除。這包含 KerasModelHubMixin 類別，以及 save_pretrained_keras、from_pretrained_keras 與 push_to_hub_keras 公用函式。Keras 2.x 是已過時且無人維護的函式庫。建議的做法是使用與 Hub 緊密整合的 Keras 3.x（即內建了載入/推送到 Hub 的方法）。如果您仍需使用 Keras 2.x，請將 huggingface_hub 降級至 v0.x 版本。

upload_file 與 upload_folder 回傳值

upload_file() 與 upload_folder() 函式現在回傳的是在 Hub 上建立的提交（commit）URL。先前它們回傳的是檔案或資料夾的 URL。這是為了與 create_commit()、delete_file() 與 delete_folder() 的回傳值保持一致。

在 GitHub 上更新

Hub Python 函式庫