セマンティックキャッシュ
セマンティックキャッシュシステムは、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.go | SHA-256 をキーとする Redis ストア。TTL は 24 時間 |
| pgvector ストレージ | pkg/cache/store.go | CRUD 操作、ベクトル I/O ヘルパー |
| セマンティック検索 | pkg/cache/semantic.go | HNSW のコサイン距離による ANN 検索 |
| 書き込みパイプライン | pkg/cache/writer.go | キャッシュ書き込み用の非同期ワーカープール |
| SSE リプレイ | pkg/cache/replay.go | RecordingWriter と 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/B | pkg/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_total | Counter | type, org_id | 検索種別ごとのキャッシュヒット |
cache_writes_total | Counter | status | 書き込み試行(written/dropped) |
cache_purged_total | Counter | backend | 削除された期限切れエントリ |
cache_size | Gauge | backend | 現在のエントリ数 |
cache_lookup_duration_seconds | Histogram | type | 検索レイテンシ |
cache_write_queue_size | Gauge | — | 保留中の書き込みジョブ |
cache_write_queue_drops_total | Counter | — | 破棄された書き込み(キュー満杯) |
cache_embedding_errors_total | Counter | — | 埋め込みの失敗 |
マイグレーション
キャッシュテーブルを作成するには、マイグレーション 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/...