レート制限

概要

swag2mcp には組み込みのレートリミッターがあり、LLM が同じ API エンドポイントを頻繁に呼び出すのを防ぎます。これにより、偶発的な重複呼び出しから保護し、API のレート制限を尊重します。

仕組み

各エンドポイントにはクールダウン期間があります。LLM がクールダウン中に同じエンドポイントを再度呼び出そうとすると、構造化エラーで拒否されます。

t=0s  → invoke(endpoint) → 実行
t=2s  → invoke(endpoint) → rate_limit エラーで拒否
t=12s → invoke(endpoint) → 実行（クールダウン経過）

デフォルトの動作

• クールダウン: エンドポイントあたり 10 秒
• スコープ: エンドポイントごと — エンドポイント A の呼び出しはエンドポイント B に影響しません
• エラーレスポンス: LLM はコード rate_limit と待機時間を示すメッセージを含む LLMError を受け取ります
• リセット: そのエンドポイントで 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

• 型: 期間（Go 形式：10s、30s、1m）
• デフォルト: 10s
• 効果: 同じエンドポイントへの呼び出し間のクールダウン期間を設定します。
• 増やすタイミング: 厳格なレート制限がある API（例：1 分あたり 10 リクエスト）。
• 減らすタイミング: 負荷を制御できる内部 API。
• 例: 5s、30s、1m、2m

重要な注意点

• エンドポイントごとの追跡 — 各エンドポイントは独立して追跡されます。あるエンドポイントの呼び出しは他に影響しません。
• LLM にエラーが返される — クールダウン中の 2 回目の呼び出しは rate_limit エラーで拒否されます。LLM はクールダウン期間を受け取り、待機後に再試行できます。
• クリーンアップ不要 — レートリミッターはエンドポイントを自動的に追跡し、メンテナンスは不要です。