LiteLLM на Ubuntu 24.04: пошаговая установка

MAATRIX

Свой LLM-шлюз нужен тогда, когда ключей уже несколько — OpenAI, Anthropic, Gemini, — а приложений, которые в них ходят, ещё больше. LiteLLM собирает всё это за одним OpenAI-совместимым адресом и добавляет виртуальные ключи, лимиты и учёт расходов. Ниже — установка на чистую Ubuntu 24.04: от apt update до systemd-юнита за nginx, вместе с граблями, на которых теряют вечер.

Почему Ubuntu 24.04 подходит LiteLLM лучше старых релизов

LiteLLM Proxy принимает запросы в формате OpenAI (POST /v1/chat/completions) и переадресует их провайдеру — OpenAI, Anthropic, Gemini или локальной Ollama; клиентский код видит один адрес и один ключ.

Актуальная версия — 1.98.0 от 22 августа 2026, в метаданных стоит Requires-Python: >=3.10,<3.15. Это и есть причина брать 24.04: ветка Python определяет, какую версию шлюза вы сможете поставить.

Граница свежая: 1.83.9 (17 апреля 2026) — последний релиз с поддержкой Python 3.9, с 1.84.0 (14 мая 2026) минимум подняли до 3.10. На Debian 11 и Ubuntu 20.04 обновления однажды остановятся.

Второй плюс noble — бинарные колёса: litellm-1.98.0-cp310-abi3-manylinux_2_28_x86_64.whl (24 МБ) требует glibc 2.28, а в 24.04 она 2.39 — ставится без компиляции и build-essential. Проверьте вводные:

lsb_release -ds       # Ubuntu 24.04.3 LTS
python3 --version     # Python 3.12.3

Шаг 1. Пользователь, пакеты и фаервол

Ставим всё сразу; python3-venv в noble тянет python3.12-venv:

apt update && apt -y upgrade
apt install -y python3-venv python3-pip postgresql nginx ufw curl

Без него создание окружения падает с сообщением, которое принимают за поломку Python:

The virtual environment was not created successfully because ensurepip is not
available.  On Debian/Ubuntu systems, you need to install the python3-venv
package using the following command:  apt install python3.12-venv

Дальше — системный пользователь: держать шлюз с боевыми ключами под root не стоит.

adduser --system --group --home /opt/litellm --shell /usr/sbin/nologin litellm
mkdir -p /etc/litellm && chown root:litellm /etc/litellm && chmod 750 /etc/litellm

Фаервол настраиваем до первого запуска; порт 4000 наружу не открываем никогда:

ufw allow 22/tcp
ufw allow 'Nginx Full'
ufw --force enable

На 4000 шлюз говорит по HTTP без шифрования, а вся авторизация — заголовок Authorization: Bearer sk-.... Открытый порт сканеры находят за часы, и дальше ваш ключ OpenAI работает на чужие задачи, а счёт приходит вам.

Шаг 2. Установка в venv: PEP 668 и правильные extras

Первое, обо что спотыкаются, — системный pip. Ubuntu 24.04 следует PEP 668 и отвечает так:

error: externally-managed-environment

× This environment is externally managed
╰─> To install Python packages system-wide, try apt install
    python3-xyz, where xyz is the package you want to install.
    You can override this by passing --break-system-packages.

Флаг из подсказки применять нельзя: litellm[proxy] тянет под девяносто пакетов со своими версиями fastapi, pydantic и boto3 — они перетрут системные python3-*, на которых держатся утилиты Ubuntu. Правильный путь — venv:

python3 -m venv /opt/litellm/venv
/opt/litellm/venv/bin/pip install -U pip setuptools wheel
/opt/litellm/venv/bin/pip install 'litellm[proxy]==1.98.0'

Кавычки вокруг litellm[proxy] обязательны — bash и zsh иначе раскроют скобки как glob. Версию фиксируйте явно: релизы выходят каждые три-семь дней — за последнюю неделю августа 2026 вышли v1.98.0, v1.99.0-rc.1 и два dev-тега.

Вторая грабля — extras. Пакет prisma, через который шлюз ходит в базу, лежит не в [proxy], а в отдельном extra:

• litellm[proxy] — шлюз с одним мастер-ключом и моделями из файла;
• litellm[proxy,extra-proxy] — плюс виртуальные ключи, бюджеты, учёт трат и веб-интерфейс /ui.

Поставите только [proxy], но пропишете DATABASE_URL — прокси не упадёт: напечатает одну строку и продолжит работать без базы, без ключей, без статистики и без UI.

Unable to connect to DB. DATABASE_URL found in environment, but prisma package not found.

du -sh /opt/litellm/venv покажет порядка гигабайта — вместе с Postgres, логами и запасом на обновления закладывайте от 20 ГБ диска.

Шаг 3. Конфиг с моделями и файл с секретами

Конфиг — /etc/litellm/config.yaml. Ключи в него не пишем, только ссылки на переменные окружения через os.environ/:

model_list:
  - model_name: gpt-4o-mini
    litellm_params:
      model: openai/gpt-4o-mini
      api_key: os.environ/OPENAI_API_KEY
  - model_name: claude-sonnet
    litellm_params:
      model: anthropic/claude-sonnet-4-5
      api_key: os.environ/ANTHROPIC_API_KEY

general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY

litellm_settings:
  drop_params: true
  num_retries: 2

model_name — имя для ваших приложений, model — идентификатор у провайдера с обязательным префиксом; названия моделей меняются, сверяйтесь с документацией. Ollama подключается так же: model: ollama/llama3.1:8b и api_base: http://127.0.0.1:11434. drop_params: true заставляет шлюз выбрасывать параметры, которых модель не понимает, вместо ответа 400 — выручает, когда один код ходит в разные модели.

Секреты — в отдельный файл /etc/litellm/litellm.env:

LITELLM_MASTER_KEY=sk-<openssl rand -hex 24>
LITELLM_SALT_KEY=<openssl rand -hex 32>
OPENAI_API_KEY=sk-proj-...
DATABASE_URL=postgresql://litellm:StrongPass@127.0.0.1:5432/litellm
STORE_MODEL_IN_DB=True
UI_USERNAME=admin
UI_PASSWORD=<длинный пароль>

Права: chown root:litellm /etc/litellm/litellm.env && chmod 640 /etc/litellm/litellm.env. Именно 640 — при 600 процесс от имени litellm файл не прочитает, а 644 открывает боевые ключи любому пользователю машины.

LITELLM_SALT_KEY шифрует учётные данные в базе. В коде рядом с ней стоит предупреждение: менять значение после первого запуска нельзя, иначе сохранённые модели и ключи перестанут расшифровываться. Сгенерируйте один раз, положите в бэкап рядом с дампом базы и не трогайте.

Шаг 4. PostgreSQL 16, первый запуск и проверка

Из репозитория 24.04 приезжает PostgreSQL 16-й ветки, PGDG не нужен:

sudo -u postgres psql -c "CREATE USER litellm WITH PASSWORD 'StrongPass';"
sudo -u postgres psql -c "CREATE DATABASE litellm OWNER litellm;"

База нужна не для запросов, а для всего вокруг: виртуальные ключи с бюджетами, история трат, веб-интерфейс. Без неё останется один мастер-ключ и модели из файла.

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

sudo -u litellm bash -c 'set -a; . /etc/litellm/litellm.env; set +a; \
  /opt/litellm/venv/bin/litellm --config /etc/litellm/config.yaml \
  --host 127.0.0.1 --port 4000 --detailed_debug'

Здесь же самая коварная особенность: если 4000 занят, LiteLLM не падает, а молча выбирает случайный порт в диапазоне 1024–49152. В логе бодрое сообщение о запуске, а nginx с proxy_pass на 127.0.0.1:4000 отдаёт 502. Проверяйте, где процесс висит:

ss -lntp | grep -E '4000|litellm'

Проверка живости — эндпоинт без авторизации:

curl -s http://127.0.0.1:4000/health/liveliness   # "I'm alive!"

Не путайте его с /health: тот требует авторизации и дёргает каждую модель настоящим запросом — на мониторинге раз в десять секунд вы платите провайдерам за свой аптайм-чекер. Полные проверки включайте фоновыми, они идут раз в 300 секунд.

Боевая проверка — запрос с мастер-ключом:

curl -s http://127.0.0.1:4000/v1/chat/completions \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"ping"}]}'

Если прилетает 403 с кодом unsupported_country_region_territory, дело не в LiteLLM: так OpenAI отвечает на запросы с адресов, которые не обслуживает. Лечится сменой локации сервера.

Шаг 5. systemd-юнит и nginx со стримингом

Юнит /etc/systemd/system/litellm.service:

[Unit]
Description=LiteLLM Proxy
After=network-online.target postgresql.service

[Service]
User=litellm
Group=litellm
EnvironmentFile=/etc/litellm/litellm.env
Environment=HOME=/opt/litellm
ExecStart=/opt/litellm/venv/bin/litellm --config /etc/litellm/config.yaml \
  --host 127.0.0.1 --port 4000 --num_workers 2
Restart=always
RestartSec=5
TimeoutStartSec=180
LimitNOFILE=65535
NoNewPrivileges=true
ProtectSystem=strict
ReadWritePaths=/opt/litellm

[Install]
WantedBy=multi-user.target

Четыре строки неочевидны. Environment=HOME=/opt/litellm — prisma кладёт скачанные движки в домашний каталог. ProtectSystem=strict делает ФС только для чтения, поэтому каталог окружения разрешаем через ReadWritePaths. TimeoutStartSec=180 — первый старт с базой долгий, prisma накатывает схему. А --num_workers 2 не случайность: по умолчанию воркер один, и на заметном потоке он становится узким местом.

systemctl daemon-reload && systemctl enable --now litellm
journalctl -u litellm -f

Дальше nginx, /etc/nginx/sites-available/litellm:

server {
    listen 80;
    server_name llm.example.com;
    client_max_body_size 25m;
    location / {
        proxy_pass http://127.0.0.1:4000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

        proxy_buffering off;
        chunked_transfer_encoding off;
        proxy_read_timeout 600s;
    }
}

Три последние директивы — не украшение. Без proxy_buffering off nginx копит SSE-поток в буфере, и ответ прилетает одним куском в конце: стриминг формально работает, а пользователь десять секунд смотрит на пустой экран. Дефолтных 60 секунд proxy_read_timeout не хватает длинным ответам, обрыв на середине выглядит как сетевая ошибка.

ln -s /etc/nginx/sites-available/litellm /etc/nginx/sites-enabled/
nginx -t && systemctl reload nginx
apt install -y certbot python3-certbot-nginx && certbot --nginx -d llm.example.com

Шлюз доступен по HTTPS, админка живёт на /ui. Виртуальные ключи выдавайте каждому приложению отдельно, мастер-ключ остаётся только у вас. По теме: API-прокси к OpenAI из России и сколько RAM нужно для LiteLLM Gateway.

Какой сервер под LiteLLM брать в MAATRIX

LiteLLM почти не считает, он ждёт ответа провайдера. Нагрузка не на процессор, а на память: каждый воркер — полноценный процесс Python.

• Минимум: 2 vCPU / 4 ГБ RAM / 40 ГБ NVMe. Хватает на --num_workers 2, Postgres рядом и десятки одновременных запросов. На 2 ГБ шлюз стартует только без базы и с одним воркером, второй упирается в OOM killer.
• Комфорт: 4 vCPU / 8 ГБ / 80 ГБ NVMe. Четыре воркера, база рядом, запас на пик и на Redis, если добавите общий кеш ответов.
• Реальный расход смотрите у себя: systemctl show -p MemoryCurrent litellm покажет байты по всему юниту.

Про диск: таблица LiteLLM_SpendLogs пишет строку на каждый запрос и растёт быстрее, чем ожидаешь. Не нужен детальный аудит — отключите её через general_settings: disable_spend_logs: true, сводная статистика останется.

Локация важнее конфигурации. Ключи OpenAI, Anthropic и Google с российских адресов не работают: приходит 403 unsupported_country_region_territory, а попытки прикрыться цепочкой прокси заканчиваются блокировкой аккаунта. Поэтому шлюз ставят в США: чистый IP и прямой доступ ко всем провайдерам. Задержка Москва — Нью-Йорк порядка 110–130 мс, на фоне двух-десяти секунд генерации она незаметна: сервер в США для доступа к нейросетям здесь базовый сценарий. UK и FR берут, когда пользователи в Европе и важен GDPR, а RU — когда за шлюзом российские модели или своя Ollama.

Оплата идёт картами российских банков, через СБП, криптой или токеном MAAT — иностранная карта для сервера в США не нужна. При заказе выбирайте Ubuntu 24.04: все команды выше рассчитаны на неё, а путь от чистой машины до работающего шлюза занимает минут пятнадцать.

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