Transformers 安装实战指南：从 uv 虚拟环境到 GPU 加速与离线模式配置

Transformers 是 Hugging Face 出品的大模型框架，覆盖文本、视觉、音频与多模态模型的推理与训练。本文基于仓库官方安装文档 installation.md 与 setup.py 等仓库源码，完整讲解如何在不同硬件环境（CUDA、CPU、Intel XPU、NVIDIA Spark ARM64）下安装 Transformers、如何验证安装、如何从源码或以可编辑模式安装，以及如何配置模型缓存目录与离线运行环境。读完本文，你可以独立完成一套干净、可复现、可离线运行的 Transformers 开发环境。

一、环境前提：Python 与 PyTorch 版本要求

官方文档明确指出：Transformers 与 PyTorch 配合工作，已在 Python 3.10+ 与 PyTorch 2.5+ 上完成测试。这一说法与仓库构建配置一致——setup.py 中定义了支持的 Python 版本范围与 PyTorch 最低版本：

# setup.py
SUPPORTED_PYTHON_VERSIONS = (10, 14)  # 3.10 to 3.14
...
"torch>=2.5",
"python>=3.10.0",

同时 setup.py 生成的 python_requires 为 >=3.10.0。当前仓库中的开发版本号为 5.16.0.dev0（见 src/transformers/init.py）。因此动手安装前请先确认：

• Python 版本在 3.10～3.14 之间；
• 如果使用 NVIDIA GPU，已按 PyTorch 官方指引 装好匹配的 CUDA 驱动。

二、用 uv 创建虚拟环境

官方推荐使用 [uv]（一个基于 Rust 的高性能 Python 包与项目管理器）来管理虚拟环境，它能隔离不同项目的依赖、避免版本冲突。uv 可以作为 pip 的直接替代品——如果你偏好 pip，只需把下文命令中的 uv 去掉即可。

创建并激活一个虚拟环境：

uv venv .env
source .env/bin/activate

三、按硬件选择安装命令

Transformers 的基础安装是 transformers，GPU 场景则通过 extras 语法 transformers[torch] 一并装上 PyTorch 与 accelerate。[torch] 这个 extra 的具体内容可以在 setup.py 中确认：

extras["torch"] = deps_list("torch", "accelerate")  # torch>=2.5, accelerate>=1.1.0

文档给出了四种典型场景，下面逐一说明。

1. NVIDIA GPU（CUDA）

先确认系统能检测到 NVIDIA GPU：

nvidia-smi

然后安装带 torch extra 的 Transformers（CUDA 版的 PyTorch 需要事先按 PyTorch 官方指引装好对应驱动）：

uv pip install "transformers[torch]"

等价的 pip 写法即 README.md 中展示的 pip install "transformers[torch]"。

2. NVIDIA Spark（ARM64 设备）

在运行 ARM64 的 NVIDIA Spark 设备（如 RTX Spark 笔记本）上，PyTorch 需要 NVIDIA 官方的 ARM64 构建，这些 wheel 不在默认 PyPI 索引或标准 PyTorch wheel 索引中，必须从 NVIDIA PyPI 索引安装：

nvidia-smi   # 先确认能检测到 NVIDIA GPU
uv pip install torch --index-url https://pypi.nvidia.com
uv pip install transformers

注意这里的顺序：先固定 PyTorch 来源，再安装 Transformers，避免依赖解析器从默认索引拉取不兼容的 ARM64 版本。

3. 纯 CPU

CPU 版本直接从 PyTorch 官方 CPU wheel 索引安装 torch，再安装 Transformers：

uv pip install torch --index-url https://download.pytorch.org/whl/cpu
uv pip install transformers

4. Intel GPU（XPU）

需要先按 Intel 官方指引安装 XPU 版 PyTorch 驱动，然后用 xpu-smi 确认系统检测到了 Intel GPU，再追加 XPU 索引 URL 安装：

xpu-smi
uv pip install "transformers[torch]" --extra-index-url https://download.pytorch.org/whl/xpu

四、验证安装是否成功

安装完成后，运行下面这条命令做冒烟测试。它会加载一个预训练情感分析模型，对输入文本返回标签与置信度分数：

python -c "from transformers import pipeline; print(pipeline('sentiment-analysis')('hugging face is the best'))"
# 期望输出形如：
# [{'label': 'POSITIVE', 'score': 0.9998704791069031}]

这条命令同时验证了三件事：transformers 包可正常导入、能访问 Hub 下载并缓存模型、pipeline 推理链路完整。如果你看到类似输出，即表示安装成功。

五、从源码安装与可编辑安装

源码安装：拿到最新（latest）版本

从源码安装装的是 latest 版本而非 stable 版本，适合实验尚未进入稳定版的新特性、或修复尚未正式发布的 bug。代价是最新版本不一定稳定——遇到问题可以提交 GitHub Issue 帮助官方尽快修复。

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

安装后仍用第四节的情感分析命令验证。

可编辑安装：本地开发 Transformers 本身

可编辑安装（editable install）把本地的 Transformers 代码目录直接链接进 Python 的导入路径，而不是复制文件——修改源码后无需重装即可生效，是参与 Transformers 本地开发的推荐方式：

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

注意：本地 Transformers 文件夹必须一直保留，删除后该安装即失效。

后续同步上游最新改动：

cd ~/transformers/
git pull

六、conda 安装方式

如果你使用 conda 生态，可以直接从 conda-forge 频道安装。在刚创建好的虚拟环境中执行：

conda install conda-forge::transformers

七、配置缓存目录：HF_HUB_CACHE 与优先级规则

当你通过 PreTrainedModel.from_pretrained 加载预训练模型时，模型会从 Hub 下载并缓存到本地。每次加载时都会检查缓存是否仍是最新版本：一致则直接读本地，不一致则下载并更新缓存。

默认缓存目录由环境变量 HF_HUB_CACHE 决定，通常为 ~/.cache/huggingface/hub（Windows 上为 C:\Users\username\.cache\huggingface\hub）。这个默认值在源码中可以直接看到——当调用方没有显式传 cache_dir 时，下载逻辑就回落到 constants.HF_HUB_CACHE：

# src/transformers/utils/hub.py
if cache_dir is None:
    cache_dir = constants.HF_HUB_CACHE

见 src/transformers/utils/hub.py。同文件中还定义了动态模块缓存路径 HF_MODULES_CACHE，默认落在 HF_HOME/modules 下（见 hub.py）。

要把模型缓存到别的目录，按以下优先级修改 shell 环境变量（优先级从高到低）：

1. HF_HUB_CACHE（直接指定 Hub 缓存目录，最精确）；
2. HF_HOME（指定整个 HF 数据主目录，Hub 缓存固定为其子路径 hub）；
3. XDG_CACHE_HOME + /huggingface（仅在 HF_HOME 未设置时生效）。

八、离线模式：防火墙环境下的完整方案

在离线或防火墙环境中，需要提前把模型文件下载并缓存好。官方给出了三种互补的手段。

1. 预下载：snapshot_download

在有网机器上使用 huggingface_hub 的 snapshot_download 一次性拉取整个模型仓库：

from huggingface_hub import snapshot_download

snapshot_download(repo_id="meta-llama/Llama-2-7b-hf", repo_type="model")

snapshot_download 支持按 revision 下载、通过 CLI 下载、以及按文件模式过滤等更多选项。

2. 环境变量禁网：HF_HUB_OFFLINE=1

设置 HF_HUB_OFFLINE=1 可以彻底禁止加载模型时的任何 HTTP 请求，强制只走本地缓存：

HF_HUB_OFFLINE=1 \
python examples/pytorch/language-modeling/run_clm.py --model_name_or_path meta-llama/Llama-2-7b-hf --dataset_name wikitext ...

其中 run_clm.py 就是仓库中真实存在的语言模型训练示例脚本。

3. 加载参数兜底：local_files_only=True

另一种更细粒度的方式是只在特定加载调用上限定只读本地文件，通过 PreTrainedModel.from_pretrained 的 local_files_only=True 参数实现：

from transformers import LlamaForCausalLM

model = LlamaForCausalLM.from_pretrained("./path/to/local/directory", local_files_only=True)

从源码结构看，local_files_only 是下载链路上一贯透传的参数：src/transformers/utils/hub.py 中它被声明在 DownloadKwargs 里，并在调用 hf_hub_download / snapshot_download 时原样传递（该文件中共有 18 处引用），因此无论是单文件下载还是整仓快照，离线约束都能生效。

小结与延伸阅读

本文完整覆盖了官方安装文档的六大板块：uv 虚拟环境、四种硬件场景的安装命令、安装验证、源码/可编辑安装、conda 安装，以及缓存目录与离线模式的配置。几个便于自查的要点：

• 版本底线：Python 3.10+、PyTorch 2.5+，extras 细节见 setup.py（如 torch extra 绑定 accelerate>=1.1.0）；
• 验证命令：pipeline('sentiment-analysis') 一行脚本即可确认环境完整可用；
• 缓存优先级：HF_HUB_CACHE > HF_HOME > XDG_CACHE_HOME + /huggingface；
• 离线三件套：snapshot_download 预下载、HF_HUB_OFFLINE=1 禁网、local_files_only=True 局部兜底。

如需进一步深入，可以继续参考 README.md 中的快速上手示例与 docs/source/en/installation.md 的原始表述。