安装

Transformers 与 PyTorch 兼容。它已在 Python 3.9+ 和 PyTorch 2.2+ 上进行了测试。

虚拟环境

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 中最新的更改，并且对于试验最新功能或修复尚未在稳定版本中正式发布的错误非常有用。

缺点是最新版本可能并不总是稳定。如果您遇到任何问题，请打开一个 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 进行开发，可编辑安装会很有帮助。它将您本地的 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 下载文件的更多选项，请参阅从 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 上更新