Как установить Hugging Face Transformers локально: пошаговый гайд

Библиотека Hugging Face Transformers — это стандарт индустрии для работы с моделями машинного обучения (NLP, CV, аудио). Она позволяет запускать тысячи предобученных моделей прямо на вашем компьютере. Этот гайд поможет практикам быстро развернуть среду разработки, оптимизировать её под доступное железо и решить проблемы с доступом к серверам Hugging Face из России.

01Требования

Для стабильной работы библиотеки необходимы следующие компоненты:

• Операционная система: Linux, macOS или Windows.
• Python: Версия 3.10 или выше.
• PyTorch: Версия 2.4+ (рекомендуется). Библиотека работает на базе PyTorch.
• Менеджер пакетов: Официальная документация настоятельно рекомендует использовать uv (быстрый менеджер на Rust), но также поддерживается классический pip или conda.

02Установка

Мы рассмотрим два основных пути: через uv (рекомендуемый, самый быстрый) и через pip (классический).

Шаг 1. Создание виртуального окружения

Всегда изолируйте проекты. Если вы используете uv:

uv venv .env
source .env/bin/activate

Если вы используете стандартный Python:

python -m venv .env
source .env/bin/activate

Шаг 2. Установка Transformers

Установите основную библиотеку. Для GPU-ускорения убедитесь, что у вас установлены драйверы NVIDIA (проверьте командой nvidia-smi).

Вариант А: Через uv (рекомендуется)

uv pip install transformers

Вариант Б: Через pip

pip install transformers

Вариант В: CPU-only версия (если у вас нет NVIDIA GPU или вы хотите сэкономить место):

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

Шаг 3. Проверка установки

Запустите тестовую команду, которая загрузит простую модель для анализа тональности. Если всё работает, вы увидите результат:

python -c "from transformers import pipeline; print(pipeline('sentiment-analysis')('hugging face is the best'))"

Ожидаемый вывод:

[{'label': 'POSITIVE', 'score': 0.9998704791069031}]

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

03Первый запуск

После установки вы можете использовать высокоуровневый API pipeline для быстрого прототипирования. Ниже пример загрузки модели для генерации текста (текстовой генерации).

Примечание: Для работы с большими моделями (например, Llama, Mistral) может потребоваться авторизация через Hugging Face Token, если модель требует подтверждения доступа.

from transformers import pipeline

# Загрузка модели для генерации текста
# Обратите внимание: модель может весить несколько ГБ
pipe = pipeline("text-generation", model="HuggingFaceH4/zephyr-7b-beta")

result = pipe("Hello, how are you?", max_length=50, do_sample=True)
print(result[0]['generated_text'])

Работа офлайн и из России

Из-за ограничений доступа к серверам Hugging Face из РФ или просто для работы в условиях плохой связи, важно уметь кэшировать модели локально.

1. Скачивание модели заранее: Используйте snapshot_download для загрузки репозитория модели в папку.

from huggingface_hub import snapshot_download

snapshot_download(repo_id="meta-llama/Llama-2-7b-hf", repo_type="model")

2. Запуск в офлайн-режиме: Установите переменную окружения HF_HUB_OFFLINE=1 перед запуском скрипта. Это запретит библиотеке обращаться к интернету.

HF_HUB_OFFLINE=1 python your_script.py

Альтернативно, в коде можно указать local_files_only=True в методе from_pretrained.

04Частые проблемы

1. Ошибка "CUDA out of memory"

Если ваша видеокарта не справляется с объемом модели, попробуйте:

• Использовать квантованные версии моделей (4-bit или 8-bit), например, через библиотеку bitsandbytes.
• Уменьшить размер батча (batch size) до 1.
• Использовать torch.cuda.empty_cache() после тяжелых операций.

2. Медленная загрузка моделей

Модели часто весят несколько гигабайт. Если интернет нестабилен:

• Используйте huggingface-cli download для загрузки через терминал, который лучше обрабатывает разрывы соединения.
• Настройте локальный кэш, изменив переменную окружения HF_HOME на быстрый SSD диск.

3. Конфликты версий PyTorch

Transformers требует актуальной версии PyTorch. Если вы уст

Источник: Hugging Face Transformers (офиц. документация) ↗