Установка шлюза

Запуск за 30 секунд

Meridian — это высокопроизводительный HTTP API-шлюз, который объединяет 20+ LLM-провайдеров (OpenAI, Anthropic, Bedrock и другие) под единым OpenAI-совместимым API. В этом разделе вы поднимете шлюз без файла конфигурации, войдёте в веб-интерфейс и сделаете первый запрос к LLM.

1. Запустите контейнер

docker pull ghcr.io/neria-cloud/meridian:latest
docker run --rm -p 8080:8080 ghcr.io/neria-cloud/meridian:latest

Чтобы данные сохранялись между перезапусками, монтируйте каталог хоста или именованный том в /app/data — там Meridian хранит SQLite-базу конфигурации (config.db) и журнал запросов (logs.db):

# Постоянное хранилище через bind-mount каталога хоста
docker run -p 8080:8080 -v $(pwd)/data:/app/data ghcr.io/neria-cloud/meridian:latest

# Либо через именованный docker-том
docker volume create meridian-data
docker run -p 8080:8080 -v meridian-data:/app/data ghcr.io/neria-cloud/meridian:latest

Можно зафиксировать неизменяемый тег вместо latest:

docker pull ghcr.io/neria-cloud/meridian:v1.1.0

2. Флаги запуска

Каталог приложения (-app-dir) определяет, где Meridian хранит все свои данные:

В Docker каталог по умолчанию - /app/data. Смонтируйте сюда том, чтобы состояние пережило docker rm.

В каталоге хранятся:

• config.json — необязательный файл конфигурации (см. ниже два режима)
• config.db — SQLite с конфигурацией, управляемой через UI
• logs.db — SQLite с журналом запросов

3. Откройте веб-интерфейс

Перейдите в браузере по адресу http://localhost:8080:

# macOS
open http://localhost:8080

# Linux
xdg-open http://localhost:8080

# Windows
start http://localhost:8080

При первом запуске без файла конфигурации Meridian сидит таблицу пользователей значениями по умолчанию и автоматически включает аутентификацию. Войдите с учётными данными:

• Логин: admin
• Пароль: admin

📷 Скриншот-плейсхолдер: /media/quick-start/setting-up/admin-login.png — экран входа Meridian с предзаполненным admin.

Веб-интерфейс предоставляет:

• Подключение провайдеров — добавляйте API-ключи без правки кода
• Конфигурацию в реальном времени — изменения применяются мгновенно
• Наблюдаемость — журнал запросов, метрики Prometheus, аналитику
• Управление доступом — виртуальные ключи, бюджеты, лимиты

4. Первый запрос к LLM

После входа добавьте провайдера OpenAI в Providers (или через API) и сделайте первый запрос:

curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [{"role": "user", "content": "Привет, Meridian!"}]
  }'

🎉 Готово. Meridian принимает запросы и маршрутизирует их в выбранного провайдера.

Что произошло

1. Запуск без конфигурации — Meridian стартовал без файла настроек; всё конфигурируется через UI или API.
2. OpenAI-совместимый API — все эндпоинты следуют формату OpenAI, поэтому существующие SDK работают «как есть».
3. Единая точка входа — /v1/chat/completions принимает запросы для любого провайдера (OpenAI, Anthropic, Bedrock и т. д.).
4. Маршрутизация по префиксу — openai/gpt-4o-mini указывает Meridian направить запрос в OpenAI с моделью gpt-4o-mini.
5. Автоматическая обработка — Meridian сам решает вопросы аутентификации, ретраев и фолбэков.

Два режима конфигурации

Meridian поддерживает два подхода к настройке. Использовать их одновременно нельзя — выбирайте один.

Режим 1: Веб-интерфейс

Активен в двух случаях:

• config.json отсутствует — Meridian создаёт SQLite-базу автоматически, сидит admin/admin (см. выше) и включает аутентификацию.
• config.json присутствует и содержит секцию config_store — UI работает поверх внешнего хранилища.

Это режим по умолчанию для тех, кто следует сценарию zero-config. Готовый пример с включённым SQLite-хранилищем лежит в репозитории — см. examples/local-sqlite-extended/.

📷 Скриншот-плейсхолдер: /media/quick-start/setting-up/ui-config.png — экран настройки в веб-интерфейсе.

Режим 2: Файловая конфигурация

Используйте, когда нужны GitOps-процессы, окружения без веб-интерфейса или строгая декларативная схема.

Создайте config.json в каталоге приложения:

{
  "$schema": "https://meridian.neria.cloud/schema",
  "client": {
    "drop_excess_requests": false
  },
  "providers": {
    "openai": {
      "keys": [
        {
          "name": "openai-key-1",
          "value": "env.OPENAI_API_KEY",
          "models": ["gpt-4o-mini", "gpt-4o"],
          "weight": 1.0
        }
      ]
    }
  },
  "config_store": {
    "enabled": true,
    "type": "sqlite",
    "config": {
      "path": "/app/data/config.db"
    }
  }
}

Если config_store отсутствует:

• UI выключен — конфигурацию через интерфейс менять нельзя
• Режим read-only — Meridian не модифицирует config.json
• Конфигурация загружается в память при старте
• Изменения в config.json применяются только после перезапуска

Если config_store присутствует:

• UI включён — полная конфигурация в реальном времени через интерфейс
• При старте Meridian проверяет, есть ли в БД данные:
  • Пустая БД — данные из config.json бутстрапятся в БД, далее используется только БД
  • Существующая БД — config.json игнорируется, источник истины — БД
• Изменения сразу сохраняются в БД и переживают перезапуск

Три хранилища:

• Config Store — конфигурация провайдеров, API-ключей, MCP. Обязателен для UI.
• Logs Store — журнал запросов, отображаемый в UI. Опциональный.
• Vector Store — векторное хранилище для семантического кэша. Опциональный.

Требование UTF-8 для PostgreSQL

Если для config_store или logs_store вы используете PostgreSQL, целевая база данных должна быть в кодировке UTF8.

Создавайте БД на основе template0, чтобы PostgreSQL применил кодировку и locale явно:

CREATE DATABASE meridian
  WITH TEMPLATE template0
       ENCODING 'UTF8'
       LC_COLLATE '<your-locale>'
       LC_CTYPE '<your-locale>';

Используйте locale, который установлен в вашем образе или хосте (например, en_US.UTF-8, C.UTF-8 или другой UTF-8 locale).

Проверьте кодировку существующей БД:

SELECT datname, pg_encoding_to_char(encoding) AS encoding
FROM pg_database
WHERE datname = 'meridian';

Если БД не в UTF8, при запуске и миграциях Meridian упадёт с ошибкой:

simple protocol queries must be run with client_encoding=UTF8

В таком случае создайте новую БД в UTF8 и переключите конфигурацию Meridian на неё.

Удачи с Meridian! 🚀