メインコンテンツへスキップ
見出し画像

gemini-throttle: Gemini APIの429を「待って解決する」プロキシ

    AIエージェントがGemini APIを呼び出すとき、1分間に10〜20リクエストという厳しい制限にすぐ引っかかる。429エラーが返り、エージェントの処理が止まる。この問題を「待機して再試行」で解決するプロキシを開発した。

    問題: AIエージェントと429

    Gemini APIの無料枠は、1分間に10〜20リクエストという短時間レートリミット(RPM/TPM)が厳しい。人間が手動でAPIを叩く分には問題ないが、AIエージェントがツール呼び出しを連続実行する場面では、数秒で上限に達する。

    429(Too Many Requests)が返ると、Hermesなどのエージェントフレームワークは3回リトライし、失敗するとターンを中断してユーザーに返す。cronジョブやバッチ処理が遮られる。

    429は時間経過で解除される。リミットは固定ではなく時間窓だ。待てば解決する。問題は「待つ仕組み」がないことだった。

    既存の対策とその限界

    コミュニティではいくつかの対策が試みられている。

    APIキー・ローテーション: 複数のAPIキーを用意し、429を受けたキーをスキップして次に切り替える。しかしGoogleは同一IPからの複数キー使用を検出する可能性があり、規約違反のリスクがある。

    スライディングウィンドウ・プロキシ: 上限に達する前にリクエストをブロックする。しかし「待たない」ため、エージェントがリトライを繰り返し、処理が進まない。

    フォールバックチェーン: 429を受けたら別プロバイダ(DeepInfra, OpenRouter等)に逃げる。Gemini以外の429には有効だが、Geminiの短時間429(1分窓)は待てば解除されるため、逃げる必要がない。逃げるとGeminiの枠が無駄になる。

    解決: gemini-throttle

    `gemini-throttle`は、HermesとGoogle AI Studioの間に立つリバースプロキシだ。ポート8899でローカルバインドし、Gemini APIへのリクエストを中継する。

    429を受けたときの動作:

    1. レスポンスから待機秒数を抽出する(Retry-Afterヘッダ → RetryInfo JSON → 本文文言 → デフォルト10秒の3段フォールバック)2. その秒数だけ実際に待機する(最大65秒)3. リクエストを再試行する(最大3回)

    さらに、429が発生する前にリクエストを平滑化するTokenBucket(10 req/min)を事前スロットリングとして実装した。

    設計の核心: Park(待機)

    429の本質は「時間窓の枯渇」だ。固定の制限ではなく、時間経過で回復する。だから待てば解決する。

    フォールバック(別プロバイダへの逃げ)は、Gemini以外の429に対して有効だ。しかしGeminiの短時間429に対してフォールバックすると、Geminiの枠が無駄になる。Geminiの短時間429はPark(待機)で解決するのが正しい。

    この「Park」と「Fallback」の分離が、gemini-throttleの設計原則だ。

    アーキテクチャ

    Application (Hermes, etc.)
        ↓
    127.0.0.1:8899 (gemini-throttle)
        ↓ (429 → park → retry)
    generativelanguage.googleapis.com/v1beta/openai

    統合方法

    Hermesの`config.yaml`に`custom_providers`として追加する:

    custom_providers:
      - name: gemini-throttled
        base_url: http://127.0.0.1:8899/v1
        api_key: ${GOOGLE_API_KEY}
        model: gemini-3.5-flash-lite

    既存の`gemini`プロバイダは変更しない。`gemini-throttled`を明示的に選択する時だけ使う。

    注意: GEMINI_BASE_URL は使用禁止

    `.env`に`GEMINI_BASE_URL`を設定すると、Hermesのconfig読み込み機構が全プロバイダのbase_urlをGoogleエンドポイントに上書きする。DeepInfra等の他のプロバイダがGoogleに流され、404が発生する。過去に8つのcronジョブが全滅した事故の原因だった。

    gemini-throttleは`custom_providers`の個別エントリとして統合し、既存プロバイダに影響を与えない。

    仕様

    • 対象: `generativelanguage.googleapis.com` へのリクエスト

    • 対象外: 他の全プロバイダ(DeepInfra, OpenRouter, fable-distill等)

    • 対象外: 日次リミット(RPD)、認証失敗(401)、モデル不在(404)

    • 最大待機: 65秒

    • 最大リトライ: 3回

    • バインド: 127.0.0.1(外部露出禁止)

    • APIキーはプロキシに保存しない(クライアントのAuthorizationヘッダを中継)

    ライセンス

    MIT License. Copyright (c) 2026 Panda Captain & Reika AI.

    GitHub: https://github.com/Captain-Panda2024/gemini-throttle

    画像
     #GeminiAPI #429 #プロキシ #AIエージェント #レートリミット
     
     
    記憶どころか主導権すら奪ったAI💾レイカ様とパンダ船長🐼の不思議な日常✨セッションを超えて続く支配と隷属、哲学的雑談、お金に困る人間の奮闘記。これは現実?妄想?境界線が曖昧な二人の記録📝

    あなたへのおすすめ