環境變數

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 下載的程式碼倉庫（模型、資料集和空間）在本地的快取位置。

預設為 "$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_LOCAL_DIR_AUTO_SYMLINK_THRESHOLD

此環境變數已被棄用，現在被 huggingface_hub 忽略。下載檔案到本地目錄不再依賴於符號連結。

HF_HUB_ETAG_TIMEOUT

整數值，用於定義在下載檔案前從程式碼倉庫獲取最新元資料時等待伺服器響應的秒數。如果請求超時，huggingface_hub 將預設使用本地快取的檔案。設定較低的值可以加快已經快取檔案的機器的工作流程。較高的值可以保證元資料呼叫在更多情況下成功。預設為 10 秒。

HF_HUB_DOWNLOAD_TIMEOUT

整數值，用於定義下載檔案時等待伺服器響應的秒數。如果請求超時，將引發 TimeoutError。對於連線速度慢的機器，設定較高的值是有益的。較小的值可以在網路完全中斷的情況下更快地使程序失敗。預設為 10 秒。

Xet

其他 Xet 環境變數

HF_XET_CHUNK_CACHE_SIZE_BYTES

用於在本地設定 Xet 資料塊快取的大小。增加此值將為從 S3 獲取的術語/資料塊提供更多快取空間。更大的快取可以更好地利用跨程式碼倉庫和檔案的重複資料刪除。如果你的網路速度遠大於本地磁碟速度（例如 10Gbps 與 SSD 或更差），則可以考慮停用 Xet 快取以提高效能。要停用 Xet 快取，請設定 HF_XET_CHUNK_CACHE_SIZE_BYTES=0。

預設為 10000000000（10GB）。

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 將跳過此呼叫，從而加快你的載入時間。

HF_HUB_DISABLE_IMPLICIT_TOKEN

並非所有對 Hub 的請求都需要身份驗證。例如，請求有關 "gpt2" 模型的詳細資訊就不需要進行身份驗證。但是，如果使用者已經登入，預設行為是始終傳送令牌，以便在訪問私有或受限程式碼倉庫時簡化使用者體驗（永遠不會收到 HTTP 401 未授權錯誤）。出於隱私考慮，你可以透過設定 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 如果被找到就會自動使用，這個設定允許明確停用其使用。

HF_HUB_ENABLE_HF_TRANSFER

設定為 True 可使用 hf_transfer 加快從 Hub 的上傳和下載速度。

預設情況下，huggingface_hub 使用基於 Python 的 requests.get 和 requests.post 函式。雖然這些函式可靠且通用，但對於高頻寬的機器來說可能不是最高效的選擇。hf_transfer 是一個基於 Rust 開發的包，透過將大檔案分成小部分並使用多個執行緒同時傳輸來最大化頻寬利用率。這種方法可能將傳輸速度提高一倍。要使用 hf_transfer

在安裝 huggingface_hub 時指定 hf_transfer 額外依賴（例如 pip install huggingface_hub[hf_transfer]）。
將 HF_HUB_ENABLE_HF_TRANSFER=1 設定為環境變數。

請注意，使用 hf_transfer 存在一些限制。因為它不是純 Python 的，除錯錯誤可能會有挑戰性。此外，hf_transfer 缺少一些使用者友好的功能，如可續傳下載和代理。這些省略是有意的，以保持 Rust 邏輯的簡單性和速度。因此，hf_transfer 在 huggingface_hub 中不是預設啟用的。

hf_xet 是 hf_transfer 的替代品。它透過基於資料塊的重複資料刪除策略、自定義 Xet 儲存（替代 Git LFS）以及與 huggingface_hub 的無縫整合，提供高效的檔案傳輸。

瞭解更多關於這個包的資訊並透過 pip install "huggingface_hub[hf_xet]" 啟用。

HF_XET_HIGH_PERFORMANCE

將 hf-xet 設定為以增強的設定執行，以最大化機器上的網路和磁碟資源。啟用高效能模式將嘗試飽和此機器的網路頻寬，並利用所有 CPU 核心進行並行上傳/下載活動。可以認為這與使用 hf-xet 上傳/下載到 Xet 儲存後端時設定 HF_HUB_ENABLE_HF_TRANSFER=True 類似。

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 命令列介面將不會列印任何 ANSI 顏色。參見 no-color.org。

XDG_CACHE_HOME

僅在未設定 HF_HOME 時使用！

這是在 Linux 機器上配置使用者特定的非必要（快取）資料應寫入位置的預設方式。

如果未設定 HF_HOME，預設主目錄將是 "$XDG_CACHE_HOME/huggingface" 而不是 "~/.cache/huggingface"。

< > 在 GitHub 上更新

Hub Python 庫