AIKraft Agents
Главная/Блог/Гайд/Как установить Hugging Face…
Гайд3 мин чтения · 26 октября 2026 г.

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

Полная инструкция по установке библиотеки Hugging Face Transformers для работы с нейросетями на Python. Разбор требований к железу, вариантов установки и настройки офлайн-режима.

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

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

01Требования

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

  • Операционная система: Linux, macOS или Windows.
  • Python: Версия 3.10 или выше.
  • PyTorch: Версия 2.6+ (рекомендуется актуальная стабильная версия).
  • Дисковое пространство: Зависит от моделей. Требуется значительный объем памяти для хранения весов.
⚠️
Важно. Для работы с графическими процессорами NVIDIA требуется установка соответствующих драйверов CUDA. Без них библиотека будет работать только на CPU, что заметно медленнее. Проверьте наличие GPU командой nvidia-smi.

Сколько VRAM нужно?

Выбор модели напрямую зависит от объема видеопамяти (VRAM) вашей видеокарты:

  • Малый объем VRAM: Подходит для квантованных моделей небольших LLM. Для инференса (генерации текста) этого может быть достаточно.
  • Средний объем VRAM: Позволяет запускать полноразмерные модели среднего размера. Подходит для комфортного инференса и легкого fine-tuning.
  • Большой объем VRAM: Позволяет запускать модели с большим количеством параметров в полном精度 (fp16/bf16) или квантованные модели большего размера.
  • Отсутствие GPU: Можно использовать CPU, но скорость генерации будет низкой. Рекомендуется использовать модели с оптимизацией optimum-intel для процессоров Intel.

02Установка

Официальная документация рекомендует использовать менеджер uv (быстрый аналог pip/conda на Rust) для создания изолированного окружения. Это предотвращает конфликты зависимостей.

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

Сначала создайте и активируйте виртуальное окружение:

terminalbash
uv venv .env
source .env/bin/activate

Примечание: Если вы не используете uv, вы можете использовать стандартный python -m venv .env и pip вместо uv pip.

Шаг 2. Установка Transformers с поддержкой PyTorch

Для установки последней стабильной версии с поддержкой NVIDIA GPU выполните:

terminalbash
uv pip install "transformers[torch]"

Если у вас нет GPU, можно установить версию только для CPU, чтобы сэкономить место и время:

terminalbash
uv pip install transformers

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

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

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

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

terminalpython
[{'label': 'POSITIVE', 'score': 0.9998704791069031}]
💡
Совет. Если вы хотите экспериментировать с самыми свежими фичами, которые еще не вышли в стабильный релиз, установите библиотеку из исходного кода: uv pip install git+https://github.com/huggingface/transformers. Однако имейте в виду, что эта версия может быть менее стабильной.

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

После установки вы можете начать работу с моделями. Самый простой способ — использовать класс pipeline, который абстрагирует загрузку модели, токенизатора и обработку данных.

Пример загрузки и использования модели для генерации текста (требуется модель, совместимая с LLM, например, facebook/opt-350m для тестов на слабом железе):

terminalpython
from transformers import pipeline

# Загрузка модели для генерации текста
generator = pipeline('text-generation', model='facebook/opt-350m')

# Генерация ответа
result = generator("Hello, I'm a language model:", max_length=50, num_return_sequences=1)
print(result[0]['generated_text'])

Работа в офлайн-режиме (актуально для РФ)

Из-за ограничений доступа к некоторым ресурсам или необходимости работы без интернета, Transformers поддерживает офлайн-режим. Сначала нужно скачать модель в кэш:

terminalpython
from huggingface_hub import snapshot_download

# Скачивание модели в локальную папку
download_path = snapshot_download(repo_id="meta-llama/Llama-2-7b-hf", repo_type="model")

Затем установите переменную окружения HF_HUB_OFFLINE=1 или используйте флаг local_files_only=True при загрузке:

terminalpython
from transformers import LlamaForCausalLM

# Загрузка только из локального кэша
model = LlamaForCausalLM.from_pretrained(
    "./path/to/local/directory",
    local_files_only=True
)

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

  1. Ошибка CUDA Out of Memory: Если вы пытаетесь загрузить большую модель на видеокарту с малым объемом памяти, PyTorch выдаст ошибку. Решение: используйте квантование (библиотека bitsandbytes) или запустите модель на CPU. Также проверьте, не заняты ли другие процессы GPU командой nvidia-smi.
  2. Медленная загрузка моделей: Hugging Face Hub может

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