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

セマンティックキャッシュ

セマンティックキャッシュシステムは、LLM 応答の多層キャッシュを提供します。完全一致の Redis キャッシュと、pgvector ベースのセマンティック検索を組み合わせます。

アーキテクチャ​

Request
│
├─→ [Redis Exact Cache] ─── hit → Return cached response
│ key: cache:{org_id}:{model_tier}:{sha256(prompt)}
│
├─→ [pgvector Exact Cache] ─── hit → Return + warm Redis
│ unique index on (org_id, model_tier, prompt_hash, model_version)
│ (disabled by default — see Read Path below)
│
├─→ [Embedding Service] → vector(384)
│ bge-small-en via text-embeddings-inference sidecar
│
├─→ [pgvector Semantic Search] ─── hit → Return + warm Redis
│ HNSW index with cosine similarity threshold (≥0.95)
│
└─→ [Upstream LLM API]
↓ async write to both Redis and pgvector

コンポーネント​

コンポーネントパッケージ説明
Redis 完全一致キャッシュpkg/cache/redis.goSHA-256 をキーとする Redis ストア。TTL は 24 時間
pgvector ストレージpkg/cache/store.goCRUD 操作、ベクトル I/O ヘルパー
セマンティック検索pkg/cache/semantic.goHNSW のコサイン距離による ANN 検索
書き込みパイプラインpkg/cache/writer.goキャッシュ書き込み用の非同期ワーカープール
SSE リプレイpkg/cache/replay.goRecordingWriter と 3 つのリプレイモード
キー正規化pkg/cache/normalize.go一貫したハッシュのための正規 JSON
埋め込みサービスpkg/embeddings/client.go埋め込み API 向けの HTTP クライアント
統合サービスpkg/cache/service.goプライバシー制御付きですべての層を調整します
プライバシー方針pkg/cache/service.go組織ごとの有効 / 無効 / 読み取り専用モード
TTL クリーナーpkg/cache/cleaner.go期限切れエントリの定期的なパージ
Prometheus メトリクスpkg/cache/metrics.goキャッシュ専用のメトリクスベクトル 8 種
利用分析 + A/Bpkg/cache/analytics.goヒット率の追跡、トラフィック分割、ウォーミング

多言語トラフィック(日本語など)​

bge-small-en-v1.5 は英語で学習されています。日本語(およびその他の非英語)トラフィックでは、セマンティックキャッシュの精度と分類器の正確さの両方が低下します。多言語の導入では、設定で embedder を多言語モデルに入れ替えます。コード変更は不要です。

YABANIN_EMBEDDER_MODEL=intfloat/multilingual-e5-small
YABANIN_EMBEDDER_QUERY_PREFIX="query: "

注意:

  • multilingual-e5-small は bge-small-en と同じ 384 次元を保つため、既存の pgvector スキーマ(vector(384))のマイグレーションは不要です(初回起動時に次元を確認してください。不一致はキャッシュを壊すのではなく、挿入を大きなエラーで失敗させます)。
  • e5 系モデルは入力プレフィックス付きで学習されています。設定した YABANIN_EMBEDDER_QUERY_PREFIX は、検索も書き込みも、埋め込むすべてのテキストの先頭に付きます。これによりコサイン比較が対称のままになります。プレフィックスを変えると、既存のセマンティックエントリは無効になります。切り替え後にキャッシュをフラッシュしてください(POST /api/cache/flush)。
  • タスク分類器は別のモデルで、独自の(英語の)学習データを持ちます。日本語トラフィックでは、経路によるティア分けはルールティア V0 にフォールバックします。日本語プロンプトでの分類器の再学習は、別途追跡しています。

多言語 embedder のサイドカーを含む compose プロファイルは、deploy/docker-compose.yml(embedder-multilingual)にあります。

プライバシー制御​

各組織にはキャッシュ方針があります。

  • enabled — キャッシュの読み書きをすべて行います
  • disabled — キャッシュをまったく行いません(プライバシー優先)
  • read-only — キャッシュ済み応答は検索できますが、新しいエントリは書き込みません

方針はメモリ内に TTL 60 秒でキャッシュされ、リクエストごとの DB 負荷を避けます。

SSE ストリーミング​

ストリーミング応答では、キャッシュが個々の SSE フレームをタイミング付きで取り込みます。

rw := cache.NewRecordingWriter(w)
// ... upstream response is written through rw ...
chunks := rw.Chunks() // []SSEChunk{Data, DelayMS}

リプレイモード:

  • faithful — 元のタイミングを保持します(デフォルト)
  • burst — すべてのチャンクを直ちに送ります
  • paced — 等間隔の 10ms

Docker Compose​

bge 埋め込みサイドカーは deploy/docker-compose.yml に含まれています。

bge-embedder:
image: ghcr.io/huggingface/text-embeddings-inference:latest
command: --model-id BAAI/bge-small-en-v1.5 --dtype float32
ports: ["6006:80"]

Prometheus メトリクス​

メトリクス型ラベル説明
cache_hits_totalCountertype, org_id検索種別ごとのキャッシュヒット
cache_writes_totalCounterstatus書き込み試行(written/dropped)
cache_purged_totalCounterbackend削除された期限切れエントリ
cache_sizeGaugebackend現在のエントリ数
cache_lookup_duration_secondsHistogramtype検索レイテンシ
cache_write_queue_sizeGauge—保留中の書き込みジョブ
cache_write_queue_drops_totalCounter—破棄された書き込み(キュー満杯)
cache_embedding_errors_totalCounter—埋め込みの失敗

マイグレーション​

キャッシュテーブルを作成するには、マイグレーション 0009 を実行します。

-- migrations/0009_pgvector.up.sql
CREATE EXTENSION IF NOT EXISTS vector;
CREATE TABLE cache_entries (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
org_id UUID NOT NULL, model_tier TEXT NOT NULL,
prompt_hash TEXT NOT NULL, embedding vector(384) NOT NULL,
response JSONB NOT NULL, sse_chunks JSONB,
tokens_in INT DEFAULT 0, tokens_out INT DEFAULT 0,
hit_count INT DEFAULT 0, model_version TEXT DEFAULT '1',
created_at TIMESTAMPTZ DEFAULT now(),
expires_at TIMESTAMPTZ DEFAULT (now() + interval '24 hours')
);

テスト​

  • ユニットテスト: go test ./pkg/cache/...
  • ベンチマーク: go test -bench=. ./pkg/cache/...
  • 統合テスト(Docker が必要): go test -race ./services/gateway/integration/...