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"。