Hub Python 庫文件
環境變數
並獲得增強的文件體驗
開始使用
環境變數
huggingface_hub 可以透過環境變數進行配置。
如果您不熟悉環境變數，這裡有一些關於它們的通用文章，分別在 macOS 和 Linux 上以及在 Windows 上。
本頁面將引導您瞭解所有特定於 huggingface_hub 的環境變數及其含義。
通用
HF_INFERENCE_ENDPOINT
用於配置推理 API 的基礎 URL。如果您的組織指向 API 閘道器而不是直接指向推理 API，您可能需要設定此變數。
預設為 "https://api-inference.huggingface.co"。
HF_HOME
用於配置 huggingface_hub 本地儲存資料的位置。特別是，您的令牌和快取將儲存在此資料夾中。
預設為 "~/.cache/huggingface"，除非設定了 XDG_CACHE_HOME。
HF_HUB_CACHE
用於配置從 Hub 下載的倉庫（模型、資料集和 Spaces）將在本地快取。
預設為 "$HF_HOME/hub"（預設情況下例如 "~/.cache/huggingface/hub"）。
HF_XET_CACHE
用於配置 Xet 塊（由 Xet 後端管理的檔案的位元組範圍）在本地快取。
預設為 "$HF_HOME/xet"（預設情況下例如 "~/.cache/huggingface/xet"）。
HF_ASSETS_CACHE
用於配置下游庫建立的 資產 將在本地快取。這些資產可以是預處理資料、從 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
如果設定了此變數，將不會進行任何 HTTP 呼叫到 Hugging Face Hub。如果您嘗試下載檔案，將只訪問快取的檔案。如果未檢測到快取檔案，將引發錯誤。當您的網路速度慢且您不關心獲取檔案的最新版本時，此功能很有用。
如果將 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_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_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_VERBOSITY | HF_HUB_VERBOSITY |
來自外部工具
一些環境變數不特定於 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"。