🤗 Transformers 安装与离线运行完全指南：pip / 源码 / conda 安装、缓存配置与离线模式实践

本指南以当前仓库 docs/source/ko/installation.md 为骨架，系统讲解 🤗 Transformers 在 Python 3.10+ 环境下的四种安装方式（pip、源码、可编辑安装、conda）、模型缓存目录的配置优先级，以及如何通过环境变量进入离线模式、预先下载模型文件实现无网络运行。读完本文，你将掌握从零搭建 🤗 Transformers 开发/运行环境、管理本地模型缓存、并在防火墙或完全离线的机器上稳定运行推理与训练脚本的完整实战方案。

环境要求：Python 3.10+ 与深度学习框架

🤗 Transformers 在当前仓库中针对 Python 3.10+ 与 PyTorch 2.4+ 进行了测试。这一版本范围可以直接在仓库的 setup.py 中得到印证：

SUPPORTED_PYTHON_VERSIONS = (10, 14)  # 3.10 to 3.14

setup.py 会基于该常量自动生成 python_requires=f">=3.{min_version}.0"（参见 setup.py），即最低要求 Python 3.10。因此，在开始安装之前，请先确认本机 Python 版本，并准备好对应的深度学习框架（如 PyTorch），具体安装方式请参考 PyTorch 等框架的官方安装指引。注意：仅安装 transformers 本身是不够的，实际运行模型还需要 torch 等后端，这点在下一节的 transformers[torch] 安装方式中会进一步体现。

使用 pip 安装

创建并激活虚拟环境

官方强烈建议将 🤗 Transformers 安装在 Python 虚拟环境 中。虚拟环境可以隔离不同项目的依赖，避免依赖冲突，也便于整体清理。首先在项目目录下创建虚拟环境：

python -m venv .env

激活虚拟环境（Linux / macOS）：

source .env/bin/activate

激活虚拟环境（Windows）：

.env/Scripts/activate

安装 transformers 本体

激活虚拟环境后，执行安装：

pip install transformers

如果只需要 CPU 环境，可以使用一行命令同时安装 🤗 Transformers 与对应的深度学习库。例如，同时安装 PyTorch：

pip install transformers[torch]

这种"extra"安装方式确保 transformers 与 torch 的版本兼容性由 pip 一并解析，省去手动对齐依赖的麻烦。

验证安装是否成功

安装完成后，运行下面这行命令验证：它会下载一个预训练的情感分析模型并执行推理：

python -c "from transformers import pipeline; print(pipeline('sentiment-analysis')('we love you'))"

如果输出类似下面的标签与分数，说明安装成功：

[{'label': 'POSITIVE', 'score': 0.9998704791069031}]

提示：首次运行该命令会从 Hugging Face Hub 下载模型文件并写入本地缓存，因此需要网络连接；具体缓存位置与配置方法见下文"缓存配置"小节。

从源码安装（main 分支）

如果想使用最新开发中的功能，可以从源码安装：

pip install git+https://github.com/huggingface/transformers

这条命令安装的是实验性较强的 main 分支（而非稳定的 stable 版本）。main 分支适合希望紧跟开发进度、及时获得最新修复的用户——例如，某个在最近一次正式发布之后才被修复的 bug，可能还没有进入新版本，但在 main 中已经可用。

需要提醒的是，main 分支并不保证稳定。官方会在 main 分支上尽量保持可用，绝大多数问题通常几小时到一天内就会得到修复；如果遇到问题，可以在官方 Issue 中报告以加速解决。

安装完成后同样可以验证：

python -c "from transformers import pipeline; print(pipeline('sentiment-analysis')('I love you'))"

可编辑安装（适合贡献者与源码调试）

以下两种场景建议使用可编辑安装（editable install）：

• 希望直接使用 main 分支源码；
• 希望为 🤗 Transformers 贡献代码，并在修改后立即测试效果。

做法是先克隆仓库，再以可编辑模式安装：

git clone https://github.com/huggingface/transformers.git
cd transformers
pip install -e .

这条命令会把克隆下来的源码目录与 Python 库搜索路径关联起来：Python 在导入 transformers 时，除了常规库目录（例如 ~/anaconda3/envs/main/lib/python3.10/site-packages/），还会去克隆目录（例如 ~/transformers/）中查找。

⚠️ 警告：以可编辑模式安装后，必须保留 transformers 源码目录，否则 Python 将无法再导入该库。

可编辑安装的另一个好处是更新方便——拉取最新代码即可：

cd ~/transformers/
git pull

重新启动 Python 环境后，就会加载更新后的 main 版本代码。

使用 conda 安装

如果使用 conda 管理环境，可以从 conda-forge 渠道安装：

conda install conda-forge::transformers

注意：conda 安装的 transformers 版本更新可能滞后于 pip，且同样需要另外安装 PyTorch 等深度学习框架。

缓存配置：预训练模型与文件的本地存储

预训练模型下载后默认缓存在本地路径 ~/.cache/huggingface/hub（Windows 下为 C:\Users\username\.cache\huggingface\hub）。这是环境变量 HF_HUB_CACHE 的默认目录。可以通过以下 shell 环境变量（按优先级从高到低）自定义缓存位置：

1. HF_HUB_CACHE（shell 环境变量，最高优先级，直接指定缓存目录）
2. HF_HOME（指定 huggingface 相关文件的根目录）
3. XDG_CACHE_HOME + /huggingface（遵循 XDG 目录规范时的兜底路径）

从当前仓库源码看，缓存机制由 huggingface_hub 库的常量驱动：src/transformers/utils/hub.py 中通过 from huggingface_hub import constants 引用 constants.HF_HOME、constants.HF_HUB_CACHE 等值（参见 hub.py），并在 hub.py 中以 constants.HF_HOME 为基础派生 HF_MODULES_CACHE（用于存放动态模块/自定义代码）：

HF_MODULES_CACHE = os.getenv("HF_MODULES_CACHE", os.path.join(constants.HF_HOME, "modules"))

这意味着调整 HF_HOME 不仅会影响模型权重缓存，也会连带影响 transformers_modules 等动态模块的存放位置。如果需要把缓存整体迁移到磁盘空间更大的目录（例如挂载的大容量数据盘），优先设置 HF_HOME 即可统一生效。

离线模式：让 Transformers 只使用本地文件

在防火墙隔离或完全离线的环境中，可以设置环境变量 HF_HUB_OFFLINE=1，让 🤗 Transformers 只检索本地文件，不再发起任何网络请求。

若离线训练流程中还用到 🤗 Datasets，可同时设置 HF_DATASETS_OFFLINE=1。

这一行为在源码层面有明确支撑：src/transformers/utils/hub.py 的 cached_file 等下载路径会调用 is_offline_mode() 进行判断，一旦检测到离线模式，会强制将 local_files_only 置为 True（参见 hub.py）：

if is_offline_mode() and not local_files_only:
    logger.info("Offline mode: forcing local_files_only=True")
    local_files_only = True

is_offline_mode 正是由 huggingface_hub 根据 HF_HUB_OFFLINE 等环境变量判定（见 hub.py 的导入）。

实际使用示例：联网机器与离线机器

在带防火墙的常规网络上，通常这样运行翻译脚本（见 run_translation.py）：

python examples/pytorch/translation/run_translation.py --model_name_or_path google-t5/t5-small --dataset_name wmt16 --dataset_config ro-en ...

同样的脚本放到离线机器上，只需在前面加上两个环境变量：

HF_DATASETS_OFFLINE=1 HF_HUB_OFFLINE=1 \
python examples/pytorch/translation/run_translation.py --model_name_or_path google-t5/t5-small --dataset_name wmt16 --dataset_config ro-en ...

此时脚本只会搜索本地文件，不会因网络超时或中断而长时间卡住，能够稳定跑完。

离线前准备：预先下载模型与分词器

另一种离线使用方案是：提前下载好所有需要的文件，离线时直接指定本地路径加载。共有三种方式：

方式一：通过 Model Hub 网页下载

在 Model Hub 模型页面点击下载（↓）图标，手动下载模型仓库中的文件到本地。

方式二：使用 from_pretrained / save_pretrained 工作流

1. 在联网机器上，先用 PreTrainedModel.from_pretrained 下载模型与分词器：

>>> from transformers import AutoTokenizer, AutoModelForSeq2SeqLM

>>> tokenizer = AutoTokenizer.from_pretrained("bigscience/T0_3B")
>>> model = AutoModelForSeq2SeqLM.from_pretrained("bigscience/T0_3B")

2. 再用 PreTrainedModel.save_pretrained 将文件保存到指定目录：

>>> tokenizer.save_pretrained("./your/path/bigscience_t0")
>>> model.save_pretrained("./your/path/bigscience_t0")

3. 离线时，用 PreTrainedModel.from_pretrained 从本地路径直接加载：

>>> tokenizer = AutoTokenizer.from_pretrained("./your/path/bigscience_t0")
>>> model = AutoModel.from_pretrained("./your/path/bigscience_t0")

提示：from_pretrained 同时支持 Hub 仓库 ID（如 "bigscience/T0_3B"）与本地目录路径，正是这一双模式设计让"在线下载、离线加载"成为可能；该能力由仓库中 PreTrainedModel 的底层加载逻辑统一提供（可参考 modeling_utils.py 中对应的实现）。

方式三：使用 huggingface_hub 库按文件下载

1. 先安装 huggingface_hub：

python -m pip install huggingface_hub

2. 使用 hf_hub_download 函数将指定文件下载到目标位置。例如，下载 T0 模型的 config.json：

>>> from huggingface_hub import hf_hub_download

>>> hf_hub_download(repo_id="bigscience/T0_3B", filename="config.json", cache_dir="./your/path/bigscience_t0")

hf_hub_download 的 cache_dir 参数可以精确控制文件落盘位置，便于后续批量拷贝到离线机器。

离线加载配置文件的通用做法

文件下载并缓存到本地后，后续只需指定本地路径即可加载。例如加载配置：

>>> from transformers import AutoConfig

>>> config = AutoConfig.from_pretrained("./your/path/bigscience_t0/config.json")

小结

• 安装优先使用虚拟环境 + pip install transformers（CPU 场景可一键 pip install transformers[torch]）；需要最新功能用源码安装，参与开发用可编辑安装，conda 用户用 conda install conda-forge::transformers。
• 模型缓存默认位于 ~/.cache/huggingface/hub，可通过 HF_HUB_CACHE → HF_HOME → XDG_CACHE_HOME/huggingface 的优先级顺序自定义。
• 离线环境设置 HF_HUB_OFFLINE=1（配合 Datasets 再加 HF_DATASETS_OFFLINE=1）即可强制仅使用本地文件；预先用 save_pretrained 或 hf_hub_download 备好模型文件，即可在完全断网的机器上稳定运行。