メインコンテンツまでスキップ

キャッシュアーキテクチャ

概要​

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 のセマンティックキャッシュ、非同期書き込みパイプラインを管理します
RedisStoreRedis をバックエンドとするインメモリのキーバリューストア。キーは cache:{org_id}:{model_tier}:{hash} です
SemanticCacheコサイン類似度のしきい値(0.95)を持つ HNSW インデックスによる、pgvector 上の ANN 検索
Writerワーカー 4 つの非同期書き込みパイプライン。非ブロッキングの Submit() と、満杯時に破棄するキュー管理
Cleaner両方のバックエンドから期限切れエントリをパージする、定期的な TTL ジャニター(5 分間隔)
InvalidatorRedis SCAN と pgvector DELETE による、組織スコープ、モデルバージョンスコープ、プロンプトハッシュスコープの無効化
PolicyCacheTTL 60 秒の、組織ごとの方針キャッシュ。有効、無効、読み取り専用の各モードを制御します
Analytics組織ごとおよびティアごとの内訳を持つ、インメモリのヒット/ミス追跡
ABTestA/B 実験(対照と処置)のための、決定的なハッシュによるバケット分け
Warmer削除済み(W-CACHE)。署名のないエントリを書き込んだため、RT-05 の検索は常にそれらを拒否していました。/api/cache/warm は 410 を返します

キャッシュフロー​

読み取り経路(検索)​

  1. Cache-Control: no-store を確認します。存在する場合はスキップします
  2. 組織ごとの方針を確認します。無効または読み取り専用の場合はスキップします
  3. sha256(normalized_prompt) による Redis の完全一致検索。最も速い経路です
  4. prompt_hash と model_version による pgvector の完全一致検索。pgvector にだけ書き込まれたエントリ向けです。既定では無効です(再有効化するには YABANIN_CACHE_PG_EXACT_LOOKUP=true)。完全一致レイヤは Redis です。pg の完全一致検索が役立つのは Redis のデータ喪失の後だけであり、ミスのたびに Postgres への往復がかかります
  5. セマンティック ANN 検索。プロンプトを埋め込み、コサイン類似度が 0.95 以上なら、見つかった応答を返します
  6. すべてがミスの場合は、上流プロバイダへ転送します

書き込み経路(上流の応答が成功した後)​

  1. shouldCache() を確認します。エラー応答、空のボディ、no-store の組織はスキップします
  2. Redis の完全一致書き込み。同期であり、常に高速です
  3. 非同期の 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 次元)

コストとレイテンシのオーバーヘッド​

キャッシュは無料ではありません。内訳を示すので、自分のトラフィックで測った節約と比較できます。

レイヤホットパスのコスト注記
完全一致ヒット(Redis)SHA-256 + Redis GET 1 回モデル呼び出しはありません。同一配置の Redis では、往復は 1 ミリ秒未満です
セマンティック検索埋め込み 1 回(CPU で約 20 ms、bge-small)+ pgvector の ANN クエリ 1 回HNSW の ef_search=100。どちらの経路にも Prometheus のヒストグラム(cache_lookup_duration_seconds)があります
キャッシュ書き込みホットパスの外非同期のワーカー 4 つのプール。満杯時は破棄し、応答をブロックしません
ストレージエントリあたり約 1.6 KB のベクトル(384 × float32)+ 応答の JSONBTTL は 24 時間、ジャニターは 5 分ごとです

インフラの下限は、エンベッダーのサイドカー 1 つ(CPU のみの場合、分類器のスケーリングに関するメモ によれば約 100 RPS)と、ゲートウェイ用にすでに動かしている Postgres および Redis です。make bench-cache は、使用中のハードウェアで検索の数値を再現します。cache_hits_total{type} と cache_similarity_score は、自分のトラフィック上の実際の値を示します。組織のヒット率が低い場合、プライバシーモード(exact / off)がその組織のセマンティックレイヤをオフにします。完全一致レイヤは残ります。

計測値(make bench-cache)​

参照環境は、Apple M5 Max、localhost 上の Docker 内の Redis 7、2026-09-02 です。自分のハードウェアでは make bench-cache で再現してください。

ベンチマーク結果内容
ExactCache_Get_Hit~0.22 ms/op、11 allocs完全な完全一致ヒット。SHA-256 と Redis GET の往復です
ExactCache_Get_Miss~0.24 ms/op、14 allocs完全一致のミス経路です
SemanticNormalize_Normalized~1.7 µs/op埋め込み前の正規形 JSON への正規化です
CosineDistance(384 次元)~93 ns/op、0 allocs類似度の判定そのものです

ユニットベンチマークの対象外なのは、エンベッダーへの HTTP 呼び出し(分類器のメモによれば、bge-small で CPU 約 20 ms。実際の数値は make bench-cache-live を参照)と、稼働中の Postgres が必要な pgvector の ANN クエリです。ライブトラフィックでは、どちらも cache_lookup_duration_seconds{type=semantic} に現れます。

監視​

Prometheus メトリクス​

メトリクス型説明
cache_hits_total{type,org_id}カウンタソース別のキャッシュヒット(exact/semantic/miss)
cache_writes_total{status}カウンタ書き込み試行(written/dropped)
cache_lookup_duration_seconds{type}ヒストグラム検索レイテンシの p50/p90/p99
cache_similarity_scoreヒストグラムセマンティックヒット時のコサイン類似度
cache_size{backend}ゲージバックエンドごとのエントリ数
cache_write_queue_sizeゲージ保留中の書き込みジョブ
cache_janitor_runs_totalカウンタTTL ジャニターの実行回数
cache_ab_arm_total{variant}カウンタA/B 実験のアーム割り当て

Grafana ダッシュボード​

ヒット率、レイテンシのパーセンタイル、類似度の分布、キューの深さ、組織ごとの内訳、savings_usd、ジャニターの統計、エラー率を扱う 8 パネルのダッシュボードです。docs/observability/cache-dashboard.json からインポートします。

A/B 実験のフロー​

  1. 管理者は、対照(cache=off)と処置(cache=enabled)のバリアントを持つ実験を作成します
  2. ゲートウェイは、各組織を決定的に割り当てます。hash(org_id + experiment_id) % 100 < traffic_pct
  3. 対照アームは、すべてのキャッシュ検索をスキップし、常に上流へ転送します
  4. 処置アームは、完全なキャッシュ検索パイプラインを使います
  5. 結果は /api/cache/experiments/{id}/results 経由で集約され、バリアントごとの savings_usd を比較します

キャッシュウォーミング(削除済み)​

キャッシュのウォーミングは削除されました(W-CACHE)。ウォームされたエントリには RT-05 の HMAC 署名がなかったため、すべての検索がそれらを拒否していました。/api/cache/warm は現在 410 Gone を返します。セマンティックキャッシュは、ライブトラフィックからのみ学習します。