Hub Python 库文档

环境变量

Hugging Face's logo
加入 Hugging Face 社区

并获得增强型文档体验

开始使用

环境变量

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_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 秒。

布尔值

以下环境变量期望布尔值。如果变量的值是 {"1", "ON", "YES", "TRUE"} 中的一个(不区分大小写),则该变量将被视为 True。任何其他值(或未定义)将被视为 False

HF_HUB_OFFLINE

如果设置,则不会向 Hugging Face Hub 发出任何 HTTP 调用。如果您尝试下载文件,则只会访问缓存的文件。如果未检测到缓存文件,则会引发错误。这在您的网络速度缓慢并且您不关心文件是否为最新版本时非常有用。

如果将 HF_HUB_OFFLINE=1 设置为环境变量,并且您调用了 HfApi 的任何方法,则会引发 OfflineModeIsEnabled 异常。

注意:即使文件的最新版本已缓存,调用 hf_hub_download 仍会触发 HTTP 请求以检查是否有新版本可用。设置 HF_HUB_OFFLINE=1 将跳过此调用,从而加快您的加载时间。

并非所有对 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 库(transformersdatasetsgradio 等)会收集一些数据以监控使用情况、调试问题并帮助确定功能的优先级。每个库都定义了自己的策略(即监控哪些使用情况),但核心实现发生在huggingface_hub中(参见send_telemetry)。

您可以将HF_HUB_DISABLE_TELEMETRY=1设置为环境变量以全局禁用遥测。

HF_HUB_ENABLE_HF_TRANSFER

设置为True,以便使用hf_transfer更快地上传和下载 Hub 中的文件。

默认情况下,huggingface_hub使用基于 Python 的requests.getrequests.post函数。虽然这些函数可靠且用途广泛,但对于具有高带宽的机器来说,它们可能不是最有效的选择。hf_transfer 是一个基于 Rust 的软件包,旨在通过将大型文件分成较小的部分并使用多个线程同时传输它们来最大化带宽使用率。这种方法可以使传输速度提高一倍。要使用hf_transfer

  1. 安装huggingface_hub时指定hf_transfer扩展(例如pip install huggingface_hub[hf_transfer])。
  2. HF_HUB_ENABLE_HF_TRANSFER=1设置为环境变量。

请注意,使用hf_transfer存在某些限制。由于它不是纯基于 Python 的,因此调试错误可能具有挑战性。此外,hf_transfer缺少一些用户友好的功能,例如可恢复下载和代理。这些遗漏是为了保持 Rust 逻辑的简单性和速度而故意为之。因此,hf_transferhuggingface_hub中默认未启用。

已弃用的环境变量

为了标准化 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 生态系统(transformersdiffusersgradio 等)中的遥测将被全局禁用。有关更多详细信息,请参阅https://consoledonottrack.com/

NO_COLOR

布尔值。设置后,huggingface-cli工具将不会打印任何 ANSI 颜色。请参阅no-color.org

XDG_CACHE_HOME

仅当未设置 HF_HOME 时使用!

这是在 Linux 机器上配置用户特定非必要(缓存)数据写入位置的默认方式。此处查看详情

如果未设置 HF_HOME,则默认主目录将为 "$XDG_CACHE_HOME/huggingface" 而不是 "~/.cache/huggingface"

< > 在 GitHub 上更新