遷移到 huggingface_hub v1.0

huggingface_hub 庫的 v1.0 版本是一個重要的里程碑。它標誌著我們對 API 穩定性和庫成熟度的承諾。我們進行了一些改進和破壞性更改，以使庫更加健壯且易於使用。

本指南旨在幫助您將現有程式碼遷移到新版本。如果您有任何疑問或反饋，請透過在 GitHub 上開啟 issue告知我們。

Python 3.9+

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

HTTPX 遷移

huggingface_hub 庫現在使用 httpx 而不是 requests 進行 HTTP 請求。此更改旨在提高效能並以相同方式支援同步和非同步請求。因此，我們刪除了 requests 和 aiohttp 依賴項。

破壞性更改

這是一項影響整個庫的重要更改。雖然我們已盡力使此更改儘可能透明，但在某些情況下您可能需要更新您的程式碼。以下是在此過程中引入的破壞性更改列表：

• 代理配置：不再支援“按方法”代理。必須使用 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 用作上下文管理器。這在流式傳輸語言模型中的 token 時特別有用，以確保正確關閉連線。
• AsyncInferenceClient：已從 AsyncInferenceClient 的建構函式中刪除 trust_env 引數。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_xet 可選包的支援。因此，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 用於管理使用者訪問令牌。使用 login() 儲存新 token，使用 logout() 刪除它，並使用 whoami() 檢查與當前 token 關聯的使用者。最後，在指令碼中使用 get_token() 來檢索使用者的 token。

InferenceApi 類

InferenceApi 是一個用於與推理 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 已移除。現在“寫許可權”概念已被移除且不再相關，因為精細化 token 是推薦方法。
• 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 支援

v1.0 中已移除所有與 TensorFlow 相關的程式碼和依賴項。這包括以下破壞性更改：

• 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 是一個過時且無人維護的庫。推薦的方法是使用 Keras 3.x，它與 Hub 緊密整合（即，它包含用於載入/推送到 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 上更新