Hub Python 庫文件
環境變數
並獲得增強的文件體驗
開始使用
環境變數
huggingface_hub 可以透過環境變數進行配置。
如果您不熟悉環境變數，這裡有關於它們的一般性文章，包括 macOS 和 Linux 以及 Windows 系統下的設定方法。
本頁面將引導您瞭解 huggingface_hub 特有的所有環境變數及其含義。
所有環境變數均在匯入
huggingface_hub時讀取。在此之後所做的任何修改都不會被採納。請確保在匯入huggingface_hub之前設定好您的環境變數。
通用
HF_INFERENCE_ENDPOINT
用於配置推理 API 的基礎 URL。如果您的組織指向的是 API 閘道器，而不是直接指向推理 API，您可能需要設定此變數。
預設為 "https://api-inference.huggingface.co"。
HF_HOME
用於配置 huggingface_hub 在本地儲存資料的位置。特別是您的令牌（token）和快取將儲存在此資料夾中。
預設為 "~/.cache/huggingface"，除非設定了 XDG_CACHE_HOME。
HF_HUB_CACHE
用於配置從 Hub 下載的儲存庫（模型、資料集和空間）在本地的快取位置。
預設為 "$HF_HOME/hub"（例如，預設情況下為 "~/.cache/huggingface/hub"）。
HF_XET_CACHE
用於配置 Xet 塊（由 Xet 後端管理的檔案中的位元組範圍）在本地的快取位置。
預設為 "$HF_HOME/xet"（例如，預設情況下為 "~/.cache/huggingface/xet"）。
HF_ASSETS_CACHE
用於配置下游庫建立的資源（assets）在本地的快取位置。這些資源可能是預處理資料、從 GitHub 下載的檔案、日誌等。
預設為 "$HF_HOME/assets"（例如，預設情況下為 "~/.cache/huggingface/assets"）。
HF_TOKEN
用於配置向 Hub 進行身份驗證的使用者訪問令牌。如果設定，此值將覆蓋儲存在機器上的令牌（若未設定 $HF_TOKEN_PATH，則覆蓋 "$HF_HOME/token" 中的令牌）。
有關身份驗證的更多詳細資訊，請檢視此部分。
HF_TOKEN_PATH
用於配置 huggingface_hub 應在何處儲存使用者訪問令牌。預設為 "$HF_HOME/token"（例如，預設情況下為 ~/.cache/huggingface/token）。
HF_HUB_VERBOSITY
設定 huggingface_hub 日誌記錄器的詳細程度級別。必須是 {"debug", "info", "warning", "error", "critical"} 中的一個。
預設為 "warning"。
有關更多詳細資訊，請參閱 日誌參考。
HF_HUB_ETAG_TIMEOUT
定義在下載檔案前從儲存庫獲取最新元資料時，等待伺服器響應的秒數（整數值）。如果請求超時，huggingface_hub 將預設使用本地快取的檔案。為連線速度慢且已快取檔案的機器設定較小的值可以加快工作流程。較高的值可確保元資料呼叫在更多情況下成功。預設為 10 秒。
HF_HUB_DOWNLOAD_TIMEOUT
定義下載檔案時等待伺服器響應的秒數（整數值）。如果請求超時，將引發 TimeoutError。在連線速度較慢的機器上設定較高的值是有益的。在完全網路中斷的情況下，較小的值可以使程序更快地失敗。預設為 10 秒。
Xet
其他 Xet 環境變數
HF_XET_CHUNK_CACHE_SIZE_BYTES
用於設定本地 Xet 塊快取的大小。預設情況下，塊快取是停用的。如果您正在為現有模型或資料集生成新的修訂版本，塊快取可能會有益，因為它用於快取從 S3 獲取的項/塊。較大的快取可以更好地利用跨儲存庫和檔案的去重功能。要啟用塊快取，請將環境變數設定為較大的數字（10GB 或更大）。然而，在大多數下載或上傳新資料的情況下，停用塊快取會有更好的效能，這就是它預設停用的原因。
預設為 0（0 位元組，意味著塊快取已停用）。
HF_XET_SHARD_CACHE_SIZE_LIMIT
用於設定本地 Xet 分片快取的大小。增加此值將提高上傳效率，因為快取分片檔案中引用的塊不會被重新上傳。請注意，預設的軟限制對於大多數工作負載來說應該足夠了。
預設為 4000000000（4GB）。
HF_XET_NUM_CONCURRENT_RANGE_GETS
用於設定每個檔案從 S3 併發下載的項數（xorb 中的位元組範圍，通常稱為塊）。如果有可用的網路頻寬，增加此值將有助於提高下載檔案的速度。
預設為 16。
布林值
以下環境變數期望布林值。如果變數的值為 {"1", "ON", "YES", "TRUE"}（不區分大小寫）中的任意一個，則該變數將被視為 True。任何其他值（或未定義）將被視為 False。
HF_DEBUG
如果設定，huggingface_hub 日誌記錄器的級別將設定為 DEBUG。此外，HF 庫進行的所有請求都將記錄為等效的 cURL 命令，以便於除錯和重現。
HF_HUB_OFFLINE
如果設定，將不會向 Hugging Face Hub 發起 HTTP 呼叫。如果您嘗試下載檔案，將僅訪問快取的檔案。如果沒有檢測到快取檔案，則會引發錯誤。如果您的網路速度很慢且您不關心是否擁有檔案的最新版本，這很有用。
如果設定了環境變數 HF_HUB_OFFLINE=1，並且您呼叫了 HfApi 的任何方法，則會引發 OfflineModeIsEnabled 異常。
注意：即使檔案的最新版本已快取，呼叫 hf_hub_download 仍會觸發 HTTP 請求以檢查是否有新版本可用。設定 HF_HUB_OFFLINE=1 將跳過此呼叫，從而加快載入時間。
如果您想檢查離線模式是否已啟用，可以使用 is_offline_mode() 輔助函式。
HF_HUB_DISABLE_IMPLICIT_TOKEN
對於向 Hub 發出的每個請求，身份驗證都不是強制性的。例如，請求有關 "gpt2" 模型的資訊不需要身份驗證。然而，如果使用者已登入，預設行為將是始終傳送令牌，以便在訪問私有或門控儲存庫時改善使用者體驗（不會出現 HTTP 401 Unauthorized 錯誤）。出於隱私考慮，您可以設定 HF_HUB_DISABLE_IMPLICIT_TOKEN=1 來停用此行為。在這種情況下，令牌將僅針對“寫入訪問”呼叫（例如：建立提交）傳送。
注意：停用令牌的隱式傳送可能會產生奇怪的副作用。例如，如果您想列出 Hub 上的所有模型，您的私有模型將不會被列出。您需要在指令碼中顯式傳遞 token=True 引數。
HF_HUB_DISABLE_PROGRESS_BARS
對於耗時的任務，huggingface_hub 預設顯示進度條（使用 tqdm）。您可以透過設定 HF_HUB_DISABLE_PROGRESS_BARS=1 一次性停用所有進度條。
HF_HUB_DISABLE_SYMLINKS
如果設定，huggingface_hub 將永遠不會在快取中建立符號連結。相反，檔案將被複制或直接移動到快照目錄中。這是一個高階使用者功能，會導致快取目錄以降級模式執行，巨大的檔案最終會在您的硬碟上重複出現。
一個示例用例是當共享網路驅動器（例如 NAS）用作跨不同作業系統機器的 HF_HUB_CACHE 時。在 Linux 上建立的符號連結並不總是在 Windows 上可遍歷，從而導致錯誤。設定 HF_HUB_DISABLE_SYMLINKS=1 可以避免此問題，但代價是失去了磁碟空間去重功能。
HF_HUB_DISABLE_SYMLINKS_WARNING
如果您在 Windows 機器上，建議啟用開發人員模式或以管理員模式執行 huggingface_hub。否則，huggingface_hub 將無法在您的快取系統中建立符號連結。您將能夠執行任何指令碼，但使用者體驗會下降，因為一些巨大的檔案可能會最終在您的硬碟上重複出現。系統會觸發警告訊息以通知您此行為。設定 HF_HUB_DISABLE_SYMLINKS_WARNING=1 以停用此警告。
有關更多詳細資訊，請參閱 快取限制。
HF_HUB_DISABLE_EXPERIMENTAL_WARNING
huggingface_hub 的某些功能是實驗性的。這意味著您可以使用它們，但我們不保證它們會在未來得到維護。特別是，我們可能會在沒有任何棄用週期的情況下更新此類功能的 API 或行為。使用實驗性功能時會觸發警告訊息以提醒您。如果您樂於除錯使用實驗性功能可能出現的任何潛在問題，可以設定 HF_HUB_DISABLE_EXPERIMENTAL_WARNING=1 以停用該警告。
如果您正在使用實驗性功能，請告知我們！您的反饋可以幫助我們設計和改進它。
HF_HUB_DISABLE_TELEMETRY
預設情況下，HF 庫（transformers、datasets、gradio 等）會收集一些資料，以監控使用情況、除錯問題並幫助確定功能優先順序。每個庫定義其自己的策略（即監控哪些使用情況），但核心實現發生在 huggingface_hub 中（請參閱 send_telemetry）。
您可以設定 HF_HUB_DISABLE_TELEMETRY=1 作為環境變數來全域性停用遙測。
HF_HUB_DISABLE_UPDATE_CHECK
預設情況下，hf CLI 會在啟動時（最多每 24 小時一次）檢查 PyPI 是否有更新的版本，並在有可用版本時向 stderr 列印一行黃色警告，建議使用 hf update。對於開發版本和預釋出版本，該檢查已是一個空操作。
設定 HF_HUB_DISABLE_UPDATE_CHECK=1 以跳過 PyPI 請求並完全關閉該警告。這在離線 CI 環境中或當您更喜歡更安靜的 Shell 輸出時非常有用。
HF_HUB_DISABLE_XET
設定此項以停用 hf-xet 的使用，即使它在您的 Python 環境中可用。這是因為如果發現 hf-xet，它會被自動使用，此設定允許顯式停用其使用。如果您要停用 Xet，請考慮提交一個 issue 幷包含診斷資訊，以幫助我們瞭解為什麼 Xet 不適合您。
HF_HUB_ENABLE_HF_TRANSFER
這是一個已棄用的環境變數。現在 Hugging Face Hub 完全由 Xet 儲存後端提供支援，所有檔案傳輸都透過
hf-xet二進位制包進行。它使用基於塊的去重策略提供高效傳輸，並與huggingface_hub無縫整合。這意味著hf_transfer不能再使用了。如果您對更高的效能感興趣，請檢視HF_XET_HIGH_PERFORMANCE部分。
HF_XET_HIGH_PERFORMANCE
設定 hf-xet 以使用增強的設定進行操作，從而最大化機器上的網路和磁碟資源。啟用高效能模式將嘗試佔滿此機器的網路頻寬，並利用所有 CPU 核心進行並行上傳/下載活動。
可以將此視為類似於舊的 HF_HUB_ENABLE_HF_TRANSFER=1 環境變數，但應用於 hf-xet。
要了解有關 Xet 儲存和 hf_xet 的好處的更多資訊，請參考此 部分。
HF_XET_RECONSTRUCT_WRITE_SEQUENTIALLY
使 hf-xet 按順序寫入本地磁碟，而不是並行寫入。hf-xet 專為 SSD/NVMe 磁碟設計（使用具有直接定址的並行寫入）。如果您使用的是 HDD（機械硬碟），設定此項將把磁碟寫入更改為順序寫入而不是並行寫入。對於較慢的機械硬碟，這可以提高整體寫入效能，因為磁碟不需要為了尋找並行寫入而轉動。
已棄用的環境變數
為了標準化 Hugging Face 生態系統中的所有環境變數，一些變數已被標記為已棄用。儘管它們仍然起作用，但它們不再優先於它們的替代品。下表列出了已棄用的變數及其相應的替代方案：
| 已棄用的變數 | 替代變數 |
|---|---|
HUGGINGFACE_HUB_CACHE | HF_HUB_CACHE |
HUGGINGFACE_ASSETS_CACHE | HF_ASSETS_CACHE |
HUGGING_FACE_HUB_TOKEN | HF_TOKEN |
來自外部工具
有些環境變數並非 huggingface_hub 特有，但在設定時仍會被考慮在內。
DO_NOT_TRACK
布林值。等同於 HF_HUB_DISABLE_TELEMETRY。當設定為 true 時，Hugging Face Python 生態系統（transformers、diffusers、gradio 等）中的遙測功能將被全域性停用。有關更多詳細資訊，請參閱 https://consoledonottrack.com/。
NO_COLOR
布林值。設定後，hf CLI 將不會列印任何 ANSI 顏色。請參閱 no-color.org。
XDG_CACHE_HOME
僅在未設定 HF_HOME 時使用！
這是在 Linux 機器上配置使用者特定的非必要（快取）資料應寫入何處的預設方式。
如果未設定 HF_HOME，則預設主目錄將為 "$XDG_CACHE_HOME/huggingface"，而不是 "~/.cache/huggingface"。