安装

Transformers 与 PyTorch 配合使用。它已在 Python 3.10+ 和 PyTorch 2.4+ 上通过测试。

虚拟环境

uv 是一个基于 Rust 的极速 Python 包和项目管理器，默认需要虚拟环境来管理不同项目并避免依赖项之间的兼容性问题。

它可以作为 pip 的直接替代方案，但如果您更倾向于使用 pip，请从下面的命令中删除 uv。

请参阅 uv 安装文档以安装 uv。

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

uv venv .env
source .env/bin/activate

Python

使用以下命令安装 Transformers。

uv 是一个快速的基于 Rust 的 Python 包和项目管理器。

uv pip install transformers

为了获得 GPU 加速，请为 PyTorch 安装相应的 CUDA 驱动程序。

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

nvidia-smi

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

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

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

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

源码安装

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

缺点是最新版本可能并不总是稳定。如果您遇到任何问题，请提交一个 GitHub Issue，以便我们尽快修复。

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

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

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

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

可编辑安装

如果您在本地开发 Transformers，可编辑安装（editable install）会非常有用。它将您的本地 Transformers 副本链接到 Transformers 仓库，而不是复制文件。文件将被添加到 Python 的导入路径中。

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

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

使用以下命令通过主仓库的最新更改来更新您的本地 Transformers 版本。

cd ~/transformers/
git pull

conda

conda 是一个与语言无关的包管理器。在您新创建的虚拟环境中，从 conda-forge 频道安装 Transformers。

conda install conda-forge::transformers

设置

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

缓存目录

当您使用 from_pretrained() 加载预训练模型时，模型会从 Hub 下载并缓存在本地。

每次加载模型时，它都会检查缓存的模型是否为最新。如果相同，则加载本地模型；如果不同，则下载并缓存更新的模型。

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

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

HF_HUB_CACHE (默认)
HF_HOME
XDG_CACHE_HOME + /huggingface (仅在未设置 HF_HOME 时)

离线模式

在离线或有防火墙的环境中使用 Transformers 需要提前下载并缓存文件。使用 snapshot_download 方法从 Hub 下载模型仓库。

请参阅从 Hub 下载文件指南，了解更多下载选项。您可以从特定版本下载，通过 CLI 下载，甚至过滤要从仓库下载的文件。

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 调用。

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

另一种仅加载缓存文件的选项是在 from_pretrained() 中设置 local_files_only=True。

from transformers import LlamaForCausalLM

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

在 GitHub 上更新