ソリューションアーキテクチャ
Yabanin は、自社運用の AI ゲートウェイです。互換性のあるアプリケーションとエージェントは、モデルリクエストをゲートウェイへ送ります。ゲートウェイは、設定された制御を適用し、上流を選択し、リクエストを転送し、運用上の証拠を記録します。コードの編集、テストの実行、変更の受け入れは、引き続き顧客の開発ツールの責務です。
この文書は、2026年9月24日に検査した実装を説明します。図は論理的な見取り図であり、すべての機能がすべての導入で有効であるという主張ではありません。任意のコンポーネントには、設定とその依存関係が必要です。以下のソースパスは、リポジトリルートからの相対パスです。Mermaid ブロックは編集可能な図のソースであり、Mermaid に対応した Markdown ビューアで描画されます。
1. システムコンテキストと所有権
flowchart LR
Developer["Developer / application"] --> Agent["Compatible agent or SDK"]
Operator["Platform operator"] --> UI["Dashboard / operator CLI"]
subgraph Customer["Customer-operated environment"]
Gateway["Yabanin gateway"]
Admin["Admin API"]
Stores[("PostgreSQL and Redis")]
Local["Optional local inference"]
Tools["Optional internal tool servers"]
Gateway --> Local
Gateway --> Stores
Admin --> Stores
Gateway -. "Configured MCP invocation" .-> Tools
end
Agent -->|"Model requests"| Gateway
UI --> Admin
Gateway -->|"Approved external route"| Cloud["External model provider"]
Gateway -. "Configured MCP invocation" .-> ExternalTools["External tool server"]
Agent --> Checks["Customer sandbox, tests and code review"]
ゲートウェイは、設定されたエンドポイントを通して送られるトラフィックの仲介です。エージェントランタイムでも、オペレーティングシステムのサンドボックスでも、コードレビューの代替でもありません。エージェントの直接のネットワーク呼び出しは、導入側が別に制限しない限り、この境界を迂回します。自社運用のゲートウェイとローカル推論は別です。外部モデルの経路は、リクエストデータを顧客環境の外へ送ります。
2. ランタイムコンポーネント
flowchart TB
Client["Agent / SDK"] --> GW["Gateway :8082"]
Dashboard["React dashboard / yb CLI"] --> Admin["Admin API :8086"]
Bridge["Optional MCP partner bridge"] --> GW
Bridge --> Admin
subgraph Data["Request processing"]
GW --> Resolve["Model resolver and routing"]
Resolve --> Adapter["Provider adapter / upstream client"]
GW --> Cache["Optional cache service"]
Resolve -. "Optional complexity classification" .-> Classifier["Classifier"]
Cache -. "Semantic lookup" .-> Embedder["Embedding endpoint"]
end
Adapter --> Inference["Local or external inference"]
Cache --> Redis[("Redis: exact cache and auth state")]
Cache --> PG[("PostgreSQL: configuration, logs, lineage, pgvector")]
Resolve --> PG
GW -->|"Async request events"| Stream[("Redis Stream: events:queue")]
Stream --> Logger["Loggerd :8085"]
Logger -->|"Request logs and accounting"| PG
GW -. "Optional async lineage writer" .-> PG
Admin --> PG
Admin --> Redis
Redis のキャッシュと Redis Stream は、責務ごとに分けて示しています。同じ Redis の導入を使うことができます。ゲートウェイは、アイデンティティ、予算、方針のデータも読みます。図では、すべてのクエリを描かず、それらの読み取りを設定とまとめています。
| コンポーネント | 責務 | 実装の入口 |
|---|---|---|
| ゲートウェイ | HTTP ミドルウェア、認証、チャット API、経路、ストリーミング、任意の MCP 呼び出し API | services/gateway/cmd/main.go、pkg/gateway/gateway.go |
| リクエストパイプライン | 検証、キャッシュ分岐、モデル選択、上流の実行、イベント | pkg/gateway/chat.go、pkg/gateway/stream.go |
| Admin | 設定とアイデンティティの管理、利用分析、リネージ検証、ダッシュボードのバックエンド | services/admin/handlers/router.go、pkg/adminstore |
| Loggerd | Redis のコンシューマグループ、リクエストログの永続化、利用量の計上、保留メッセージの回復、デッドレター処理 | services/run/loggerd.go、services/loggerd/consumer/stream.go |
| MCP パートナーブリッジ | Yabanin のツールを MCP クライアントへ公開し、ゲートウェイ/admin の API を呼び出す | services/run/mcp.go、pkg/mcppartner |
| PostgreSQL | 永続的な設定と運用記録。任意のセマンティックキャッシュのベクトル | migrations、pkg/migrate/migrations |
| Redis | キャッシュ、アイデンティティ解決のキャッシュ、イベントストリーム、その他の設定されたランタイム状態 | pkg/cache、pkg/auth、pkg/eventpublisher |
| 分類器 / 埋め込み器 | 任意の経路分類と、セマンティックキャッシュの埋め込み | pkg/classifier、pkg/embeddings、deploy/docker-compose.yml |
ゲートウェイの独立した運用リスナー(既定は :9090)は、Admin のコントロールプレーンサービスではありません。開発用の Compose スタックでは、Admin コンテナのポート :8086 は、ホストポート :9091 として公開されます。MCP ブリッジは stdio と、:8787 上の任意の HTTP-SSE リスナーをサポートします。通常のチャット呼び出しには必要ありません。
3. チャットリクエストの経路
主要な API は POST /v1/chat/completions で、応答は JSON と SSE です。以下の順序は chatCompletions に従います。無効、または未接続の機能はスキップされます。拒否の分岐は、図に示した次の段階より前にリクエストを終了します。
flowchart TD
In["POST /v1/chat/completions"] --> HTTP["Body limit, timeout, rate limit, request ID"]
HTTP --> Auth["Authentication and resolved identity"]
Auth --> Admission["Optional credit guard and regional failover middleware"]
Admission --> Parse["Parse JSON and run configured input guards"]
Parse --> Access["Resolve requested model; check model access and budgets"]
Access --> Validate["Validate request; optional vertical transforms"]
Validate --> Cache{"Eligible cache hit?"}
Cache -->|"Yes"| Replay["Return cached JSON or replay as SSE"]
Cache -->|"No / bypass / lookup error"| Tier["Optional classifier and tier selection"]
Tier --> Rules["Organization routing-rule overrides"]
Rules --> Time["Optional time-window or batch downgrade"]
Time --> Residency["Configured residency enforcement / model remap"]
Residency --> Execute["Provider adapter, circuit breaker, retry and fallback"]
Execute --> Result["Return JSON or stream SSE"]
Result -. "Eligible successful response" .-> Write["Cache write"]
Replay -.-> Evidence["Request event and optional signed lineage"]
Result -.-> Evidence
アイデンティティと受付
認証は、解決されたプリンシパルから値を入れる前に、クライアントが供給した組織、キー、チーム、エージェントのアイデンティティヘッダーを取り除きます。静的キーとデータベースリゾルバの動作は、設定された認証モードに依存します。静的キーは、組織/エージェントのアイデンティティの代わりにはなりません。pkg/gateway/auth.go を参照してください。
接続されている場合、モデルアクセスと予算の確認はリクエストを拒否できます。これらの確認におけるデータストアのエラーは、支出を許可しません。チーム/エージェントの予算確認と、その後の利用量計上は別の操作です。したがってこの図は、同時に行われる各リクエストの最終コストを、アトミックに予約することを意味しません。
キャッシュと経路の順序
現在のハンドラでは、キャッシュ検索が、分類器/ルールによる経路と、その後のレジデンシー強制のブロックより先に行われます。ヒットすると、早期に返します。図を、キャッシュ後のすべての方針がキャッシュ済み応答に対して再評価される証拠として解釈しないでください。キャッシュの範囲、無効化、方針の変更は、まとめて評価する必要があります。
Cache-Control: no-store は、そのリクエストについてゲートウェイのキャッシュを迂回します。対象となる検索は、Redis の完全一致、任意で PostgreSQL の完全一致を試し、組織の方針で有効な場合はその後にセマンティック一致を試します。セマンティック一致は、埋め込みエンドポイントと pgvector を使います。再利用された回答が、あらゆるタスクに適するという証明ではありません。詳細は キャッシュアーキテクチャ を参照してください。
ミスの場合、分類がティアを選ぶことがあり、組織のルールがその選択を上書きすることがあり、設定された時間ベースの経路が、レジデンシー強制の前にそれをさらに変えることがあります。これらは別個の決定です。経路ルールの読み取り失敗は、現在はエラーを記録し、それらのルールなしで続行します。普遍的な失敗時クローズの方針レイヤではありません。最終的に応答するモデルは、フォールバックの後でも異なり 得ます。
ストリーミングとリトライ
sequenceDiagram
participant C as Client
participant G as Gateway
participant A as Selected upstream
participant B as Configured fallback
C->>G: Chat request with stream=true
G->>G: Admission, cache miss, routing
G->>A: Open stream through provider adapter
alt Connection setup fails
G->>A: Retry when policy permits
opt Selected upstream remains unavailable
G->>B: Try configured fallback
B-->>G: Accepted stream
end
else Selected upstream accepts
A-->>G: Accepted stream
end
Note over G,B: Successful setup commits to one upstream stream
G-->>C: Translated SSE chunks from winning upstream
Note over C,G: A mid-stream failure cannot be transparently replayed
G->>G: Record outcome and observed usage
このシーケンスは、いずれかの経路によるセットアップの成功を描きます。すべてのセットアップ試行が失敗すると、ゲートウェイはエラーを返します。ストリーミングのリトライ/フォールバックは、接続のセットアップにのみ適用されます。上流の応答を受け付けた後は、そのストリームを排出し、黙って再起動することはありません。プロバイダ固有の raw-body ストリーミングは、プロバイダをまたぐフォールバックを無効にします。pkg/gateway/stream.go と プロバイダ連携 を参照してください。
4. イベント、ストレージ、証拠
flowchart LR
GW["Gateway request outcome"] --> Pub["Bounded async event publisher"]
Pub --> Stream[("Redis Stream")]
Stream --> Consumer["Loggerd consumer group"]
Consumer --> DB[("PostgreSQL request_logs and accounting")]
Consumer -->|"Successful processing"| Ack["Acknowledge stream entry"]
Consumer -->|"Processing failure"| Pending["Pending entry / reclaim"]
Pending --> Consumer
Pending -->|"Poison-message handling"| DLQ[("Dead-letter stream")]
GW -. "When lineage enabled" .-> Sign["Sign attestation with organization key"]
Sign --> Writer["Async lineage writer"]
Writer --> Ledger[("PostgreSQL request_lineage")]
UI["Dashboard / operator"] --> Admin["Admin analytics and verification API"]
Admin --> DB
Admin --> Ledger
リクエストのログ記録とリネージは、永続化の経路が異なります。Loggerd はリクエストイベントを消費します。ゲートウェイのリネージライターは、アテストを別に追記します。クライアントへの応答は、loggerd がそのイベントを永続化するのを待ちません。利用分析は、リクエストの完了より遅れることがあります。
イベントの発行は有界で、ベストエフォートです。ゲートウェイは発行をリトライしますが、バックログが満杯のとき、または試行を使い切ったときに、イベントを破棄できます。リネージの作成もベストエフォートであり、失敗してもリクエストをブロックしません。コンシューマの回収、重複排除、デッドレター処理は、パイプライン全体を、厳密に 1 回で損失のないトランザクションにはしません。
| 記録 | 意味 | 解釈の境界 |
|---|---|---|
model_requested、model_used、経路の決定 | 要求されたラベル、記録された提供モデル、選択の文脈 | 要求されたモデル名だけでは、実行されたワークロードの価格付けや比較には不十分です |
| トークン、所要時間、先頭バイトのタイミング、試行 | 実行された経路で得られる観測 | 欠落したフィールドや中断されたストリームは、作業がゼロであることや、回答が完全であることの証拠ではありません |
| 見積もりコストと反事実コスト | 使用量ベースの価格見積もりと、モデル化された代替 | いずれも、プロバイダの請求書ではなく、実現が保証された節約でもありません |
| リネージの署名とリージョンの証拠 | アテストの完全性と、記載された証拠の出所 | 有効な署名は、物理的な推論の場所を単独では証明しません |
| タスク / セッション / エージェントの識別子 | 帰属と相関 | タスクタグは、その出力がテストまたはレビューに合格したことを示しません |
プロンプト、応答サンプル、キャッシュエントリ、埋め込み、イベントストリーム、バックアップは、別々のデータ面です。記録された 1 つのプロンプトをハッシュ化したからといって、それらのすべてから内容が除去されると推論しないでください。実際の導入について、取得、マスキング、保持、エンドポイントの設定を確認してください。リネージ、エージェントガバナンス、シャドウモード を参照してください。
シャドウモードは任意であり、候補モデルに対するサンプル比較を実行し、主たる回答を置き換えません。追加の推論呼び出しを行い、追加のコストが発生することがあります。候補の経路は、データの外向き境界の一部です。
5. 2 つの MCP 連携経路
flowchart LR
subgraph BridgePath["A. Clients invoke Yabanin tools"]
Client["MCP client"] -->|"stdio / HTTP-SSE"| Bridge["Partner bridge"]
Bridge -->|"Route prompt"| Chat["Gateway chat API"]
Bridge -->|"Spend, policy, lineage operations"| Admin["Admin API"]
end
subgraph InvokePath["B. Agents invoke registered external tools"]
Agent["Agent principal"] -->|"POST /api/mcp/invoke"| Invoke["Gateway invoke endpoint"]
Invoke --> Grants["Organization registry and agent grants"]
Grants --> Guards["Tool allow-list, input guards and SSRF checks"]
Guards --> Remote["Registered external MCP server"]
Guards -. "Audit event" .-> Events["Redis Stream / loggerd"]
end
ブリッジは、別の連携プロセスです。呼び出しエンドポイントはゲートウェイの一部であり、MCP プロキシが設定されている場合にのみマウントされます(YABANIN_MCP_GATEWAY=1 と、データベースをバックエンドとするセットアップ)。エージェントのプリンシパルと、有効化されたサーバー付与が必要です。通常の API キーでは不十分です。
外部の呼び出し経路は、サポートされた HTTP のツール呼び出し経路であり、MCP トランスポートの普遍的な互換性を主張するものではありません。上流の stdio サーバーは起動しません。転送されるエージェントのアイデンティティヘッダーは帰属を示すものであり、上流の資格情報ではありません。入力ガードは、出力のマスキングを確立しません。詳細は MCP ゲートウェイ を参照してください。
6. 導入と運用
flowchart TB
Users["Applications and operators"] --> Edge["Deployment-managed ingress / TLS"]
subgraph Boundary["Customer host, VPC or Kubernetes environment"]
Edge --> GW["Gateway replicas"]
Edge --> Admin["Admin API / dashboard"]
GW --> Redis[("Redis")]
Redis --> Logger["Loggerd workers"]
GW --> PG[("PostgreSQL / pgvector")]
Admin --> PG
Logger --> PG
Migration["Migration job"] --> PG
GW -. "Optional" .-> Local["Local model endpoints"]
GW -. "Optional" .-> Support["Classifier / embedder"]
GW -. "Metrics and traces" .-> Observe["Configured monitoring"]
end
GW -->|"Explicitly permitted egress"| Cloud["Approved cloud inference"]
これは導入のパターンであり、定められたレプリカ数や、可用性の保証ではありません。イングレス、シークレット、バックアップ、リソース制限、ネットワーク方針は、インストール側のものです。運用リスナーは、クライアント API とは別に保護してください。
| 導入 | リポジトリの資産 | 運用上の意味 |
|---|---|---|
| ローカル開発 | deploy/docker-compose.yml | データベース、Redis、マイグレーションジョブ、サービス、任意の推論/監視プロファイル。開発時の公開は、本番のセキュリティ設定ではありません |
| Kubernetes | deploy/helm/yabanin | 設定可能なサ ービス導入。任意のリージョン構成には、追加の設定が必要です |
| オンプレミス | deploy/helm/yabanin-onprem | ローカルインフラの選択肢を持つ自社運用コンポーネント。エアギャップへの準備には、すべての依存関係と外向き経路の確認が必要です |
| マルチリージョン | pkg/regionrouter、pkg/regionrepl、tests/integration/multiregion | 任意の組織リージョンの処理とレプリケーション。リクエストの中でモデルプロバイダをリトライすることとは別です |
リージョン対応のゲートウェイミドルウェアは、リクエストを HTTP 307 でピアへリダイレクトするか、リージョンが利用できないときにピン留めされた組織を拒否できます。クライアントは、選択された動作を処理しなければなりません。これは、見えないリージョン横断プロキシではありません。マルチリージョン運用、導入オプション、エアギャップチェックリスト を参照してください。
7. ソースマップとレビュー境界
| 質問 | 確認するコード |
|---|---|
| どの依存関係と任意機能が接続されていますか | pkg/gateway/gateway.go、pkg/config |