llama.cpp — среда запуска моделей с небольшим сервером и поддержкой квантованных весов GGUF. Она подходит, когда нужен явный контроль файла модели, потоков CPU и размера контекста. Здесь API с авторизацией доступен через SSH; файл модели вы выбираете и проверяете самостоятельно.
Среда: Ubuntu Server 24.04 LTS, x86-64, SSH и учётная запись с sudo. Проверено по документации 15 ноября 2026 года. Команды не проходили сквозное испытание на Ubuntu.
Что подготовить
Для небольшой квантованной текстовой модели 0.5–1.5B ориентируйтесь на 2–4 vCPU, 4 ГБ RAM и 10 ГБ диска, затем измерьте нагрузку. Крупные веса и контекст требуют больше. Нужен совместимый instruction-tuned GGUF с проверенными лицензией и контрольной суммой; переименование произвольного файла не делает его совместимым.
Приведённые ресурсы — ориентир для небольшого теста, а не гарантия производительности или описание тарифов. VPS/VDS не означает наличие GPU. Проверьте память, диск и доступные ресурсы перед заказом.
На чистой Ubuntu установите пакеты ниже. Если Docker уже установлен из другого репозитория, сохраните текущую установку и сначала проверьте совместимость: не смешивайте пакеты Docker CE и docker.io. Нужен Compose v2; при отсутствии пакета проверьте включение репозитория Ubuntu Universe.
sudo apt update
sudo apt install -y docker.io docker-compose-v2 curl openssl
sudo systemctl enable --now docker
sudo docker compose version
Все примеры публикуют порты только на 127.0.0.1 сервера. Для доступа с компьютера используйте SSH-туннель; домен для этого не нужен. Не открывайте эти порты в интернете. Внутренний адрес 0.0.0.0 в контейнере не отменяет привязку опубликованного порта к loopback хоста.
Каждый проект ниже — новая установка. Не повторяйте генерацию секретов поверх уже работающего экземпляра.
1. Подготовьте проверенный файл модели
Создайте проект. Со своего компьютера скопируйте выбранный GGUF на VPS, заменив все заглушки. На VPS сравните sha256sum models/model.gguf с доверенной суммой издателя до запуска. Для загрузки GGUF не требуется выполнять сторонний код репозитория модели.
umask 077
mkdir -p ~/ai-llama/models
cd ~/ai-llama
openssl rand -hex 32 > api-key.txt
scp /PATH/TO/SELECTED.gguf YOUR_USER@YOUR_SERVER_IP:~/ai-llama/models/model.gguf
2. Опишите сервер с ограниченной нагрузкой
Сохраните compose.yaml. Файлы модели и API-ключа подключены только для чтения. --alias задаёт постоянное имя для клиентов; два потока и один параллельный слот — осторожные параметры для теста, а не универсальная настройка для всех тарифов.
services:
llama:
image: ghcr.io/ggml-org/llama.cpp:server
restart: unless-stopped
ports:
- "127.0.0.1:8080:8080"
volumes:
- ./models:/models:ro
- ./api-key.txt:/run/llama-api-key:ro
command: ["-m", "/models/model.gguf", "--alias", "local-gguf", "--host", "0.0.0.0", "--port", "8080", "--ctx-size", "2048", "--threads", "2", "--parallel", "1", "--api-key-file", "/run/llama-api-key"]
3. Проверьте загрузку, авторизацию и ответ
Выполните на VPS после проверки контрольной суммы. /health может быть общедоступным и возвращать 503 во время загрузки: это не проверка авторизации. /v1/models без ключа должен вернуть 401. Начните с коротких запросов; если шаблон чата модели не поддерживается, изучите журналы.
sha256sum models/model.gguf
sudo docker compose up -d
curl -i http://127.0.0.1:8080/health
curl -s -o /dev/null -w '%{http_code}
' http://127.0.0.1:8080/v1/models
LLAMA_KEY=$(cat api-key.txt)
curl --fail-with-body --max-time 180 http://127.0.0.1:8080/v1/chat/completions -H "Authorization: Bearer $LLAMA_KEY" -H 'Content-Type: application/json' -d '{"model":"local-gguf","messages":[{"role":"user","content":"Explain SSH in one sentence."}],"max_tokens":80}'
unset LLAMA_KEY
4. Подключение и воспроизводимость
На своём компьютере создайте туннель и используйте http://127.0.0.1:8080/v1 с тем же ключом и псевдонимом. Сохраните происхождение, контрольную сумму, квантование, лицензию модели и digest контейнера. Даже помещающаяся в RAM модель может быть медленной на общем CPU: измерьте задержку до увеличения параллелизма. Сохраните веса или проверенный способ получить их повторно, а также ключ и конфигурацию.
ssh -N -L 127.0.0.1:8080:127.0.0.1:8080 YOUR_USER@YOUR_SERVER_IP
Обновления и восстановление
Перед обновлением остановите приложение на время согласованного резервного копирования, сохраните данные и секреты за пределами VPS и проверьте восстановление на отдельном экземпляре. Изменяемые теги образов в примерах нужны для первоначальной оценки; перед постоянной эксплуатацией зафиксируйте проверенный тег выпуска или digest. Запишите текущий digest командой sudo docker image inspect ИМЯ_ОБРАЗА --format '{{json .RepoDigests}}'. Не запускайте автоматические обновления без проверки совместимости и не удаляйте тома командой down -v.
Если приложение не запускается, проверьте sudo docker compose ps, последние журналы, свободное место и память. Не публикуйте журналы с ключами, содержимым запросов или персональными данными. При ошибке доступа к каталогу проверьте UID/GID и владельца, а не назначайте права 777. Для совместного доступа сначала настройте HTTPS, аутентификацию и ограничения запросов.