Transformers documentation
安装
安装
Transformers 支持 PyTorch。已在 Python 3.11+ 和 PyTorch 2.6+ 上完成测试。
虚拟环境
uv 是一款基于 Rust 的极速 Python 包与项目管理工具，默认要求使用 虚拟环境 来管理不同的项目，从而避免依赖项之间的兼容性问题。
它可以作为 pip 的直接替代品，但如果您更习惯使用 pip，请从以下命令中移除 uv。
请参阅 uv 的 安装 文档以安装 uv。
创建一个虚拟环境，用于安装 Transformers。
uv venv .env
source .env/bin/activatePython
使用以下命令安装 Transformers。
uv 是一个基于 Rust 的快速 Python 包和项目管理器。
要在 NVIDIA GPU（CUDA）上使用 PyTorch 安装 Transformers，请为 PyTorch 安装相应的 CUDA 驱动程序。
运行以下命令以检查您的系统是否检测到 NVIDIA GPU。
nvidia-smi
uv pip install "transformers[torch]"要在运行 ARM64 的 NVIDIA Spark 设备（例如 RTX Spark 笔记本电脑）上安装基于 PyTorch 的 Transformers，请从 NVIDIA PyPI 索引安装 PyTorch。这些设备需要 NVIDIA 提供的 PyTorch ARM64 构建版本，而该版本在默认 PyPI 索引或标准 PyTorch wheel 索引中不可用。
运行以下命令以检查您的系统是否检测到 NVIDIA GPU。
nvidia-smi
从 NVIDIA PyPI 索引安装 PyTorch，然后安装 Transformers。
uv pip install torch --index-url https://pypi.nvidia.com uv pip install transformers
要安装仅支持 CPU 的 Transformers 版本，请运行以下命令。
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 驱动程序，并添加 Intel GPU (XPU) PyTorch 索引 URL。
安装完驱动程序后，运行以下命令以检查系统是否检测到 Intel GPU。
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 中最新的更改，适用于尝试最新功能或修复尚未在稳定版中正式发布的 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，可编辑安装会非常有用。它会将你本地的 Transformers 副本链接到 Transformers 仓库，而不是复制文件。这些文件会被添加到 Python 的导入路径中。
git clone https://github.com/huggingface/transformers.git
cd transformers
uv pip install -e .您必须保留本地的 Transformers 文件夹才能继续使用它。
使用以下命令，将本地 Transformers 版本更新为 main 仓库中的最新更改。
cd ~/transformers/
git pullconda
conda 是一个与语言无关的包管理器。请在您新建的虚拟环境中，从 conda-forge 频道安装 Transformers。
conda install conda-forge::transformers
设置
安装完成后，您可以配置 Transformers 的缓存位置，或将该库设置为离线使用。
缓存目录
使用 from_pretrained() 加载预训练模型时，该模型会从 Hub 下载并在本地进行缓存。
如果传入提交哈希，Transformers 将使用该提交的本地缓存文件，而不会针对每个文件（包括已知缺失的文件）重新检查 Hub。在未指定 revision 时，这是默认行为。
如果您传入一个分支或标签，Transformers 会在加载开始时联系 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 调用。
另一种仅加载缓存文件的方法是在 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=True）仍然可以将分支或标签转换为 commit，前提是之前的在线加载已在缓存中保存了该映射。如果该映射从未被保存，Transformers 将保留你请求的分支或标签，并继续执行常规的离线加载。你将获得与正常离线加载相同的缓存命中或文件缺失错误。