HuggingFace для начинающих: как выбрать и запустить модель

Что понадобится

• Аккаунт на HuggingFace (бесплатный).
• Python 3.9 или новее.
• Установленный пакет transformers и torch.
• Токен доступа (если модель требует авторизации).
• Базовое понимание, что такое модель и веса.

Шаг 1. Зарегистрируйтесь и получите токен

Зайдите на huggingface.co и создайте аккаунт. Без аккаунта можно скачивать многие модели, но некоторые (например, Llama) требуют принятия лицензии.

Токен нужен для доступа к приватным или лицензионным моделям. Создайте его в настройках: Settings → Access Tokens → New token. Выберите роль read.

Сохраните токен в переменную окружения:

export HF_TOKEN=ВАШ_ТОКЕН

Где взять: на странице создания токена. Скопируйте сразу — второй раз не покажут.

Шаг 2. Установите библиотеки

pip install transformers torch

Если есть GPU, установите версию torch с поддержкой CUDA. Команда зависит от версии CUDA. Инструкция на pytorch.org.

Шаг 3. Найдите модель

На главной странице HuggingFace есть поиск. Введите задачу, например «text-classification» или «russian sentiment». Слева фильтры: задачи, библиотеки, языки, лицензии.

Обратите внимание на карточку модели. Там указано: какая задача, на каких данных обучена, какие метрики, как запускать. Если в карточке нет примера кода — это плохой знак.

Не берите первую попавшуюся модель. Проверьте, что она поддерживает ваш язык и задачу. Например, для русского языка ищите модели с тегом «ru».

Шаг 4. Запустите модель через pipeline

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

from transformers import pipeline

classifier = pipeline("sentiment-analysis", model="blanchefort/rubert-base-cased-sentiment")
result = classifier("Я люблю HuggingFace")
print(result)

Этот код скачает модель и запустит её. Первый запуск может занять время — веса скачиваются из интернета.

Если модель требует токен, pipeline его подхватит из переменной HF_TOKEN.

Шаг 5. Проверьте результат

Вывод будет примерно таким:

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

Метка и уверенность зависят от модели. Если результат странный, проверьте, что модель обучена на русском. Например, модель для английского на русском тексте выдаст мусор.

Шаг 6. Запустите модель вручную (если pipeline не подходит)

Иногда нужен доступ к скрытым состояниям или нестандартный пайплайн. Тогда загружайте модель и токенизатор отдельно.

from transformers import AutoTokenizer, AutoModelForSequenceClassification
import torch

model_name = "blanchefort/rubert-base-cased-sentiment"
tokenizer = AutoTokenizer.from_pretrained(model_name)
model = AutoModelForSequenceClassification.from_pretrained(model_name)

inputs = tokenizer("Я люблю HuggingFace", return_tensors="pt")
with torch.no_grad():
    outputs = model(**inputs)

probs = torch.nn.functional.softmax(outputs.logits, dim=-1)
print(probs)

Этот код возвращает вероятности для каждого класса. Метки классов смотрите в карточке модели (обычно в файле config.json).

Шаг 7. Сохраните модель локально

Если модель уже скачана, она лежит в кэше. Путь по умолчанию: ~/.cache/huggingface/hub. Можно указать свою папку:

model.save_pretrained("./my_model")
tokenizer.save_pretrained("./my_model")

Потом загружайте из папки:

model = AutoModelForSequenceClassification.from_pretrained("./my_model")
tokenizer = AutoTokenizer.from_pretrained("./my_model")

Типичные ошибки

Ошибка 1: OSError: Can't load tokenizer

Модель не найдена или нет доступа. Проверьте имя модели на сайте. Если модель приватная, убедитесь, что токен передан.

Ошибка 2: RuntimeError: CUDA out of memory

Модель не помещается в память GPU. Уменьшите batch size или запустите на CPU. Для CPU используйте device=-1 в pipeline.

Ошибка 3: Модель выдаёт бессмыслицу

Скорее всего, модель не для вашего языка или задачи. Проверьте теги и описание. Не все модели многоязычные.

Ошибка 4: Долгая загрузка

Первый раз скачиваются веса. Это нормально. Следующие запуски будут быстрее. Если скорость критична, используйте зеркала или локальный кэш.

Ошибка 5: Несовпадение версий transformers и torch

Обновите обе библиотеки. pip install --upgrade transformers torch.

Что дальше

Когда освоите pipeline, переходите к тонкой настройке (fine-tuning). Для этого есть Trainer и примеры в документации. Но это уже отдельная история.