Transformers documentation

环境变量

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

环境变量

布尔变量接受 1、on、yes 或 true(不区分大小写)。其他任何值,包括未设置,均为 false。

这些变量中的大多数在导入 Transformers 时只会被读取一次。请在启动 Python 之前通过 shell 设置它们,或者在导入之前使用 os.environ 进行设置。之后修改这些变量将不会生效。

TRANSFORMERS_VERBOSITY=info python run.py

缓存和 Hub 访问由 huggingface_hub 拥有的 HF_* 变量进行配置,例如 HF_HOME 和 HF_HUB_OFFLINE。有关离线工作流,请参阅 Installation。

日志

Transformers 的日志级别为 warning。Logging 记录了等效的 Python API,包括 logging.set_verbosity()。

变量值描述
TRANSFORMERS_VERBOSITYdetail, debug, info, warning, error, critical库日志级别。detail 与 debug 相同,但会在每条消息中附加文件名和行号。无法识别的值会发出警告并回退到 warning。
TRANSFORMERS_NO_ADVISORY_WARNINGSboolean静默建议性警告,即那些不表示存在问题的最佳实践提示。

模型加载

默认情况下,检查点分片会并行加载。

变量值描述
HF_DEACTIVATE_ASYNC_LOADboolean在主线程上加载分片,而不是使用线程池。速度较慢,但峰值内存更容易评估。当 device_map 将数据卸载到磁盘或进行即时量化时,加载本身已经是顺序执行的,因此该选项仅影响原本并行的加载过程。
DISABLE_SAFETENSORS_CONVERSIONboolean阻止 Transformers 向 Hub 转换机器人请求仅包含 PyTorch .bin 权重的仓库的 safetensors 版本。建议在 CI 中设置此项,因为该请求会增加延迟并导致网络不稳定。

内核与后端

当安装 kernels 且硬件支持时,优化内核会从 Hub 下载。若要排查数值差异或崩溃问题,请禁用它们。

变量值描述
USE_HUB_KERNELS布尔值,默认启用将其设置为 false 值,以回退到参考实现。
TRANSFORMERS_DISABLE_DEEPGEMM_LINEAR1在细粒度 FP8 量化中,强制 FP8 线性层使用 Triton 回退方案,而不是 DeepGEMM。
TRANSFORMERS_DISABLE_TORCH_CHECK1在导入时跳过最低 PyTorch 版本检查。
TRANSFORMERS_SDPA_FORCE_GQA1强制 PyTorch SDPA 对分组查询注意力使用 enable_gqa=True。否则,Transformers 会在设置 enable_gqa=True 和重复键/值头之间进行选择。

TRANSFORMERS_DISABLE_TORCH_CHECK 移除的是一项防护机制,而非改变行为。在不受支持的 PyTorch 版本上,你将遇到导入错误或静默产生错误结果,而不是收到清晰的提示信息。

Update on GitHub