Ограничение частоты запросов

Обзор

swag2mcp имеет встроенный ограничитель частоты, который предотвращает слишком частые вызовы одного и того же эндпоинта API со стороны LLM. Это защищает от случайных дублирующих вызовов и соблюдает лимиты частоты API.

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

Каждый эндпоинт имеет период охлаждения. Если LLM пытается вызвать тот же эндпоинт снова в течение периода охлаждения, вызов отклоняется со структурированной ошибкой.

t=0s  → invoke(endpoint) → выполняется
t=2s  → invoke(endpoint) → отклонён с ошибкой rate_limit
t=12s → invoke(endpoint) → выполняется (период охлаждения прошёл)

Поведение по умолчанию

• Период охлаждения: 10 секунд на эндпоинт
• Область действия: На эндпоинт — вызов эндпоинта A не влияет на эндпоинт B
• Ответ об ошибке: LLM получает LLMError с кодом rate_limit и сообщением, указывающим, сколько ждать
• Сброс: После 10 секунд бездействия на этом эндпоинте

Формат ошибки

При превышении лимита частоты LLM получает:

{
  "code": "rate_limit",
  "message": "rate limit exceeded for endpoint \"abc123\": try again in 8 seconds",
  "hint": "Wait for the cooldown period to expire, then try invoking the endpoint again. Use the search tool to find other endpoints you can call in the meantime."
}

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

Зачем это нужно

• Предотвращает случайные дублирующие вызовы — LLM может вызывать один и тот же эндпоинт несколько раз подряд
• Защищает от лимитов частоты API — многие API имеют собственные лимиты, и их превышение вызовет ошибки
• Экономит ресурсы — уменьшает ненужный сетевой трафик

Конфигурация

Вы можете отключить ограничитель частоты или изменить интервал охлаждения:

# Полное отключение ограничителя частоты
disable_ratelimiter: true

# Пользовательский интервал охлаждения
rate_limit_interval: 30s

disable_ratelimiter

• Тип: bool
• По умолчанию: false
• Эффект: При true ограничитель частоты на эндпоинт отключается. LLM может вызывать один и тот же эндпоинт повторно без ожидания.
• Когда включать: Тестирование, отладка или когда нужно вызывать один и тот же эндпоинт несколько раз подряд.
• Когда оставлять отключённым (рекомендуется): Продакшен. Ограничитель частоты предотвращает случайное злоупотребление.

rate_limit_interval

• Тип: duration (Go-формат: 10s, 30s, 1m)
• По умолчанию: 10s
• Эффект: Устанавливает период охлаждения между вызовами одного и того же эндпоинта.
• Когда увеличивать: API со строгими лимитами частоты (например, 10 запросов в минуту).
• Когда уменьшать: Внутренние API, где вы контролируете нагрузку.
• Примеры: 5s, 30s, 1m, 2m

Важные замечания

• Отслеживание на эндпоинт — каждый эндпоинт отслеживается независимо. Вызов одного эндпоинта не влияет на другие.
• Ошибка возвращается LLM — второй вызов в течение периода охлаждения отклоняется с ошибкой rate_limit. LLM получает длительность охлаждения и может повторить попытку после ожидания.
• Очистка не требуется — ограничитель частоты отслеживает эндпоинты автоматически и не требует обслуживания.