Установка

Transformers работает с PyTorch. Он был протестирован на Python 3.11+ и PyTorch 2.6+.

Виртуальное окружение

uv — это чрезвычайно быстрый менеджер пакетов и проектов Python на базе Rust, который по умолчанию требует виртуальное окружение для управления различными проектами и позволяет избежать проблем совместимости между зависимостями.

Его можно использовать как прямую замену для pip, но если вы предпочитаете использовать pip, удалите uv из команд ниже.

См. документацию по установке uv, чтобы установить uv.

Создайте виртуальное окружение для установки Transformers.

uv venv .env
source .env/bin/activate

Python

Установите Transformers с помощью следующей команды.

uv — это быстрый менеджер пакетов и проектов для Python, написанный на Rust.

nvidia-smi

uv pip install "transformers[torch]"

nvidia-smi

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

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

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 и полезно для экспериментов с новыми функциями или исправления ошибок, которые ещё не были официально выпущены в стабильной версии.

Недостаток состоит в том, что последняя версия не всегда стабильна. Если вы столкнетесь с какими-либо проблемами, пожалуйста, создайте 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}]

Установка в режиме редактирования

Установка в режиме editable полезна при локальной разработке с 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 — это менеджер пакетов, не зависящий от языка программирования. Установите Transformers из канала conda-forge в только что созданную виртуальную среду.

conda install conda-forge::transformers

Настройка

После установки вы можете настроить расположение кэша Transformers или настроить библиотеку для работы в автономном режиме.

Каталог кэша

При загрузке предобученной модели с помощью from_pretrained() модель скачивается с Hub и кэшируется локально.

Если вы передаёте хеш коммита, Transformers использует локальный кэш для файлов этого коммита и не проверяет Hub повторно для каждого из них (включая файлы, отсутствие которых известно). Это поведение по умолчанию, если ревизия не указана.

Если вы передаёте ветку или тег, Transformers обращается к Hub один раз в начале загрузки, чтобы выбрать коммит, а затем использует кэш для файлов этого коммита аналогичным образом.

Каталог по умолчанию, задаваемый переменной окружения оболочки HF_HUB_CACHE, — это ~/.cache/huggingface/hub. В Windows каталог по умолчанию — C:\Users\username\.cache\huggingface\hub.

Кэшируйте модель в другой директории, изменив путь в следующих переменных окружения оболочки (перечислены по приоритету).

1. HF_HUB_CACHE (по умолчанию)
2. HF_HOME
3. XDG_CACHE_HOME + /huggingface (только если HF_HOME не задан)

Офлайн-режим

Для использования Transformers в автономной или защищённой файрволом среде необходимо заранее скачать и закэшировать файлы. Скачайте репозиторий модели с Hub с помощью метода 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, чтобы предотвратить HTTP-вызовы к Hub при загрузке модели.

Ещё один вариант загрузить только кэшированные файлы — установить local_files_only=True в from_pretrained().

from transformers import LlamaForCausalLM

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

В режиме офлайн (или при local_files_only=True), если в кэше ранее было сохранено соответствие ветки или тега с коммитом при онлайн-загрузке, система всё равно может преобразовать ветку или тег в коммит. Если такое соответствие никогда не сохранялось, Transformers сохраняет запрошенную вами ветку или тег и продолжает обычную офлайн-загрузку. Вы получите те же попадания в кэш или ошибки об отсутствии файлов, что и при стандартной офлайн-загрузке.