[特殊字符] Transformers 安装完全指南：pip/conda/源码安装、缓存配置与离线模式

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

【免费下载链接】transformers🤗 Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformers

本文是 🤗 Transformers 框架（当前仓库即其完整源码实现）的安装与运行环境配置指南，内容以 docs/source/fr/installation.md 为骨架，覆盖虚拟环境创建、pip/conda/源码三种安装方式、预训练模型缓存目录的定制，以及完全离线（无网络）环境下的模型加载与训练方案。读完本文，你将能独立完成 🤗 Transformers 在各种深度学习框架（如 PyTorch）下的环境搭建，并掌握在隔离网络中部署推理或训练任务的关键技巧。

环境前提

🤗 Transformers 支持与主流深度学习库配合使用（PyTorch、TensorFlow、JAX 等），当前仓库要求Python 3.10+，且与 PyTorch 的适配基线为PyTorch 2.4+（仓库 setup.py 中extras["torch"]对应的 torch 依赖声明为torch>=2.5，可据此确认新版对 PyTorch 的兼容要求）。

在动手安装之前，建议先为所选的深度学习框架准备好其自身的安装环境（例如 PyTorch 需要根据 CUDA 版本选择对应的安装命令），🤗 Transformers 只是叠加在其之上的模型定义与调用层。

使用 pip 安装

1. 创建并激活虚拟环境

强烈建议在虚拟环境中安装 🤗 Transformers，这样可以在不同项目之间隔离依赖版本，避免包冲突。先在项目工作目录下创建虚拟环境：

python -m venv .env

激活虚拟环境，Linux/macOS：

source .env/bin/activate

Windows：

.env/Scripts/activate

2. 安装 🤗 Transformers

激活环境后即可安装：

pip install transformers

如果仅用于 CPU 推理/训练，可以一条命令同时安装 🤗 Transformers 与所选深度学习库。例如同时安装 PyTorch：

pip install 'transformers[torch]'

这里的[torch]是仓库 setup.py 中定义的安装扩展（extras）之一，其内容为deps_list("torch", "accelerate")，即会额外带入torch与accelerate依赖。setup.py 中还提供了其他常用 extras，例如：

• transformers[vision]：引入torchvision与Pillow，用于视觉模型；
• transformers[audio]：引入torchaudio、librosa、pyctcdecode、phonemizer等音频处理依赖；
• transformers[sentencepiece]：引入sentencepiece与protobuf，用于基于 SentencePiece 的分词器；
• transformers[tiktoken]：引入tiktoken，用于 GPT-4 风格的分词器；
• transformers[deepspeed]：引入deepspeed与accelerate，用于大规模分布式训练；
• transformers[serving]：引入openai、pydantic、uvicorn、fastapi等，用于搭建推理服务。

按需组合即可，例如同时安装 PyTorch 与视觉依赖：pip install 'transformers[torch,vision]'。

3. 验证安装

执行下面的命令验证安装是否成功。该命令会从 Hub 下载一个预训练情感分析模型并立即推理：

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

正常输出如下（label 与 score 可能随模型版本略有浮动）：

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

这条命令同时验证了三件事：库本身可导入、Hub 网络可达、预训练模型可以正常下载与加载。

从源码安装（main 分支）

如果需要使用最新开发版（例如某个 bug 已在main分支修复但尚未发布正式版本），可以直接从源码安装：

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

需要注意：

• 该命令安装的是main分支版本，而非最新稳定版；
• main分支持续集成新功能，不保证总是稳定。项目尽力保持其可用性，多数问题通常在几小时到一天内被修复；
• 若在使用main分支时遇到问题，可以在 GitHub 上提交 Issue 以便尽快解决。

安装完成后同样可以用 pipeline 快速验证：

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 .

原理说明：pip install -e .会在 Python 的 site-packages 中建立指向克隆目录的链接。此后 Python 解释器查找transformers包时，除了常规的包安装目录（例如~/anaconda3/envs/main/lib/python3.10/site-packages/），还会直接使用克隆目录~/transformers/中的源码。这意味着你对克隆目录的每次修改，在下一次运行 Python 时都会生效，非常适合源码调试与贡献开发。

⚠️重要提醒：可编辑安装后，必须保留克隆下来的transformers目录，否则库将无法使用。

之后随时可以用 git 拉取最新代码更新本地版本：

cd ~/transformers/ git pull

下次运行 Python 时，环境会自动使用更新后的main分支代码。

使用 conda 安装

通过 conda 的conda-forge频道安装：

conda install conda-forge::transformers

conda 安装适合希望由 conda 统一管理包依赖（尤其是同时管理 CUDA 相关库）的场景。

配置模型缓存目录

预训练模型默认下载并缓存在本地目录~/.cache/huggingface/hub（Windows 下为C:\Users\<用户名>\.cache\huggingface\hub）。该路径由环境变量HF_HUB_CACHE控制。如需自定义缓存位置，可按以下优先级设置环境变量（高优先级覆盖低优先级）：

1. HF_HUB_CACHE（环境变量，默认即使用它）；
2. HF_HOME；
3. XDG_CACHE_HOME+/huggingface。

从源码层面看，缓存目录的解析逻辑集中在 src/transformers/utils/hub.py 与相关常量定义中：HF_HOME被作为最高层级的用户目录配置（注释中明确指出 "The best way to set the cache path is with the environment variable HF_HOME"），在其之下派生HF_MODULES_CACHE（存放动态加载的自定义模块）等子目录；同时 modeling_utils.py 在模型加载时会通过constants.HF_HUB_CACHE获取默认缓存路径。因此：

• 只想挪动模型缓存：设置HF_HUB_CACHE；
• 想统一管理 HF 生态（模型缓存、模块缓存、token 等）的所有本地文件：设置HF_HOME；
• 遵循 Linux 桌面约定：设置XDG_CACHE_HOME（最终缓存落在$XDG_CACHE_HOME/huggingface下）。

离线模式（Offline Mode）

1. 一键开启完全离线

🤗 Transformers 可以在隔离/无网络环境中仅使用本地文件运行。设置环境变量HF_HUB_OFFLINE=1即可开启离线模式。

如果训练流程还依赖 🤗 Datasets，可一并设置HF_DATASETS_OFFLINE=1，让数据集下载同样走离线逻辑：

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 ...

开启后，脚本将直接从本地缓存读取模型与数据集，不会尝试访问 Hub，因此不会因网络不可达而长时间挂起或等待超时。这个机制在代码中也有印证：is_offline_mode()检测到离线环境时，hub.py 中的下载逻辑会跳过网络请求而回退到本地缓存。

2. 强制只使用本地文件：local_files_only

另一个更精细的做法是通过from_pretrained的local_files_only参数，让加载过程只读取本地文件：

from transformers import T5Model model = T5Model.from_pretrained("./path/to/local/directory", local_files_only=True)

在 modeling_utils.py 的from_pretrained实现中，local_files_only=True会被透传到下载解析逻辑，禁止任何形式的网络访问；此外当检测到离线模式（is_offline_mode()）时，代码会自动将local_files_only强制置为True，保证离线环境下不会触发网络请求。

3. 预先下载模型/分词器供离线使用

除了直接使用缓存目录，更可控的做法是提前下载文件、保存到指定目录，之后在离线环境下加载本地路径。有三种途径：

途径 A：通过 Model Hub 网页手动下载

在 Model Hub 的模型页面点击下载图标（↓），手动保存模型文件到本地目录。

途径 B：用from_pretrained+save_pretrained下载并导出

先在联网环境下载并保存到指定目录：

>>> from transformers import AutoTokenizer, AutoModelForSeq2SeqLM >>> tokenizer = AutoTokenizer.from_pretrained("bigscience/T0_3B") >>> model = AutoModelForSeq2SeqLM.from_pretrained("bigscience/T0_3B")

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

离线后再从本地目录加载：

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

途径 C：用huggingface_hub的hf_hub_download精确下载

先在虚拟环境中安装huggingface_hub：

python -m pip install huggingface_hub

然后精确下载某个文件到指定缓存目录。例如下载 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")

文件下载并缓存到本地后，即可用本地路径加载配置：

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

综合建议

• 常规使用：优先pip install transformers稳定版，并在虚拟环境中管理依赖；
• 尝鲜新特性/修复：从源码安装main分支；
• 贡献代码：使用git clone+pip install -e .可编辑安装；
• 生产/离线环境：预先设置HF_HUB_CACHE（或HF_HOME）指向固定缓存目录，配合HF_HUB_OFFLINE=1与local_files_only=True，实现完全脱离网络的模型加载与训练，具体离线训练示例可参考仓库中的 run_translation.py 脚本的调用方式。

【免费下载链接】transformers🤗 Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformers