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

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

【免费下载链接】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 是 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（如torchextra 绑定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 的原始表述。

【免费下载链接】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