Личный кабинет
На сайт
← База знаний

LiteLLM на VPS: приватный шлюз API для моделей

LiteLLM предоставляет приложениям единый шлюз к поддерживаемым моделям. Постоянный псевдоним модели позволяет сменить бэкенд без перенастройки каждого клиента. В небольшом примере без базы запросы защищены главным ключом и передаются приватной модели Ollama.

Среда: Ubuntu Server 24.04 LTS, x86-64, SSH и учётная запись с sudo. Проверено по документации 15 ноября 2026 года. Команды не проходили сквозное испытание на Ubuntu.

Что подготовить

Для проверки с маленькой локальной моделью ориентируйтесь на 2 vCPU, 4 ГБ RAM и 10 ГБ диска. Крупные модели требуют больше. При внешней обработке модели шлюзу может понадобиться меньше памяти. Здесь нет базы для виртуальных ключей, бюджетов и учёта расходов: этот пример нельзя считать системой контроля затрат.

Приведённые ресурсы — ориентир для небольшого теста, а не гарантия производительности или описание тарифов. 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. Опишите шлюз и псевдоним модели

Создайте закрытый файл ключа и сохраните config.yaml и compose.yaml. Модель доступна только внутри сети Compose. Шлюз публикует лишь локальный порт 4000.

umask 077
mkdir -p ~/ai-litellm
cd ~/ai-litellm
printf 'LITELLM_MASTER_KEY=sk-%s\n' "$(openssl rand -hex 32)" > .env
model_list:
  - model_name: local-small
    litellm_params:
      model: ollama_chat/qwen2.5:0.5b
      api_base: http://ollama:11434
general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY
services:
  ollama:
    image: ollama/ollama:latest
    restart: unless-stopped
    environment:
      OLLAMA_NUM_PARALLEL: "1"
      OLLAMA_CONTEXT_LENGTH: "2048"
    volumes:
      - models:/root/.ollama
  gateway:
    image: docker.litellm.ai/berriai/litellm:latest
    restart: unless-stopped
    env_file: .env
    command: ["--config", "/app/config.yaml", "--port", "4000"]
    ports:
      - "127.0.0.1:4000:4000"
    volumes:
      - ./config.yaml:/app/config.yaml:ro
    depends_on:
      - ollama
volumes:
  models:

2. Запустите сервисы и проверьте авторизацию

Выполните команды на VPS. Первый запрос намеренно отправляется без ключа и должен вернуть HTTP 401. Авторизованный запрос должен вернуть JSON с ответом после загрузки модели. Если запрос без ключа проходит, остановитесь и исправьте настройку до отправки реальных данных.

sudo docker compose up -d
sudo docker compose exec ollama ollama pull qwen2.5:0.5b
curl -s -o /dev/null -w '%{http_code}
' http://127.0.0.1:4000/v1/models
set -a
. ./.env
set +a
curl --fail-with-body --max-time 180 http://127.0.0.1:4000/v1/chat/completions   -H "Authorization: Bearer $LITELLM_MASTER_KEY"   -H 'Content-Type: application/json'   -d '{"model":"local-small","messages":[{"role":"user","content":"Say hello in five words."}],"max_tokens":80}'
unset LITELLM_MASTER_KEY

3. Подключите клиент и спланируйте развитие

Через SSH-туннель используйте на компьютере базовый URL http://127.0.0.1:4000/v1 и модель local-small. Главный ключ храните у оператора и не раздавайте недоверенным пользователям. Для команды нужна поддерживаемая конфигурация с базой и виртуальными ключами, проверкой их прав и отдельной защитой администрирования. Лимиты внешнего API задавайте у провайдера; шлюз без базы не обеспечивает надёжное ограничение бюджета. Сохраняйте конфигурацию и .env, а при добавлении базы — её согласованную копию.

ssh -N -L 127.0.0.1:4000:127.0.0.1:4000 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, аутентификацию и ограничения запросов.

Другие сценарии