Модели с Hugging Face на VPS: запуск с нуля

Hugging Face — крупнейший склад открытых моделей. Разберём, как поднять окружение на чистом сервере, скачать модель без сюрпризов с местом на диске и запустить инференс.

Готовим окружение

На свежем Ubuntu-сервере ставим Python-окружение и базовые библиотеки. Изолируем всё в venv, чтобы не ломать системный Python:

apt update && apt install -y python3-venv python3-pip git git-lfs
git lfs install
python3 -m venv ~/hf && source ~/hf/bin/activate
pip install -U huggingface_hub transformers accelerate

git-lfs обязателен: без него большие файлы весов скачаются как пустые заглушки.

Токен доступа и приватные модели

Часть моделей (например, gated-версии Llama) требует принять лицензию и авторизоваться токеном. Создаёшь токен в настройках профиля Hugging Face и логинишься:

huggingface-cli login
# вставь токен hf_xxx когда попросит

Токен хранится в ~/.cache/huggingface. Никогда не коммить его в репозиторий и не оставляй в истории bash.

Скачиваем модель правильно

Не клонируй гигантские репозитории целиком — качай только нужные файлы. Удобный способ через CLI:

huggingface-cli download Qwen/Qwen2.5-7B-Instruct \
  --local-dir ./qwen2.5-7b --exclude '*.pth' '*.bin'

Следи за местом на диске: fp16-модель 7B — это ~15 ГБ, 70B — под 140 ГБ. Проверяй свободное место заранее:

df -h
du -sh ~/.cache/huggingface

Здесь напрямую играет NVMe у MAATRIX: скачивание и распаковка десятков гигабайт весов идут на полной скорости диска, а не упираются в медленный HDD.

Запускаем инференс

Минимальный пример на transformers — загрузка модели и генерация:

python3 -c "
from transformers import pipeline
pipe = pipeline('text-generation', model='./qwen2.5-7b', device_map='auto')
print(pipe('Объясни, что такое VPS', max_new_tokens=100)[0]['generated_text'])
"

Для CPU-сервера практичнее взять GGUF-версию и запустить через llama.cpp или Ollama — быстрее и легче по памяти, чем сырой transformers на fp16.

Если всё же работаешь через transformers на CPU, включи оптимизации: тип данных bfloat16 экономит память, а low_cpu_mem_usage снижает пик потребления при загрузке. Иначе большая модель может не влезть даже при формально достаточной RAM.

Не только LLM: другие модели с Hub

Hugging Face — это не только языковые модели. Оттуда же удобно брать модели эмбеддингов для поиска и RAG, распознавания речи, классификации и компьютерного зрения. Все они ставятся тем же способом.

Например, модель эмбеддингов для семантического поиска через библиотеку sentence-transformers:

pip install sentence-transformers
python3 -c "
from sentence_transformers import SentenceTransformer
m = SentenceTransformer('intfloat/multilingual-e5-small')
print(m.encode('пример текста').shape)
"

Такие модели лёгкие (десятки-сотни МБ), отлично идут на CPU и часто становятся первым шагом к RAG-системе на своём сервере — без всякого GPU.

Кэш, место и уборка

Hugging Face кэширует всё в ~/.cache/huggingface. Он быстро разрастается. Управляй кэшем:

huggingface-cli scan-cache
huggingface-cli delete-cache

Вынести кэш на отдельный путь можно переменной окружения — удобно, если под модели выделен отдельный диск:

export HF_HOME=/data/hf-cache

Частые ошибки

• Забыли git-lfs — веса скачались заглушками по несколько килобайт.
• Кончилось место на диске посреди скачивания 70B-модели.
• Пытаются запустить gated-модель без токена и получают 401.
• Грузят fp16 на CPU вместо GGUF и получают медленный инференс.

Частые вопросы