Надёжность API

Лимит параллельных запросов AI API: как защитить очередь

Лимит параллельных запросов AI API защищает систему там, где обычного ограничения частоты недостаточно. Десять долгих операций могут занять соединения, воркеры и бюджет, хотя формально за минуту стартовало немного запросов. Контролируемый concurrency задаёт верхнюю границу незавершённой работы, а очередь сохраняет избыток в предсказуемом состоянии. Это не способ «получить больше лимитов» и не гарантия доступности: текущие ограничения маршрута, модели и проекта нужно сверять в RussiaAPI перед запуском.

Опубликовано 23 августа 2026 · 11 минут чтения · Ключевой запрос: лимит параллельных запросов AI API

Не смешивайте три разных ограничения

Rate limit отвечает на вопрос «сколько запусков можно начать за период». Лимит параллелизма отвечает «сколько операций ещё выполняется». Бюджет отвечает «сколько риска по расходам команда готова принять». У них разные симптомы и разные владельцы. Если ограничить только запросы в секунду, несколько минутных операций всё равно могут накопиться в памяти. Если установить только concurrency, короткий всплеск может перегрузить шлюз множеством запусков. Если поставить лишь бюджет, сервис останется медленным и нестабильным до момента остановки.

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

Определите, что именно занимает слот

Слот должен отражать единицу работы, которая реально удерживает ограниченный ресурс. Для обычного завершённого ответа это время от отправки до получения или отмены. Для streaming — до закрытия потока. Для видео — до момента, когда ваш воркер передал внешнюю операцию в асинхронный контур; дальнейшее ожидание task_id обычно контролируется отдельной очередью. Если не определить границу, один запрос может освободить слот слишком рано, а другой — держать его после завершения.

Заранее обработайте отмену. Когда клиент закрыл вкладку, не всегда стоит отменять уже полезную фоновую задачу, но нужно освободить пользовательское соединение и пометить интерес клиента. Когда серверный deadline истёк, нельзя автоматически предполагать, что операция не принята. Сначала зафиксируйте idempotency key и запросите статус безопасным способом. Этот порядок предотвращает дубли и описан в руководстве по повторным запросам.

Очередь делает отказ явным

Когда все слоты заняты, у приложения есть выбор: поставить работу в очередь, быстро отказать или понизить приоритет. Худший вариант — бесконечно держать HTTP-соединение без статуса. Сохраните компактную запись с владельцем, классом, временем создания, deadline и внутренним ID. Не храните API Key, заголовки Authorization или полный пользовательский текст в служебной очереди. Для чувствительных входов используйте ссылку на защищённое хранилище с контролем доступа и сроком удаления.

Очередь нуждается в максимальной длине и политике справедливости. Один проект не должен вытеснить остальных десятью тысячами задач. Можно вводить квоту на проект, отдельные очереди по приоритету и время жизни заявки. При переполнении возвращайте проверяемую причину и рекомендуйте повторить операцию позже в соответствии с правилами продукта. Не обещайте конкретную минуту готовности: реальное время зависит от входа, очереди и доступных ресурсов.

Минимальный limiter в Node.js

Следующий пример запускается в Node.js 20+ и показывает локальный limiter для одного процесса. Он годится для теста или одного воркера; в нескольких репликах счётчик нужно перенести в общее хранилище с атомарным резервированием и TTL. Обработчик не знает настоящий ключ и не отправляет его в лог. Функция work должна обращаться к API только с серверным RUSSIAAPI_API_KEY и с выбранным по текущему каталогу маршрутом.

export function createLimiter(maxActive) {
  let active = 0;
  const waiting = [];

  async function run(work) {
    if (active >= maxActive) await new Promise(resolve => waiting.push(resolve));
    active += 1;
    try {
      return await work();
    } finally {
      active -= 1;
      waiting.shift()?.();
    }
  }

  return { run, snapshot: () => ({ active, waiting: waiting.length, maxActive }) };
}

const limiter = createLimiter(3);
const result = await limiter.run(async () => ({ ok: true }));
console.log(result, limiter.snapshot());

В production добавьте deadline на всю операцию, а не только на сетевой вызов. Проверьте, что отменённая или упавшая задача всегда проходит через finally, иначе слот утечёт и сервис остановится при нулевой видимой нагрузке. Также ограничьте длину списка ожидания: неограниченный массив превращает временную перегрузку в отказ по памяти. Для событий с побочным эффектом сохраняйте ключ идемпотентности до запуска work.

429 — сигнал снизить давление

Ответ 429 не означает, что можно немедленно повторить тот же запрос из каждого воркера. Это обычно усиливает очередь и создаёт синхронный шторм. Соблюдайте указание Retry-After, если endpoint его передаёт; иначе используйте ограниченное число повторов с экспоненциальной паузой и случайным jitter. Повтор разрешён лишь для подходящего класса ошибки и в границах общего deadline. Ошибки 400, 401 и 403 требуют исправления входа, endpoint или прав, а не скрытых повторов.

Свяжите limiter с circuit breaker: если временная ошибка повторяется по одному маршруту, новые задачи можно оставить в очереди или отклонить быстро по ясной политике. Но breaker не заменяет диагностику и не должен бесконечно переключать модель без теста. Практические границы retry описаны в статье об ошибке 429, а защита от каскадных сбоев — в материале про circuit breaker.

Измеряйте задержку по классам задач

Один средний показатель почти бесполезен. Считайте отдельно время ожидания в очереди, время активного вызова, полный путь до результата, число отмен, число просроченных задач, p50 и p95. Дополните их долей 429, 5xx и валидных завершений. Если увеличение concurrency снижает очередь, но повышает p95 и долю ошибок, это не победа: узкое место просто переместилось в внешний маршрут или вашу базу данных.

В метриках достаточно внутреннего request ID, проекта, класса задачи, выбранного маршрута, длительности и безопасного кода результата. Не записывайте prompt, ответ, URL с подписью или секреты. Стоимость нужно оценивать по успешно завершённому сценариям и текущим данным, а не по захардкоженной цене. Подход к бюджетам и алертам объяснён в руководстве по мониторингу стоимости AI API.

Проведите контролируемый rollout

1. Выберите один маршрут и один класс задач; зафиксируйте начальный лимит и общий deadline.
2. Проверьте заполнение очереди, отмену, 429, timeout и падение воркера на синтетическом наборе.
3. Убедитесь, что повтор не создаёт вторую операцию и слот освобождается при любой ветке.
4. Снимите p95, длину очереди, долю ошибок и стоимость успешного результата.
5. Меняйте одно значение за раз, оставляйте rollback и документируйте причину изменения.

Конкурентность — часть договора о качестве сервиса, а не магическая настройка производительности. Хороший лимит делает перегрузку наблюдаемой, ограниченной и обратимой. Он помогает команде объяснить пользователю статус, сохранить бюджет и не превратить одну ошибку конфигурации в большую очередь повторов.

FAQ

Читайте также

• Ошибка 429 и backoff
• Circuit breaker для AI API
• Тайм-ауты AI API
• Документы RussiaAPI