キャッシュアーキテクチャ
概要
Yabanin のセマンティックキャッシュは、複数のレイヤで応答をキャッシュすることで、LLM のコストとレイテンシを下げます。組織ごとのプライバシー制御、A/B テスト、包括的な可観測性をサポートします。
graph TB
Client[Client / App] -->|POST /v1/chat/completions| GW[Gateway]
subgraph "Cache Decision"
GW --> CC["Cache-Control: no-store?"]
CC -->|yes| UPSTREAM[Upstream Provider]
CC -->|no| CK{"Check Cache"}
end
subgraph "Cache Layers"
CK --> Redis[(Redis Exact<br/>cache:{org}:{tier}:{hash})]
Redis -->|miss| PG[(pgvector)<br/>cache_entries table]
PG -->|miss| Embed["Embedder (bge-small-en)"]
Embed --> SemanticSearch[ANN Search<br/>cosine >= 0.95]
end
subgraph "Cache Write"
GW -->|"upstream success"| ASync[Async Writer Pool<br/>4 workers]
ASync --> RedisWrite[(Redis)]
ASync --> PGWrite[(pgvector + embedding)]
end
UPSTREAM --> GW
SemanticSearch -->|hit| GW
Redis -->|hit| GW
subgraph "Observability"
GW --> Prometheus[Prometheus Metrics]
GW --> Loggerd[loggerd → request_logs]
Prometheus --> Grafana[Grafana Dashboard]
Loggerd --> Analytics["/api/analytics/{org}/cache"]
end
subgraph "Admin API"
Admin[Admin Panel] --> CacheSettings["PATCH /api/organizations/{id}/cache-settings"]
Admin --> Flush["POST /api/cache/flush"]
Admin --> Warm["POST /api/cache/warm (410, removed)"]
Admin --> Experiments["POST /api/cache/experiments"]
end
style GW fill:#e1f5fe
style Redis fill:#fff3e0
style PG fill:#e8f5e9
style Embed fill:#fce4ec
コンポーネント
| コンポーネント | 説明 |
|---|---|
| CacheService | 最上位のオーケストレータ。Redis の完全一致キャッシュ、pgvector のセマンティックキャッシュ、非同期書き込みパイプラインを管理します |
| RedisStore | Redis をバックエンドとするインメモリのキーバリューストア。キーは cache:{org_id}:{model_tier}:{hash} です |
| SemanticCache | コサイン類似度のしきい値(0.95)を持 つ HNSW インデックスによる、pgvector 上の ANN 検索 |
| Writer | ワーカー 4 つの非同期書き込みパイプライン。非ブロッキングの Submit() と、満杯時に破棄するキュー管理 |
| Cleaner | 両方のバックエンドから期限切れエントリをパージする、定期的な TTL ジャニター(5 分間隔) |
| Invalidator | Redis SCAN と pgvector DELETE による、組織スコープ、モデルバージョンスコープ、プロンプトハッシュスコープの無効化 |
| PolicyCache | TTL 60 秒の、組織ごとの方針キャッシュ。有効、無効、読み取り専用の各モードを制御します |
| Analytics | 組織ごとおよびティアごとの内訳を持つ、インメモリのヒット/ミス追跡 |
| ABTest | A/B 実験(対照と処置)のための、決定的なハッシュによるバケット分け |
| Warmer | 削除済み(W-CACHE)。署名のないエントリを書き込んだため、RT-05 の検索は常にそれらを拒否していました。/api/cache/warm は 410 を返します |
キャッシュフロー
読み取り経路(検索)
- Cache-Control: no-store を確認します。存在する場合はスキップします
- 組織ごとの方針を確認します。無効または読み取り専用の場合はスキップします
sha256(normalized_prompt)による Redis の完全一致検索。最も速い経路です- prompt_hash と model_version による pgvector の完全一致検索。pgvector にだけ書き込まれたエントリ向けです。既定では無効です(再有効化するには
YABANIN_CACHE_PG_EXACT_LOOKUP=true)。完全一致レイヤは Redis です。pg の完全一致検索が役立つのは Redis のデータ喪失の後だけであり、ミスのたびに Postgres への往復がかかります - セマンティック ANN 検索。プロンプトを埋め込み、コサイン類似度が 0.95 以上なら、見つかった応答を返します
- すべてがミスの場合は、上流プロバイダへ転送します
書き込み経路(上流の応答が成功した後)
shouldCache()を確認します。エラー応答、空のボディ、no-store の組織はスキップします- Redis の完全一致書き込み。同期であり、常に高速です
- 非同期の pgvector 書き込み。ワーカー 4 つのプールが埋め込みを計算し、cache_entries へ upsert します
プライバシーモデル
| モード | 検索 | 書き込み | 説明 |
|---|---|---|---|
off | ❌ | ❌ | キャッシュをまったく行いません |
exact | ✅(Redis のみ) | ✅(Redis + pgvector) | 完全一致キーの照合だけを行います |
semantic | ✅(Redis + pgvector) | ✅(Redis + pgvector) | 完全なセマンティックキャッシュです |
切り替えは管理者だけが行え、監査ログに記録されます。変更は、影響を受ける組織のキャッシュを自動的に無効化します。
しきい値の調整
- コサイン類似度: 0.95(既定)。低くするとヒットは増え、偽陽性のリスクは高くなります。
- HNSW ef_search: 100(既定)。高くすると再現率は上がり、クエリは遅くなります。
- TTL: 24 時間(Redis)。方針により組織ごとに設定できます。
- 埋め込みモデル:
BAAI/bge-small-en-v1.5(384 次元)