xtokenhub

# XTokenHub XTokenHubは、LLMプロバイダーAPIのためのセルフホスト型集約ゲートウェイです。複数のプロバイダーで保持しているAPIキーを単一のチャネルベースのパネルに集約し、クライアントに標準化されたプロトコルエンドポイントを公開し、トークン使用量とキャッシュヒット率をリアルタイムでレポートします。設計原則として、可能な限りプロバイダーのネイティブプロトコルでトラフィックを通過させ、変換はフォールバックとして扱うとしています。 ## コア機能 - **チャネルベースのキー管理** — プロバイダーエンドポイントごとに1つのエントリを作成し、可用性プローブ、有効/無効の切り替え、およびプロバイダーが提供している場合は残高照会が可能です。 - **モデルのグループ化とルーティング** — 各チャネルは独自のモデルリスト（オンデマンドでアップストリームから取得）を持ち、すべてのアップストリームは単一のモデル一覧エンドポイントに統合されます。ルーティングは優先度と重み付きランダム選択を使用し、同じモデルを提供するチャネル間で自動フェイルオーバーが行われます。 - **使用状況のインサイト** — ダッシュボードでリクエスト数、トークン使用量、キャッシュヒット率、平均レイテンシを、モデル別、チャネル別、またはコーラーキー別に集計してレポートします。GitHubスタイルのアクティビティヒートマップと日次トレンドチャートがWebSocket経由で配信されます。 - **プロトコル変換** — ゲートウェイは、OpenAIスタイルのchatおよびresponsesエンドポイントと、Anthropicスタイルのmessagesエンドポイントを同時に公開します。リクエストは、インバウンドとアップストリームのプロトコルが異なる場合にのみ変換されます。プロトコルが一致する場合は書き換えなしで転送され、これによりツール呼び出しやマルチモーダルペイロードが保持されます。 - **ゲートウェイキーとコーラー別統計** — 異なるコーラー向けにクライアント用キーを発行し、リクエスト数とトークン合計をキーごとに集計します。 - **単一バイナリによるセルフホスティング** — フロントエンドがGoバイナリに組み込まれているため、ビルドすると1つの静的アーティファクト（CGOなし）が生成され、LinuxまたはmacOSマシンにコピーして利用できます。 ## ルーティングと計測の仕組み READMEでは、以下の4ステップのフローが説明されています： 1. プロバイダーのベースURL、APIキー、モデルリストを使用してチャネルを作成します。APIスタイル（OpenAI互換はBearer、Anthropic互換はx-api-key）はベースURLから自動検出されますが、上書きも可能です。ベアドメイン、/v1サフィックス、/anthropicなどのサブパスマウント、バージョン付きマウントなど、複数のベースURLマウント形式をサポートしています。 2. ネイティブプロトコルのプローブが各プロトコルエンドポイントに最小限のリクエストを送信し、2xxレスポンスが返ってきたプロトコルがそのチャネルのネイティブとしてマークされます（手動での修正も可能です）。 3. 受信リクエストは、そのモデルを提供する有効なチャネルにフィルタリングされます。ネイティブチャネルが優先され、変換チャネルはフォールバックとしてのみ使用されます。選択は優先度昇順の重み付きランダムで行われ、ネットワークエラー、401/403/408/429、または5xxなどの失敗が発生するとフェイルオーバーがトリガーされます。 4. 使用量は、アップストリームのレスポンスで報告されている場合に解析されます（ストリーミング使用量オプションが自動的に追加されます）。アップストリームから報告がない場合は、ローカルのヒューリスティック推定が使用されます。キャッシュヒット率はプロバイダーのcached-tokenフィールドから取得され、すべてのリクエストはログテーブルに書き込まれ、UIにプッシュされます。 ## ダッシュボードとAPIサーフェス 管理APIは、チャネル、ゲートウェイキー、保持期間によるクリーンアップを伴うリクエストログ、および一連の統計エンドポイント（サマリー、日次トレンド、モデル別、チャネル別、キー別、生涯合計、モデル別トレンド）をカバーし、さらにヘルスチェックエンドポイントとライブイベント用のWebSocketエンドポイントを備えています。ゲートウェイエンドポイントには、統合モデルリストとchat、responses、messagesルートが含まれます。コーラー認証はBearerトークンまたはx-api-keyヘッダーを受け入れ、設定でオフにすることも可能です。 ## 設定と運用 設定の優先順位は、環境変数、YAMLファイル、組み込みデフォルトの順です。データはWALモードのSQLiteに保存され、単一のライター接続が使用されます。リクエストログはデフォルトで無制限に増加するため、保持ジョブが設定された日数より古い行を削除します。サイクル間隔、バッチサイズ、およびオプションのVACUUMの設定が可能です。プロジェクトの注意点として、削除後にSQLiteファイルが自動的に縮小されないことが挙げられています。 ## テスト ユニットテストはミラーリングされた外部テストパッケージレイアウトに配置され、設定の読み込み、インメモリSQLiteリポジトリ、イベントバス、WebSocketの動作、擬似アップストリームによるプロバイダープローブと変換、ゲートウェイ選択と統計の永続化、およびエンドツーエンドのハンドラー/ルーターパスをカバーしています。READMEによると、レース検出を有効にしたフルテストが実行され、ステートメントカバレッジは87.6%であり、WebSocketの再接続とデータ変換に関するフロントエンドテストも実施されています。 ## プロジェクトが提示する既知の制限事項 - 変換パスはテキストチャットのみを処理します。ツール呼び出し、マルチモーダル、およびキャッシュコントロールペイロードにはネイティブパススルーチャネルが必要です。 - 残高照会は現在DeepSeekのみをサポートしています。他のプロバイダーの残高APIはドキュメント化されていないか、期限切れのクッキー認証が必要であるか、または公開されていないためです。 - ローカルのトークン推定はヒューリスティックであり、フォールバックとしてのみ使用されます。 - 管理APIにはログイン認証がなく、外部ネットワークから隔離されたセルフホストのイントラネット利用を想定しています。キーはプレーンテキストで保存されます。 - キャッシュヒット率とキーごとの集計はリクエストログのスナップショットに依存しているため、削除されたキーの履歴使用量はその名前の下に残ります。 ## コンパニオンアプリとライセンス 別途提供されるSwiftUIメニューバーアプリは、バックエンドの変更なしに同じ管理APIとWebSocketを利用します。XTokenHubはMITライセンスの下でリリースされています。