# 安装

Transformers 支持 [PyTorch](https://pytorch.org/get-started/locally/)。已在 Python 3.11+ 和 PyTorch 2.6+ 上完成测试。

## 虚拟环境

[uv](https://docs.astral.sh/uv/) 是一款基于 Rust 的极速 Python 包与项目管理工具，默认要求使用 [虚拟环境](https://docs.astral.sh/uv/pip/environments/) 来管理不同的项目，从而避免依赖项之间的兼容性问题。

它可以作为 [pip](https://pip.pypa.io/en/stable/) 的直接替代品，但如果您更习惯使用 pip，请从以下命令中移除 `uv`。

> [!TIP]
> 请参阅 uv 的 [安装](https://docs.astral.sh/uv/guides/install-python/) 文档以安装 uv。

创建一个虚拟环境，用于安装 Transformers。

```bash
uv venv .env
source .env/bin/activate
```

## Python

使用以下命令安装 Transformers。

[uv](https://docs.astral.sh/uv/) 是一个基于 Rust 的快速 Python 包和项目管理器。

要在 NVIDIA GPU（CUDA）上使用 PyTorch 安装 Transformers，请为 [PyTorch](https://pytorch.org/get-started/locally) 安装相应的 CUDA 驱动程序。

运行以下命令以检查您的系统是否检测到 NVIDIA GPU。

```bash
nvidia-smi
```

```bash
uv pip install "transformers[torch]"
```

要在运行 ARM64 的 NVIDIA Spark 设备（例如 RTX Spark 笔记本电脑）上安装基于 PyTorch 的 Transformers，请从 NVIDIA PyPI 索引安装 PyTorch。这些设备需要 NVIDIA 提供的 PyTorch ARM64 构建版本，而该版本在默认的 PyPI 索引或标准的 PyTorch wheel 索引中不可用。

运行以下命令以检查您的系统是否检测到 NVIDIA GPU。

```bash
nvidia-smi
```

从 NVIDIA PyPI 索引安装 PyTorch，然后安装 Transformers。

```bash
uv pip install torch --index-url https://pypi.nvidia.com
uv pip install transformers
```

要安装仅支持 CPU 的 Transformers 版本，请运行以下命令。

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

要在 Intel GPU (XPU) 上安装带有 PyTorch 的 Transformers，请安装相应的 [Intel GPU (XPU) PyTorch 驱动程序](https://www.intel.com/content/www/us/en/developer/articles/tool/pytorch-prerequisites-for-intel-gpu/2-13.html)，并添加 Intel GPU (XPU) PyTorch 索引 URL。

安装完驱动程序后，运行以下命令以[检查系统是否检测到 Intel GPU](https://dgpu-docs.intel.com/driver/verification.html)。

```bash
xpu-smi
```

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

使用以下命令测试安装是否成功。它应该为提供的文本返回一个标签和分数。

```bash
python -c "from transformers import pipeline; print(pipeline('sentiment-analysis')('hugging face is the best'))"
[{'label': 'POSITIVE', 'score': 0.9998704791069031}]
```

### 从源代码安装

从源代码安装会安装库的*最新*版本，而非*稳定*版本。这可以确保您拥有 Transformers 中最新的更改，适用于尝试最新功能或修复尚未在稳定版中正式发布的 bug。

缺点在于，最新版本并不总是稳定的。如果您遇到任何问题，请提交一个 [GitHub Issue](https://github.com/huggingface/transformers/issues)，以便我们尽快修复。

使用以下命令从源代码安装。

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

使用以下命令检查安装是否成功。它应该为提供的文本返回一个标签和分数。

```bash
python -c "from transformers import pipeline; print(pipeline('sentiment-analysis')('hugging face is the best'))"
[{'label': 'POSITIVE', 'score': 0.9998704791069031}]
```

### 可编辑安装

如果你正在本地开发 Transformers，[可编辑安装](https://pip.pypa.io/en/stable/topics/local-project-installs/#editable-installs)会非常有用。它会将你本地的 Transformers 副本链接到 Transformers [仓库](https://github.com/huggingface/transformers)，而不是复制文件。这些文件会被添加到 Python 的导入路径中。

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

> [!WARNING]
> 您必须保留本地的 Transformers 文件夹才能继续使用它。

使用以下命令，将本地 Transformers 版本更新为 main 仓库中的最新更改。

```bash
cd ~/transformers/
git pull
```

## conda

[conda](https://docs.conda.io/projects/conda/en/stable/#) 是一个与语言无关的包管理器。请在您新建的虚拟环境中，从 [conda-forge](https://anaconda.org/conda-forge/transformers) 频道安装 Transformers。

```bash
conda install conda-forge::transformers
```

## 设置

安装完成后，您可以配置 Transformers 的缓存位置，或将该库设置为离线使用。

### 缓存目录

使用 [from_pretrained()](/docs/transformers/v5.23.0/zh/main_classes/model#transformers.PreTrainedModel.from_pretrained) 加载预训练模型时，该模型会从 Hub 下载并在本地进行缓存。

如果传入提交哈希，Transformers 将使用该提交文件的本地缓存，而不会针对每个文件（包括已知缺失的文件）重新检查 Hub。在未指定 revision 时，这是默认行为。

如果传入分支或标签，Transformers 会在加载开始时联系 Hub 一次以选择提交，然后以相同的方式使用该提交的缓存文件。

由 shell 环境变量 `HF_HUB_CACHE` 指定的默认目录为 `~/.cache/huggingface/hub`。在 Windows 上，默认目录为 `C:\Users\username\.cache\huggingface\hub`。

通过修改以下 shell 环境变量（按优先级排列）中的路径，将模型缓存到不同的目录。

1. [HF_HUB_CACHE](https://hf.co/docs/huggingface_hub/package_reference/environment_variables#hfhubcache)（默认）
2. [HF_HOME](https://hf.co/docs/huggingface_hub/package_reference/environment_variables#hfhome)
3. [XDG_CACHE_HOME](https://hf.co/docs/huggingface_hub/package_reference/environment_variables#xdgcachehome) + `/huggingface`（仅在未设置 `HF_HOME` 时）

### 离线模式

要在离线或防火墙环境中使用 Transformers，需要提前下载并缓存相关文件。使用 [snapshot_download](https://huggingface.co/docs/huggingface_hub/v2.4.0/en/package_reference/file_download#huggingface_hub.snapshot_download) 方法从 Hub 下载模型仓库。

> [!TIP]
> 有关从 Hub 下载文件的更多选项，请参阅 [从 Hub 下载文件](https://hf.co/docs/huggingface_hub/guides/download) 指南。您可以从特定版本下载文件、通过 CLI 下载，甚至筛选要从仓库中下载的文件。

```py
from huggingface_hub import snapshot_download

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

设置环境变量 `HF_HUB_OFFLINE=1`，以在加载模型时阻止向 Hub 发起 HTTP 调用。

另一种仅加载缓存文件的方法是在 [from_pretrained()](/docs/transformers/v5.23.0/zh/main_classes/model#transformers.PreTrainedModel.from_pretrained) 中设置 `local_files_only=True`。

```py
from transformers import LlamaForCausalLM

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

离线模式（或 `local_files_only=True`）仍然可以将分支或标签转换为 commit，前提是之前的在线加载已在缓存中保存了该映射。如果该映射从未被保存，Transformers 将保留你请求的分支或标签，并继续执行常规的离线加载。你将获得与正常离线加载相同的缓存命中或文件缺失错误。