Transformers 文档
安装
并获得增强的文档体验
开始
安装
Transformers 可以与 PyTorch、TensorFlow 2.0 和 Flax 一起使用。它已经在 Python 3.9+、PyTorch 2.0+、TensorFlow 2.6+ 和 Flax 0.4.1+ 上进行了测试。
虚拟环境
虚拟环境有助于管理不同的项目，并避免依赖项之间的兼容性问题。如果您不熟悉 Python 虚拟环境，请查看使用 pip 和 venv 在虚拟环境中安装软件包指南。
使用 venv 在您的项目目录中创建并激活虚拟环境。
python -m venv .env
source ./env/bin/activatePython
您可以使用 pip 或 uv 安装 Transformers。
pip 是 Python 的包安装程序。在您新创建的虚拟环境中使用 pip 安装 Transformers。
pip install transformers
为了获得 GPU 加速，请为 PyTorch 和 TensorFlow 安装适当的 CUDA 驱动程序。
运行以下命令检查您的系统是否检测到 NVIDIA GPU。
nvidia-smi
要安装仅 CPU 版本的 Transformers 和机器学习框架，请运行以下命令。
pip install 'transformers[torch]'
uv pip install 'transformers[torch]'使用以下命令测试安装是否成功。它应该为提供的文本返回标签和分数。
python -c "from transformers import pipeline; print(pipeline('sentiment-analysis')('hugging face is the best'))"
[{'label': 'POSITIVE', 'score': 0.9998704791069031}]源代码安装
从源代码安装会安装<强调>最新版本，而不是库的<强调>稳定版本。它可以确保您拥有 Transformers 中最新的更改，并且对于试验最新功能或修复尚未在稳定版本中正式发布的错误非常有用。
缺点是最新的版本可能并不总是稳定的。如果您遇到任何问题，请打开一个 GitHub Issue，以便我们尽快修复它。
使用以下命令从源代码安装。
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
pip install -e .您必须保留本地 Transformers 文件夹才能继续使用它。
使用以下命令使用主存储库中的最新更改更新您的本地 Transformers 版本。
cd ~/transformers/
git pullconda
conda 是一个与语言无关的包管理器。在您新创建的虚拟环境中使用 conda-forge 频道安装 Transformers。
conda install conda-forge::transformers
设置
安装后，您可以配置 Transformers 缓存位置或设置库以供离线使用。
缓存目录
当您使用 from_pretrained() 加载预训练模型时，该模型将从 Hub 下载并本地缓存。
每次加载模型时，它都会检查缓存的模型是否为最新。如果相同，则加载本地模型。如果不同，则下载并缓存较新的模型。
shell 环境变量 TRANSFORMERS_CACHE 给出的默认目录是 ~/.cache/huggingface/hub。在 Windows 上，默认目录是 C:\Users\username\.cache\huggingface\hub。
通过更改以下 shell 环境变量中的路径（按优先级列出）在不同的目录中缓存模型。
- HF_HUB_CACHE 或
TRANSFORMERS_CACHE（默认） - HF_HOME
- XDG_CACHE_HOME +
/huggingface（仅当未设置HF_HOME时）
较旧版本的 Transformers 使用 shell 环境变量 PYTORCH_TRANSFORMERS_CACHE 或 PYTORCH_PRETRAINED_BERT_CACHE。您应该保留这些变量，除非您指定较新的 shell 环境变量 TRANSFORMERS_CACHE。
离线模式
要在离线或防火墙环境中使用 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)