Бюджеты и лимиты

Enterprise-уровень управления бюджетами и контроля расходов с иерархическим распределением через виртуальные ключи, команды и клиентов.

Обзор

Бюджеты и rate limits — базовая возможность governance Meridian, управляемая через виртуальные ключи.

Система управления бюджетами Meridian обеспечивает полноценный контроль расходов и финансовый governance в enterprise-развёртываниях. Она работает поверх иерархической структуры бюджетов, что даёт точечное управление расходами, отслеживание использования и финансовый контроль по всей организации.

Базовая иерархия:

Customer (независимый бюджет)
    ↓ (один ко многим)
Team (независимый бюджет)
    ↓ (один ко многим)
Virtual Key (независимый бюджет + rate limits)
    ↓ (один ко многим)
Provider Config (независимый бюджет + rate limits)

ИЛИ

Customer (независимый бюджет)
    ↓ (прямая привязка)
Virtual Key (независимый бюджет + rate limits)
    ↓ (один ко многим)
Provider Config (независимый бюджет + rate limits)

ИЛИ

Virtual Key (отдельный — независимый бюджет + rate limits)
    ↓ (один ко многим)
Provider Config (независимый бюджет + rate limits)

Ключевые возможности:

Виртуальные ключи — основной контроль доступа через заголовок x-bf-vk (взаимоисключающая привязка к команде ИЛИ клиенту);
Управление бюджетами — независимые лимиты на каждом уровне иерархии с накопительной проверкой;
Rate limits — ограничения по запросам и токенам на уровне VK и provider config;
Governance на уровне провайдера — точечные бюджеты и rate limits для каждого AI-провайдера внутри VK;
Фильтрация моделей и провайдеров — точечный контроль доступа на уровне VK;
Отслеживание использования — мониторинг и audit trail в реальном времени;
Audit-заголовки — опциональная идентификация команды и клиента.

Управление бюджетом

Расчёт стоимости

Meridian автоматически рассчитывает стоимость на основе:

Цены провайдера — актуальные тарифы моделей;
Использование токенов — input + output токены из ответа API;
Тип запроса — разные тарифы для chat, text, embedding, speech, transcription;
Статус кэша — пониженная стоимость для кэшированных ответов;
Batch-операции — объёмные скидки для batch-запросов.

Подробности расчёта стоимости описаны в Architecture → Framework → Model Catalog.

Поток проверки бюджета

При запросе с виртуальным ключом Meridian независимо проверяет все применимые бюджеты в иерархии. На каждом из них должно быть достаточно остатка, чтобы запрос прошёл.

Последовательность проверки.

Для VK → Team → Customer:

1. ✓ Бюджет provider config (если у provider config есть бюджет)
2. ✓ Бюджет VK (если у VK есть бюджет)
3. ✓ Бюджет команды (если у команды VK есть бюджет)
4. ✓ Бюджет клиента (если у клиента команды есть бюджет)

Для VK → Customer (напрямую):

1. ✓ Бюджет provider config (если у provider config есть бюджет)
2. ✓ Бюджет VK (если у VK есть бюджет)
3. ✓ Бюджет клиента (если у клиента VK есть бюджет)

Для отдельного VK:

1. ✓ Бюджет provider config (если у provider config есть бюджет)
2. ✓ Бюджет VK (если у VK есть бюджет)

Важные моменты:

Должны пройти все применимые бюджеты — отказ хоть одного блокирует запрос.
Бюджеты независимы — каждый ведёт своё использование и лимиты.
Стоимость списывается со всех применимых бюджетов — одинаковая стоимость на каждом уровне.
Rate limits проверяются на уровнях provider config и VK — у команд и клиентов rate limits нет.
Выбор провайдера — провайдеры, превысившие бюджет или rate limits, исключаются из маршрутизации.

Пример:

- Бюджет provider config: остаток $4 / $5 ✓
- Бюджет VK: остаток $9 / $10 ✓
- Бюджет команды: остаток $15 / $20 ✓
- Бюджет клиента: остаток $45 / $50 ✓
- Результат: разрешено (ни один бюджет не превышен)

- После запроса:
    - Стоимость запроса: $2
    - Обновлённые: Provider=$6/$5, VK=$11/$10, Team=$17/$20, Customer=$47/$50
    - Следующий запрос будет заблокирован (превышены бюджеты Provider и VK).

Rate limits

Rate limits защищают систему от злоупотреблений и управляют трафиком, задавая пороги частоты запросов и использования токенов в фиксированном временном окне. Rate limits можно настраивать и на уровне виртуального ключа, и на уровне provider config — для точечного контроля.

Meridian поддерживает два типа rate limits, работающих параллельно:

Request limits — максимум API-вызовов в заданном окне (например, 100 запросов в минуту).
Token limits — максимум токенов (prompt + completion) в заданном окне (например, 50 000 токенов в час).

Иерархия rate limits

Rate limits проверяются в иерархическом порядке:

1. ✓ Rate limits provider config (если они заданы у provider config)
2. ✓ Rate limits виртуального ключа (если они заданы у VK)

Чтобы запрос прошёл, он должен пройти проверку и по числу запросов, и по токенам на всех применимых уровнях. Если provider config превысил свои rate limits, этот провайдер исключается из маршрутизации, но остальные провайдеры внутри того же VK остаются доступны.

Rate limits на уровне провайдера

Provider configs внутри виртуального ключа могут иметь независимые rate limits, что даёт:

Throttling по провайдерам — разные лимиты для OpenAI и Anthropic;
Изоляцию провайдеров — превышение rate limit одним провайдером не влияет на остальных;
Точечный контроль — тонкая настройка под возможности и стоимость каждого провайдера.

Reset durations

Бюджеты и rate limits поддерживают гибкие интервалы сброса:

Примеры формата:

1m — 1 минута;
5m — 5 минут;
1h — 1 час;
1d — 1 день;
1w — 1 неделя;
1M — 1 месяц;
1Y — 1 год.

Типичные паттерны:

Rate limits — 1m, 1h, 1d для throttling запросов;
Бюджеты — 1d, 1w, 1M, 1Y для контроля расходов.

Calendar-aligned бюджеты

По умолчанию бюджет скользящий: использование сбрасывается после того, как с момента last_reset прошло reset_duration. С опцией calendar_aligned: true бюджет вместо этого сбрасывается в начале каждого календарного периода в UTC (один и тот же момент для всех клиентов с такой настройкой).

Поддерживаемые суффиксы reset_duration: только день (d), неделя (w), месяц (M) и год (Y). Примеры: 1d → каждая полночь UTC; 1w → каждый понедельник в 00:00 UTC; 1M → первое число каждого месяца; 1Y → 1 января. Для интервалов короче суток (например, 1h, 30m) выравнивание по календарю недоступно — API отклоняет некорректные комбинации.

Calendar alignment применяется к бюджетам клиентов, команд, виртуальных ключей и per-provider-config. Опция задаётся при создании бюджета (calendar_aligned в create) или переключается при обновлении (calendar_aligned в PUT-запросе на бюджет). Включение calendar alignment у существующего бюджета обнуляет текущее использование и подтягивает last_reset к началу текущего периода.

Как настроить

Настройте бюджеты и rate limits на уровне провайдера любым из способов:

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

Создание VK с provider configs

Перейдите в Virtual Keys — откройте страницу Virtual Keys в панели управления Meridian.
Создайте новый VK — нажмите кнопку Create Virtual Key.
Настройте провайдеров — в разделе Provider Configurations:
- добавьте несколько провайдеров с индивидуальными весами;
- задайте бюджеты и rate limits для каждого провайдера;
- укажите разрешённые модели для каждого провайдера.

Интерфейс конфигурации провайдера

Ключевые элементы:

Карточки провайдеров — каждый провайдер представлен раскрывающейся карточкой;
Контроль бюджета — лимит расходов с периодом сброса для каждого провайдера;
Контроль rate limits — независимая настройка лимитов по токенам и запросам;
Фильтрация моделей — список разрешённых моделей для каждого провайдера;
Распределение веса — визуальные индикаторы весов балансировки;
Валидация в реальном времени — мгновенная обратная связь по ошибкам конфигурации.

Мониторинг использования провайдеров

Info-sheet виртуального ключа даёт мониторинг в реальном времени:

расход бюджета по провайдерам;
использование rate limits (токены и запросы);
статус доступности провайдера;
тренды использования и прогноз.

Используйте HTTP API Meridian, чтобы программно управлять конфигурациями governance на уровне провайдера.

Создать VK с provider configs

curl -X POST "http://localhost:8080/api/governance/virtual-keys" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "marketing-team-vk",
    "description": "Marketing team virtual key with provider-specific limits",
    "provider_configs": [
      {
        "provider": "openai",
        "weight": 0.7,
        "allowed_models": ["gpt-4", "gpt-3.5-turbo"],
        "budget": {
          "max_limit": 500.00,
          "reset_duration": "1M",
          "calendar_aligned": true
        },
        "rate_limit": {
          "token_max_limit": 1000000,
          "token_reset_duration": "1h",
          "request_max_limit": 1000,
          "request_reset_duration": "1h"
        }
      },
      {
        "provider": "anthropic",
        "weight": 0.3,
        "allowed_models": ["claude-3-opus", "claude-3-sonnet"],
        "budget": {
          "max_limit": 200.00,
          "reset_duration": "1M"
        },
        "rate_limit": {
          "token_max_limit": 500000,
          "token_reset_duration": "1h",
          "request_max_limit": 500,
          "request_reset_duration": "1h"
        }
      }
    ],
    "budget": {
      "max_limit": 1000.00,
      "reset_duration": "1M",
      "calendar_aligned": true
    },
    "is_active": true
  }'

calendar_aligned используйте только с интервалами d / w / M / Y (см. Calendar-aligned бюджеты).

Обновить конфигурацию провайдера

curl -X PUT "http://localhost:8080/api/governance/virtual-keys/{vk_id}" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_configs": [
      {
        "id": 1,
        "provider": "openai",
        "weight": 0.8,
        "budget": {
          "max_limit": 600.00,
          "reset_duration": "1M"
        },
        "rate_limit": {
          "token_max_limit": 1200000,
          "token_reset_duration": "1h"
        }
      }
    ]
  }'

Структура ответа API

{
  "message": "Virtual key created successfully",
  "virtual_key": {
    "id": "vk_123",
    "name": "marketing-team-vk",
    "value": "vk_abc123def456",
    "provider_configs": [
      {
        "id": 1,
        "provider": "openai",
        "weight": 0.7,
        "allowed_models": ["gpt-4", "gpt-3.5-turbo"],
        "budget": {
          "id": "budget_789",
          "max_limit": 500.00,
          "current_usage": 0.00,
          "reset_duration": "1M",
          "calendar_aligned": true,
          "last_reset": "2024-01-01T00:00:00Z"
        },
        "rate_limit": {
          "id": "rate_limit_456",
          "token_max_limit": 1000000,
          "token_current_usage": 0,
          "token_reset_duration": "1h",
          "token_last_reset": "2024-01-01T00:00:00Z",
          "request_max_limit": 1000,
          "request_current_usage": 0,
          "request_reset_duration": "1h",
          "request_last_reset": "2024-01-01T00:00:00Z"
        }
      }
    ]
  }
}

Описания полей

Поле	Тип	Описание
`provider`	string	Имя AI-провайдера (например, `openai`, `anthropic`)
`weight`	float	Вес для балансировки нагрузки (0.0–1.0)
`allowed_models`	array	Конкретные модели, разрешённые для этого провайдера
`budget.max_limit`	float	Максимальный расход в USD
`budget.reset_duration`	string	Период сброса (например, `1h`, `1d`, `1M`)
`budget.calendar_aligned`	boolean	При `true` сбрасывается по календарным границам в UTC (требует `d`/`w`/`M`/`Y`)
`rate_limit.token_max_limit`	integer	Максимум токенов за период
`rate_limit.request_max_limit`	integer	Максимум запросов за период

Настраивайте governance на уровне провайдера в файле конфигурации Meridian для декларативного управления.

Базовая структура

{
  "governance": {
    "virtual_keys": [
      {
        "name": "development-team-vk",
        "description": "Development team with multi-provider setup",
        "provider_configs": [
          {
            "provider": "openai",
            "weight": 0.6,
            "allowed_models": ["gpt-4", "gpt-3.5-turbo"],
            "budget": {
              "max_limit": 1000.00,
              "reset_duration": "1M"
            },
            "rate_limit": {
              "token_max_limit": 2000000,
              "token_reset_duration": "1h",
              "request_max_limit": 2000,
              "request_reset_duration": "1h"
            }
          },
          {
            "provider": "anthropic",
            "weight": 0.4,
            "allowed_models": ["claude-3-opus", "claude-3-sonnet"],
            "budget": {
              "max_limit": 500.00,
              "reset_duration": "1M"
            },
            "rate_limit": {
              "token_max_limit": 1000000,
              "token_reset_duration": "1h",
              "request_max_limit": 1000,
              "request_reset_duration": "1h"
            }
          }
        ],
        "budget": {
          "max_limit": 2000.00,
          "reset_duration": "1M",
          "calendar_aligned": true
        },
        "rate_limit": {
          "token_max_limit": 5000000,
          "token_reset_duration": "1h",
          "request_max_limit": 3000,
          "request_reset_duration": "1h"
        },
        "is_active": true
      }
    ]
  }
}

Опциональный calendar_aligned в каждом budget соответствует поведению HTTP API и calendar-aligned бюджетов.

Расширенные примеры

Cost-optimized конфигурация

{
  "governance": {
    "virtual_keys": [
      {
        "name": "cost-optimized-vk",
        "provider_configs": [
          {
            "provider": "openai-gpt-3.5",
            "weight": 0.8,
            "budget": {
              "max_limit": 50.00,
              "reset_duration": "1d"
            },
            "rate_limit": {
              "request_max_limit": 1000,
              "request_reset_duration": "1h"
            }
          },
          {
            "provider": "openai-gpt-4",
            "weight": 0.2,
            "budget": {
              "max_limit": 200.00,
              "reset_duration": "1d"
            },
            "rate_limit": {
              "request_max_limit": 100,
              "request_reset_duration": "1h"
            }
          }
        ]
      }
    ]
  }
}

High-volume production конфигурация

{
  "governance": {
    "virtual_keys": [
      {
        "name": "production-high-volume-vk",
        "provider_configs": [
          {
            "provider": "openai",
            "weight": 0.5,
            "budget": {
              "max_limit": 5000.00,
              "reset_duration": "1M"
            },
            "rate_limit": {
              "token_max_limit": 10000000,
              "token_reset_duration": "1h",
              "request_max_limit": 10000,
              "request_reset_duration": "1h"
            }
          },
          {
            "provider": "anthropic",
            "weight": 0.3,
            "budget": {
              "max_limit": 3000.00,
              "reset_duration": "1M"
            },
            "rate_limit": {
              "token_max_limit": 6000000,
              "token_reset_duration": "1h",
              "request_max_limit": 6000,
              "request_reset_duration": "1h"
            }
          },
          {
            "provider": "azure-openai",
            "weight": 0.2,
            "budget": {
              "max_limit": 2000.00,
              "reset_duration": "1M"
            },
            "rate_limit": {
              "token_max_limit": 4000000,
              "token_reset_duration": "1h",
              "request_max_limit": 4000,
              "request_reset_duration": "1h"
            }
          }
        ]
      }
    ]
  }
}

Правила валидации:

Лимиты бюджета — положительные числа;
Reset duration — корректный временной формат;
Rate limits — положительные целые;
Имена провайдеров должны совпадать с настроенными провайдерами.

Примеры governance уровня провайдера

Пример 1: смешанные бюджеты провайдеров

VK с несколькими провайдерами и разными бюджетами:

{
  "name": "marketing-team-vk",
  "budget": { "max_limit": 100, "reset_duration": "1M" },
  "provider_configs": [
    {
      "provider": "openai",
      "weight": 0.7,
      "budget": { "max_limit": 50, "reset_duration": "1M" }
    },
    {
      "provider": "anthropic",
      "weight": 0.3,
      "budget": { "max_limit": 30, "reset_duration": "1M" }
    }
  ]
}

Поведение:

Запросы к OpenAI ограничены 50 USD/месяц на уровне провайдера + 100 USD/месяц на уровне VK;
Запросы к Anthropic ограничены 30 USD/месяц на уровне провайдера + 100 USD/месяц на уровне VK;
При исчерпании бюджета любого провайдера все запросы к нему блокируются.

Пример 2: rate limits по провайдеру

Разные rate limits в зависимости от возможностей провайдера:

{
  "name": "high-volume-vk",
  "provider_configs": [
    {
      "provider": "openai",
      "rate_limit": {
        "request_max_limit": 1000,
        "request_reset_duration": "1h",
        "token_max_limit": 1000000,
        "token_reset_duration": "1h"
      }
    },
    {
      "provider": "anthropic",
      "rate_limit": {
        "request_max_limit": 500,
        "request_reset_duration": "1h",
        "token_max_limit": 500000,
        "token_reset_duration": "1h"
      }
    }
  ]
}

Поведение:

OpenAI — 1000 запросов/час, 1M токенов/час;
Anthropic — 500 запросов/час, 500K токенов/час;
При превышении rate limits любого провайдера все запросы к нему блокируются.

Пример 3: стратегия failover

Конфигурация провайдеров с failover по бюджету:

{
  "name": "cost-optimized-vk",
  "provider_configs": [
    {
      "provider": "openai-cheap",
      "weight": 1.0,
      "budget": { "max_limit": 10, "reset_duration": "1d" }
    },
    {
      "provider": "openai-premium",
      "weight": 0.0,
      "budget": { "max_limit": 50, "reset_duration": "1d" },
      "rate_limit": {
        "request_max_limit": 100,
        "request_reset_duration": "1h",
        "token_max_limit": 50000,
        "token_reset_duration": "1h"
      }
    }
  ]
}

Поведение:

Основной — использовать дешёвого провайдера, пока не исчерпан суточный бюджет в $10.
Резервный — автоматически переключиться на премиум, когда дешёвый недоступен. Чтобы это работало, не передавайте имя provider в теле запроса; подробнее — Маршрутизация.
Сдерживание расходов — защита от неожиданного перерасхода на премиум-ресурсах и ограничение числа запросов к премиуму.

Чем полезен governance уровня провайдера

Точечный контроль — индивидуальные лимиты расходов и rate limits для каждого AI-провайдера;
Автоматический failover — переключение на альтернативного провайдера при превышении бюджета или rate limits;
Контроль расходов — отслеживание и ограничение трат по провайдерам для финансового надзора;
Performance testing — A/B-тесты между провайдерами с контролируемыми бюджетами;
Multi-provider стратегии — конфигурация основного и резервного провайдеров;
Тарификация по уровням — дешёвые провайдеры под базовые задачи, премиум — под сложные.

Бюджеты и лимиты

Содержание