Transformers documentation
环境变量
快速入门
基类
模型
预处理器
推理
Pipeline API
生成 API
优化
与模型对话
服务
训练
硬件
量化
生态系统集成
资源
API
环境变量
布尔变量接受 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_VERBOSITY | detail, debug, info, warning, error, critical | 库日志级别。detail 与 debug 相同,但会在每条消息中附加文件名和行号。无法识别的值会发出警告并回退到 warning。 |
TRANSFORMERS_NO_ADVISORY_WARNINGS | boolean | 静默建议性警告,即那些不表示存在问题的最佳实践提示。 |
模型加载
默认情况下,检查点分片会并行加载。
| 变量 | 值 | 描述 |
|---|---|---|
HF_DEACTIVATE_ASYNC_LOAD | boolean | 在主线程上加载分片,而不是使用线程池。速度较慢,但峰值内存更容易评估。当 device_map 将数据卸载到磁盘或进行即时量化时,加载本身已经是顺序执行的,因此该选项仅影响原本并行的加载过程。 |
DISABLE_SAFETENSORS_CONVERSION | boolean | 阻止 Transformers 向 Hub 转换机器人请求仅包含 PyTorch .bin 权重的仓库的 safetensors 版本。建议在 CI 中设置此项,因为该请求会增加延迟并导致网络不稳定。 |
内核与后端
当安装 kernels 且硬件支持时,优化内核会从 Hub 下载。若要排查数值差异或崩溃问题,请禁用它们。
| 变量 | 值 | 描述 |
|---|---|---|
USE_HUB_KERNELS | 布尔值,默认启用 | 将其设置为 false 值,以回退到参考实现。 |
TRANSFORMERS_DISABLE_DEEPGEMM_LINEAR | 1 | 在细粒度 FP8 量化中,强制 FP8 线性层使用 Triton 回退方案,而不是 DeepGEMM。 |
TRANSFORMERS_DISABLE_TORCH_CHECK | 1 | 在导入时跳过最低 PyTorch 版本检查。 |
TRANSFORMERS_SDPA_FORCE_GQA | 1 | 强制 PyTorch SDPA 对分组查询注意力使用 enable_gqa=True。否则,Transformers 会在设置 enable_gqa=True 和重复键/值头之间进行选择。 |
Update on GitHub
TRANSFORMERS_DISABLE_TORCH_CHECK移除的是一项防护机制,而非改变行为。在不受支持的 PyTorch 版本上,你将遇到导入错误或静默产生错误结果,而不是收到清晰的提示信息。