Маршрутизация запросов к провайдерам

Обзор

Meridian предлагает два мощных механизма распределения запросов между провайдерами, каждый под свои сценарии:

1. Governance-routing — явные пользовательские правила маршрутизации, заданные через виртуальные ключи.
2. Адаптивная балансировка — автоматическая маршрутизация по производительности, основанная на метриках в реальном времени (Enterprise).

Когда оба механизма доступны, приоритет у governance — пользователь явно задал свои предпочтения через provider configurations виртуальных ключей.

Каталог моделей (Model Catalog)

Каталог моделей — это центральный реестр Meridian, отслеживающий, какие модели доступны у каких провайдеров. Он питает и governance-routing, и адаптивную балансировку, поддерживая в актуальном состоянии маппинг «модель → провайдер».

Источники данных

Каталог объединяет два источника:

1. Pricing-данные (основной источник).

   • Скачиваются с удалённого URL (настраиваемый, по умолчанию https://meridian.neria.cloud/datasheet).
   • Содержат имена моделей, тарифы и сопоставление с провайдерами.
   • Синхронизируются в БД при старте и периодически обновляются (по умолчанию раз в 24 часа).
   • Используются для расчёта стоимости и первичного маппинга.
   • Хранение: in-memory map pricingData[model|provider|mode] с O(1)-доступом.

2. List Models API провайдеров (вторичный источник).

   • Запрос к эндпоинту /v1/models каждого провайдера при старте.
   • Обогащает каталог provider-specific моделями и алиасами.
   • Перезапрашивается при добавлении/обновлении провайдера через API или панель управления.
   • Добавляет модели, которых ещё нет в pricing-данных (например, только что выпущенные).
   • Хранение: in-memory map modelPool[provider][]models.

Как определяется доступность модели

Поведение синхронизации

Поведение allowed_models с примерами

Поле allowed_models в provider-конфигах определяет, какие модели можно использовать с данным провайдером. Понимание его поведения критично для governance-routing.

{
  "provider_configs": [
    {
      "provider": "openai",
      "allowed_models": ["*"],
      "weight": 1.0
    }
  ]
}

# ✅ Разрешено (есть в каталоге)
curl -H "x-bf-vk: vk-123" -d '{"model": "gpt-4o"}'

# ✅ Разрешено
curl -H "x-bf-vk: vk-123" -d '{"model": "gpt-3.5-turbo"}'

# ❌ Отклонено (нет в каталоге OpenAI)
curl -H "x-bf-vk: vk-123" -d '{"model": "claude-3-5-sonnet"}'

{
  "provider_configs": [
    {
      "provider": "openai",
      "allowed_models": ["gpt-4o", "gpt-4o-mini"],
      "weight": 1.0
    },
    {
      "provider": "anthropic",
      "allowed_models": ["claude-3-5-sonnet-20241022"],
      "weight": 1.0
    }
  ]
}

# ✅ Разрешено
curl -H "x-bf-vk: vk-123" -d '{"model": "gpt-4o"}'

# ❌ Отклонено (нет в списке)
curl -H "x-bf-vk: vk-123" -d '{"model": "gpt-4-turbo"}'
# даже если gpt-4-turbo есть в каталоге OpenAI

# ✅ Разрешено
curl -H "x-bf-vk: vk-123" -d '{"model": "claude-3-5-sonnet-20241022"}'

# ❌ Отклонено (несовпадение версии)
curl -H "x-bf-vk: vk-123" -d '{"model": "claude-3-5-sonnet-20240620"}'

{
  "provider_configs": [
    {
      "provider": "openrouter",
      "allowed_models": ["openai/gpt-4o", "anthropic/claude-3-5-sonnet"],
      "weight": 1.0
    }
  ]
}

# Запрос без префикса
curl -H "x-bf-vk: vk-123" -d '{"model": "gpt-4o"}'

# 1. Проверяется: "openai/gpt-4o" в allowed_models
# 2. Префикс снимается: "openai/gpt-4o" → "gpt-4o"
# 3. Сравнение: "gpt-4o" == "gpt-4o" ✅
# 4. Результат: разрешено и маршрутизируется в OpenRouter

{
  "providers": {
    "azure": {
      "keys": [
        {
          "name": "azure-prod-key",
          "value": "your-api-key",
          "models": [],
          "azure_key_config": {
            "endpoint": "https://your-resource.openai.azure.com",
            "deployments": {
              "gpt-4o": "my-prod-gpt4o-deployment",
              "gpt-4o-mini": "my-mini-deployment"
            }
          }
        }
      ]
    }
  }
}

{
  "providers": {
    "bedrock": {
      "keys": [
        {
          "name": "bedrock-key",
          "models": [],
          "bedrock_key_config": {
            "access_key": "your-access-key",
            "secret_key": "your-secret-key",
            "region": "us-east-1",
            "deployments": {
              "claude-sonnet": "us.anthropic.claude-3-5-sonnet-20241022-v2:0",
              "claude-opus": "us.anthropic.claude-3-opus-20240229-v1:0"
            }
          }
        }
      ]
    }
  }
}

1. Если key.models НЕ пуст → используется key.models
2. Иначе если есть deployments → используются алиасы deployments
3. Иначе → разрешены все модели (через Model Catalog)

{
  "keys": [
    {
      "models": ["gpt-4o", "gpt-3.5-turbo"],
      "azure_key_config": {
        "deployments": {
          "gpt-4o": "my-deployment",
          "gpt-4-turbo": "another-deployment"
        }
      }
    }
  ]
}

{
  "keys": [
    {
      "vertex_key_config": {
        "project_id": "my-project",
        "region": "us-central1",
        "deployments": {
          "claude-3-5-sonnet": "anthropic/claude-3-5-sonnet@20241022",
          "gemini-pro": "google/gemini-1.5-pro"
        }
      }
    }
  ]
}

Запрос: {"model": "gpt-4o"}
         ↓
Валидация: "gpt-4o" в allowed models (выведенных из deployments)
         ↓
Маппинг: deployments["gpt-4o"] → "my-prod-gpt4o-deployment"
         ↓
API-вызов: используется "my-prod-gpt4o-deployment"
         ↓
Pricing: fallback на "gpt-4o", если deployment'а нет в pricing-данных

{
  "provider_configs": [
    {
      "provider": "openai",
      "allowed_models": ["gpt-4o"],
      "weight": 0.5
    },
    {
      "provider": "azure",
      "allowed_models": ["gpt-4o"],
      "weight": 0.5
    }
  ]
}

curl -H "x-bf-vk: vk-123" \
     -d '{"model": "gpt-4o"}'

{
  "provider_configs": [
    {
      "provider": "openrouter",
      "allowed_models": ["*"]
    }
  ]
}

{
  "provider_configs": [
    {
      "provider": "openai",
      "allowed_models": ["gpt-4o"],
      "weight": 0.01
    },
    {
      "provider": "openrouter",
      "allowed_models": ["openai/gpt-4o"],
      "weight": 0.99
    }
  ]
}

{
  "provider_configs": [
    {
      "provider": "vertex",
      "allowed_models": ["claude-3-5-sonnet", "gemini-1.5-pro"]
    }
  ]
}

{
  "provider_configs": [
    {
      "provider": "groq",
      "allowed_models": ["gpt-3.5-turbo"]
    }
  ]
}

Как каталог используется в маршрутизации

{
  "provider_configs": [
    {
      "provider": "openai",
      "allowed_models": ["*"],
      "weight": 0.5
    }
  ]
}

curl -H "x-bf-vk: vk-123" -d '{"model": "gpt-4o"}'

# 1. Governance: есть ли "gpt-4o" в GetModelsForProvider("openai")?
# 2. Каталог: modelPool["openai"] содержит "gpt-4o" ✅
# 3. Валидация прошла, провайдер выбран
# 4. Модель становится: "openai/gpt-4o"

curl -H "x-bf-vk: vk-123" -d '{"model": "claude-3-5-sonnet"}'

# 1. Governance: есть ли "claude-3-5-sonnet" в GetModelsForProvider("openai")?
# 2. Каталог: modelPool["openai"] НЕ содержит "claude-3-5-sonnet" ❌
# 3. Валидация не прошла, запрос отклонён
# 4. Ошибка: "model not allowed for any configured provider"

curl -X POST http://localhost:8080/v1/chat/completions \
  -d '{"model": "gpt-4o", "messages": [...]}'

# 1. LB: GetProvidersForModel("gpt-4o")
# 2. Каталог: ["openai", "azure", "groq"]
# 3. Фильтр по настроенным провайдерам: ["openai", "azure"] (groq не настроен)
# 4. Скоринг: openai=0.95, azure=0.87
# 5. Выбран: openai
# 6. Модель: "openai/gpt-4o"
# 7. Fallbacks: ["azure/gpt-4o"]

curl -d '{"model": "claude-3-5-sonnet"}'

# 1. LB: GetProvidersForModel("claude-3-5-sonnet")
# 2. Проверки каталога:
#    - Прямой: ["anthropic"] ✅
#    - OpenRouter: содержит "anthropic/claude-3-5-sonnet" ✅
#    - Vertex: содержит "anthropic/claude-3-5-sonnet" ✅
#    - Bedrock: содержит "anthropic.claude-3-5-sonnet-..." ✅
# 3. Каталог: ["anthropic", "openrouter", "vertex", "bedrock"]
# 4. Скоринг по всем четырём
# 5. Выбран лучший по производительности

Governance-routing

Governance-routing позволяет явно задать провайдеров и модели, обслуживающих запросы для конкретного виртуального ключа. Этот метод даёт точный контроль над решениями маршрутизации.

Как это работает

Когда у виртуального ключа определены provider_configs:

1. Запрос приходит с виртуальным ключом (например, x-bf-vk: vk-prod-main).
2. Валидация модели: Meridian проверяет, разрешена ли модель хотя бы у одного настроенного провайдера.
3. Фильтрация провайдеров по:
   • наличию модели в allowed_models;
   • бюджетам (текущее использование vs максимум);
   • rate limit'ам (токены/запросы за окно).
4. Взвешенный выбор: провайдер выбирается weighted random.
5. Префикс провайдера: строка модели становится provider/model (например, openai/gpt-4o).
6. Fallbacks: оставшиеся провайдеры сортируются по убыванию веса и добавляются как fallbacks.

Пример конфигурации

{
  "provider_configs": [
    {
      "provider": "openai",
      "allowed_models": ["gpt-4o", "gpt-4o-mini"],
      "weight": 0.3,
      "budget": {
        "max_limit": 100.0,
        "current_usage": 45.0
      }
    },
    {
      "provider": "azure",
      "allowed_models": ["gpt-4o"],
      "weight": 0.7,
      "rate_limit": {
        "token_max_limit": 100000,
        "token_reset_duration": "1m"
      }
    }
  ]
}

Поток запроса

curl -X POST http://localhost:8080/v1/chat/completions \
  -H "x-bf-vk: vk-prod-main" \
  -d '{"model": "gpt-4o", "messages": [...]}'

{
  "model": "azure/gpt-4o",
  "messages": [...],
  "fallbacks": ["openai/gpt-4o"]
}

Возможности

Лучшие практики

Адаптивная балансировка

Адаптивная балансировка автоматически оптимизирует маршрутизацию по метрикам производительности в реальном времени. Работает на двух уровнях: macro-уровне (выбор провайдера) и micro-уровне (выбор ключа).

Двухуровневая архитектура

Разделение выбора провайдера (направления) и выбора ключа (маршрута) даёт:

• Оптимизацию на уровне провайдера — лучший провайдер для модели по агрегированной производительности;
• Оптимизацию на уровне ключа — внутри провайдера выбирается лучший API-ключ;
• Устойчивость — даже когда провайдер задан явно (governance или пользователем), оптимизация ключа продолжает работать.

Уровень 1: направление (выбор провайдера)

Когда выполняется: только когда строка модели не содержит префикс провайдера (например, gpt-4o).

Как:

1. Поиск в каталоге — все настроенные провайдеры, поддерживающие модель.
2. Фильтрация по:
   • allowed_models из конфигурации ключей;
   • доступности ключей у провайдера.
3. Скоринг производительности:
   • error rates (вес 50 %);
   • latency (вес 20 %, алгоритм MV-TACOS);
   • utilization (вес 5 %);
   • momentum bias (ускорение восстановления).
4. Smart selection: weighted random с jitter и exploration.
5. Fallbacks: оставшиеся провайдеры сортируются по убыванию score.

Уровень 2: маршрут (выбор ключа)

Когда выполняется: всегда, даже если провайдер уже выбран (governance, пользователем или уровнем 1).

Как:

1. Сбор ключей провайдера.
2. Фильтрация по конфигурации (ограничения по моделям).
3. Скоринг каждого ключа:
   • error rates (недавние сбои);
   • latency;
   • TPM hits (нарушения rate limit);
   • текущее состояние (Healthy, Degraded, Failed, Recovering).
4. Weighted random с exploration (25 % шанс «зондирования» recovering-ключа).
5. Circuit breaker: ключи с весом 0 пропускаются (TPM hits, повторные сбои).

Алгоритм скоринга

Балансировщик считает score для каждой пары provider-model:

Score = (P_error × 0.5) + (P_latency × 0.2) + (P_util × 0.05) − M_momentum

Поток запроса

curl -X POST http://localhost:8080/v1/chat/completions \
  -d '{"model": "gpt-4o", "messages": [...]}'

{
  "model": "openai/gpt-4o",
  "messages": [...],
  "fallbacks": ["azure/gpt-4o", "groq/gpt-4o"]
}

Возможности

Видимость в дашборде

Мониторинг балансировки в реальном времени:

В дашборде отображается:

• распределение весов по маршрутам provider-model-key;
• метрики производительности (error rate, latency, success rate);
• переходы состояний (Healthy → Degraded → Failed → Recovering);
• фактическое vs ожидаемое распределение трафика.

Как governance и балансировка взаимодействуют

Когда оба механизма доступны, они работают согласованно по двум уровням.

Поток выполнения

Порядок выполнения

1. HTTPTransportIntercept (governance, уровень провайдера) — выполняется первым; если у виртуального ключа есть provider_configs, добавляет префикс провайдера. Результат: провайдер выбран governance.
2. Middleware (балансировка, уровень провайдера / направление) — после governance; если в строке модели уже есть /, пропускает выбор провайдера; иначе делает performance-based выбор. Результат: префикс добавлен, если его не было.
3. KeySelector (балансировка, уровень ключа / маршрут) — всегда выполняется во время исполнения запроса в ядре Meridian: получает ключи провайдера, фильтрует по ограничениям модели, скорит и выбирает лучший. Результат: оптимальный ключ внутри выбранного провайдера.

Сценарии

curl -X POST http://localhost:8080/v1/chat/completions \
  -H "x-bf-vk: vk-prod-main" \
  -d '{"model": "gpt-4o", "messages": [...]}'

curl -X POST http://localhost:8080/v1/chat/completions \
  -d '{"model": "gpt-4o", "messages": [...]}'

curl -X POST http://localhost:8080/v1/chat/completions \
  -H "x-bf-vk: vk-prod-main" \
  -d '{"model": "gpt-4o", "messages": [...]}'

curl -X POST http://localhost:8080/v1/chat/completions \
  -d '{"model": "openai/gpt-4o", "messages": [...]}'

Правила выбора провайдера и ключа

Правила маршрутизации (динамические выражения)

Кратко

Правила маршрутизации дают expression-based контроль через CEL. В отличие от governance (статические веса), правила оцениваются в момент запроса.

Когда выполняются

Как это работает

1. Правила оцениваются первыми в порядке scope (VirtualKey → Team → Customer → Global).
2. Если правило совпало: provider/model/fallbacks переопределяются, governance provider_configs пропускается.
3. Если совпадений нет: работает governance (weighted random).
4. LB уровня 1 пропускается, если провайдер уже определён (есть /).
5. LB уровня 2 (выбор ключа) работает всегда.

Доступные CEL-переменные

// Контекст запроса
model                      // Запрошенная модель
provider                   // Текущий провайдер

// Заголовки и параметры (без учёта регистра)
headers["x-tier"]          // Заголовок запроса
params["region"]           // Query-параметр

// Контекст организации
virtual_key_id             // ID виртуального ключа
team_name                  // Имя команды
customer_id                // ID клиента

// Метрики потребления (0–100 %)
budget_used                // Использование бюджета
tokens_used                // Использование токенового rate limit
request                    // Использование request rate limit

Примеры

По тарифу пользователя

headers["x-tier"] == "premium"   // → openai/gpt-4o

Fallback при высоком бюджете

budget_used > 85                 // → groq/llama-2 (дешевле)

По команде

team_name == "ml-research"       // → anthropic/claude-3-opus

Сложное многокритериальное

headers["x-environment"] == "production" &&
tokens_used < 75 &&
team_name == "ai-platform"       // → openai/gpt-4o

Иерархия scope

Правила оцениваются по precedence (first-match-wins):

1. VirtualKey scope (наивысший)
2. Team scope
3. Customer scope
4. Global scope (низший)

Внутри одного scope — по приоритету (по возрастанию: 0 раньше 10).

Возможности

Подробная документация: Правила маршрутизации.

Как выбрать подход

1. Используйте governance, когда:

   • ✅ требуется compliance (данные в определённом регионе/провайдере);
   • ✅ нужен явный контроль над оптимизацией стоимости;
   • ✅ нужны жёсткие лимиты бюджета на провайдера;
   • ✅ разделение окружений (разные команды/приложения, разные провайдеры);
   • ✅ управление rate limit'ами провайдеров.

2. Используйте правила маршрутизации, когда:

   • ✅ нужна динамическая маршрутизация по runtime-контексту (заголовки, параметры);
   • ✅ нужен capacity-aware routing (fallback при росте бюджета или rate limit);
   • ✅ организационные правила (разные правила для команд/клиентов);
   • ✅ A/B-тесты;
   • ✅ сложные условия (тариф + capacity + команда).

3. Используйте балансировку, когда:

   • ✅ нужна автоматическая оптимизация по производительности;
   • ✅ хочется минимума настройки;
   • ✅ нагрузки часто меняются;
   • ✅ нужен мгновенный авто-failover;
   • ✅ нужна устойчивость через multi-provider redundancy.

4. Используйте всё вместе, когда:

   • ✅ нужно полное решение: governance задаёт базу, правила добавляют динамику, балансировка оптимизирует ключи;
   • ✅ разные виртуальные ключи используют разные стратегии;
   • ✅ enterprise-развёртывания со сложной структурой требований.