GPT-Load 2.0: 複数プロバイダの資格情報を1つのURLに束ねるGo製セルフホストゲートウェイ

「1つのbase URL」に何を寄せるのか

GPT-Loadが解こうとしているのは、プロバイダごとに散らばった資格情報の管理である。READMEのWhyセクションには「Your application only needs one base URL and one AccessKey」と書かれている。アプリケーション側はbase URLとAccessKeyだけを持ち、プロバイダ、アカウント、資格情報、モデル、ルーティングポリシーはすべて管理UI側で設定する、という分担になる。

対象読者は、複数のAPIキーやサブスクリプションアカウントを並行して使っている運用者だ。たとえばOpenAI互換のAPIキーを複数用意している場合と、CodexやClaudeのようなサブスクリプションアカウントをOAuthで接続している場合で、資格情報の形式は違う。READMEはこの両者を「One mechanism for API keys and subscriptions」として同じ資格情報管理・スケジューリング・ヘルス処理に載せると説明している。プロバイダごとに別のラッパーを書くのではなく、ゲートウェイの1つの抽象に寄せるという設計だ。

クライアント側のプロトコルを変換しない点も明示されている。「clients keep their OpenAI, Anthropic, or Gemini native interfaces」とあり、OpenAI Chat Completions、OpenAI Responses、OpenAI Images、OpenAI Embeddings、Rerankなどのエントリがそのまま公開される。SDKを差し替えるのではなく、向き先のURLだけを変える移行を想定している。

スケジューリングと障害隔離の実装粒度

READMEが挙げる機能は、多資格情報スケジューリング、設定可能な重み、リトライ、クールダウン、ブラックリスト、セッションアフィニティの6つである。これらは「reduce the impact of overloaded or failing credentials」のために入っていると説明されている。つまり目的は負荷分散そのものではなく、壊れた資格情報がリクエスト全体を巻き添えにしないことにある。

ここで注目したいのは、重みとセッションアフィニティが同じ層に並んでいる点だ。重みは資格情報間の振り分け比率を操作する。セッションアフィニティは逆方向で、同一セッションを同じ資格情報に留める。両方を同時に効かせたい場合、どの粒度でセッションが判定されるのかはREADMEからは読み取れない。管理UIのグループ設定に委ねられている部分であり、導入前に自分のユースケースで挙動を確かめる価値がある。

クールダウンとブラックリストの閾値も同様に、READMEには具体的な数値や既定値の記載がない。設定可能であることは分かるが、既定でどれくらいの失敗でクールダウンに入るのかは素材からは確認できない。ここはドキュメントが薄い領域だと正直に言っておく。

障害隔離の単位はグループとチャネルになる。グループはチャネルを選び、利用可能なモデルとランタイムポリシーを設定する。AccessKeyは利用可能なグループとクライアントプロトコルを指定する。この3層の関係を理解しないと、意図した隔離にならない。

起動からコンソール到達までの実際の手順

必要なのはDockerとDocker Composeのみ。READMEのQuick startは次の順で進む。

git clone --depth 1 https://github.com/tbphp/gpt-load.git cd gpt-load cp .env.example .env docker compose up -d

起動確認はヘルスエンドポイントを叩く。

curl --fail http://127.0.0.1:3001/health

初回起動時に管理キーが生成される。これを読み出して保管する。

docker compose exec gpt-load sh -c 'cat /app/data/auth.key'

http://127.0.0.1:3001 を開き、そのキーでコンソールにサインインする。`AUTH_KEY`を`.env`に明示しておけば、起動前に自分で決めることもできる。既定ではループバックアドレスでのみ待ち受け、インターネットには公開されない。

初期設定は3ステップだ。1つ目はチャネルの追加で、上流サービスを選びAPIキーを1つ以上登録する。サブスクリプションチャネルならOAuthフローを完了するか、資格情報をインポートする。2つ目はグループの作成で、チャネルを選び、利用可能なモデルとランタイムポリシーを設定する。3つ目はAccessKeyの作成で、使用可能なグループとクライアントプロトコルを指定し、生成されたキーをアプリケーションに渡す。

`HOST`の既定値は`127.0.0.1`である。SSH経由やリモートブラウザから作業する場合、ブラウザの`localhost`がGPT-Loadに届かないことがある。その場合はコールバックURL全体を認可ダイアログに貼り付けてフローを完了させる、とREADMEは案内している。

1.xからの移行ができないという制約

最大の注意点はバージョン間の断絶である。READMEの警告は明確で、2.0は1.xのデータをその場で開くことも、インポートすることも、移行することもできない。1.xを使っているならMoving from 1.xを先に読め、という指示になっている。

これは単なる破壊的変更ではなく、データの持ち越しが不可能という意味だ。既存の1.x環境で蓄積した設定やログを2.0に引き継ぐ道が用意されていない以上、移行は再構築になる。運用中のゲートウェイを入れ替えるなら、クライアントに配布済みのAccessKeyやbase URLの再設定まで含めた作業計画が要る。

リリース状況も見ておくべきだ。直近のリリースはv2.0.0-rc.11、v2.0.0-rc.10、v2.0.0-rc.9と、いずれもrc表記である。2.0系はまだ候補版の段階にあり、READMEも1.xからの移行に関する警告を冒頭に置いている。安定版としての運用実績を前提にした判断はできない。

もう1つの制約はOAuthのコールバックポートだ。Codex、Claude、AntigravityのOAuthクライアントは固定のコールバックポートを使う。Composeはそれを`HOST`で指定されたアドレスに公開し、既定は`127.0.0.1`である。`HOST=0.0.0.0`にするとすべてのホストインターフェースにも公開される。ポートが上流クライアント側で固定されているため、既定のComposeインスタンスは1ホストに1つしか同時に動かせない。

LiteLLM Proxyとの設計の違い

比較対象として素直なのはLiteLLM Proxyだ。ただし両者は同じ方向から問題に接近していない。

LiteLLM Proxyはプロバイダ間のAPI差異を吸収し、OpenAI互換の形式に正規化することを主目的に据える。クライアントは1つの形式だけを話せばよく、その代わりにプロバイダ固有の機能は正規化の過程で落ちるか、拡張フィールドとして扱うことになる。

GPT-Loadは逆で、クライアントのネイティブインターフェースを維持する。READMEは「clients keep their OpenAI, Anthropic, or Gemini native interfaces」と書いており、OpenAI ResponsesのリソースパスやOpenAI Images、Embeddings、Rerankといったエンドポイントがそのまま公開される。プロバイダ固有のリクエスト形状を変換せずに通す設計だ。

この違いは、資格情報の扱いにも現れる。GPT-LoadはAPIキーとサブスクリプションアカウントを同じ機構に載せる。CodexやClaudeのOAuth接続を、APIキーと同じスケジューリング、ヘルス処理、クールダウンの対象として扱う。LiteLLM Proxy側でサブスクリプションアカウントを同じ粒度で扱えるかは、本記事の素材からは判断できない。少なくともGPT-Loadはそこを明示的な設計目標にしている。

どちらが優れているという話ではない。プロトコル変換を中央で一元管理したいならLiteLLM Proxy寄り、クライアントのネイティブ形式を保ったまま資格情報の運用だけを寄せたいならGPT-Load寄り、という住み分けになる。

データ保存先とライセンスの確認点

保存先はSQLite、MySQL、PostgreSQLから選べる。READMEは「backed by SQLite, MySQL, or PostgreSQL with local credential encryption」と述べており、資格情報はローカルで暗号化される。小規模ならSQLiteで完結するが、複数インスタンスで運用する場合はMySQLかPostgreSQLを選ぶことになる。どの構成でどの程度の同時接続に耐えるかの数値は素材にない。

ライセンスはMITである。リポジトリのLICENSEファイルとREADMEのバッジが示している。MITは商用利用を含めて制限が緩い部類だが、本記事は法的助言ではない。サブスクリプションアカウントをOAuthで接続してゲートウェイ経由で使う構成は、上流サービスの利用規約と別の論点を持つ。技術的な導入可否と規約上の可否は分けて確認する必要がある。

アップグレードのコストは2.0系では小さくない。1.xからのデータ移行ができない以上、メジャー更新のたびに再構築が発生しうる。rc版が短期間に連続して出ている状況を踏まえると、追従にはそれなりの手間を見込んでおくべきだ。

観測面は組み込みUIで完結する。ヘルス、ルート、ログ、使用量、コスト推定を確認できる。AccessKeyでサインインすると読み取り専用のホームに入り、そのキー自身のグループ、モデル、リクエスト、使用量、コスト許容量だけが見える。キーを配布する相手に何を見せるかを制御できる点は、運用上は地味に効く。

どの規模なら運用に乗るか

向いているのは、複数の資格情報を日常的に切り替えている運用者だ。APIキーを複数持っていて、どれかがレート制限や障害に当たったときに手動で差し替えているような状況なら、クールダウンとブラックリストをゲートウェイに任せる意味は大きい。クライアント側のコードをプロバイダごとに書き分けずに済む点も、SDKを複数抱える構成より見通しがよい。

向かないのは、単一プロバイダの単一キーで足りている場合だ。資格情報が1つしかないなら、スケジューリングも重みもセッションアフィニティも働く余地がない。ゲートウェイを1段挟むぶん、障害点と設定対象が増えるだけになる。

1.xを運用中のチームも現時点では慎重になるべきだ。データの引き継ぎができない以上、2.0への移行は新規構築として計画する必要がある。rc版である期間は、設定の再作成が何度か発生する前提で動かすことになる。

検証の順序は決まっている。`cp .env.example .env`で設定を用意し、`docker compose up -d`で起動し、`curl --fail http://127.0.0.1:3001/health`で応答を確認する。管理キーは`docker compose exec gpt-load sh -c 'cat /app/data/auth.key'`で読む。ここまで通ったら、実際に使う予定のサブスクリプションチャネルでOAuthフローを1回通し、固定ポートの制約が自分のホスト構成で問題にならないかを確かめる。この確認を飛ばすと、本番構成を組んだ後に1ホスト1インスタンスの制約に気づくことになる。

編集部の結論

採用すべきなのは、複数のAPIキーやサブスクリプションアカウントを自前で持ち、クライアント側のコードをプロバイダごとに書き分けたくない運用者だ。逆に、単一プロバイダの単一キーで足りている場合や、1.xのデータをそのまま引き継ぎたい場合は向かない。導入前に確認すべきは3点ある。1つ目は2.0が1.xのデータを開くこともインポートも移行もできないという点で、これはREADMEの警告に明記されている。2つ目はCodex/Claude/AntigravityのOAuthクライアントが固定ポートを使うため、既定のComposeインスタンスは1ホストに1つしか同時に動かせないという制約。3つ目は保存先の選択で、SQLite/MySQL/PostgreSQLのいずれを使うかによって運用負荷が変わる。まずは`cp .env.example .env`と`docker compose up -d`、そして`curl --fail http://127.0.0.1:3001/health`で起動確認し、`docker compose exec gpt-load sh -c 'cat /app/data/auth.key'`で管理キーを取得してコンソールに入るところまでを検証するのが現実的な第一歩になる。

公式情報源

1. License: MIT
2. Project website
3. README
4. Releases
5. tbphp/gpt-load on GitHub