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

ランブック: キャッシュヒット率が 25% を下回った

診断手順​

1. メトリクスの即時確認​

# From Grafana dashboard or Prometheus:
# - cache_hits_total{type="miss"} spike?
# - cache_lookup_duration_seconds p99 > 15ms?
# - cache_embedding_errors_total increasing?
# - cache_write_queue_drops_total increasing?

curl http://localhost:2112/metrics | grep "cache_"

2. エンベッダーの健全性確認​

# bge-embedder health check (port 6006)
curl http://localhost:6006/health

# Check embedder logs
docker logs deploy-bge-embedder-1 --tail=50

3. キャッシュ設定の確認​

# Verify org cache settings haven't been accidentally changed
curl -H "Authorization: Bearer $ADMIN_TOKEN" \
http://localhost:2112/api/organizations/$ORG_ID/cache-settings

# Check if any orgs were switched to "exact" or "off" mode
curl -H "Authorization: Bearer $ADMIN_TOKEN" \
http://localhost:2112/api/organizations?cache_mode=off

4. スキーマ変更の確認​

# Verify pgvector extension is still valid
docker exec deploy-postgres-1 psql -U yabanin -d yabanin \
-c "SELECT extversion FROM pg_extension WHERE extname='vector';"

# Check cache_entries table size
docker exec deploy-postgres-1 psql -U yabanin -d yabanin \
-c "SELECT count(*), min(expires_at), max(expires_at) FROM cache_entries;"

5. トラフィックパターン変化の確認​

# Look at request volume vs cache hits in the last hour
curl -H "Authorization: Bearer $ADMIN_TOKEN" \
http://localhost:2112/api/analytics/$ORG_ID/cache?from=$(date -u -d '1 hour ago' +%Y-%m-%dT%H:%M:%SZ)

# Check if new request patterns don't match existing cache entries
docker exec deploy-postgres-1 psql -U yabanin -d yabanin \
-c "SELECT count(*) FROM request_logs WHERE created_at > now() - interval '1 hour' AND cache_hit_type IS NULL;"

是正措置​

即時対応: フラッシュ​

キャッシュに古いエントリがある場合、または埋め込みモデルが変わった場合:

# Flush entire cache (root admin only)
curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \
"http://localhost:2112/api/cache/flush?org_id=$ORG_ID&reason=low_hit_rate"

# NOTE: cache warming was removed (W-CACHE); POST /api/cache/warm answers 410.
# The semantic cache re-populates from live traffic only.

中期対応: しきい値の調整​

セマンティックキャッシュのヒットが少なすぎる場合(しきい値が高すぎる場合):

  • pkg/cache/semantic.go を編集し、DefaultSimilarityThreshold を 0.95 から 0.92 に変更します
  • ゲートウェイを再起動します: docker compose restart gateway

誤検知が多すぎる場合(しきい値が低すぎる場合):

  • しきい値を 0.97 に上げます

長期対応: 新しいキャッシュエントリの追加​

キャッシュのウォーミングは削除されています(W-CACHE)。エントリはライブトラフィックからのみ書き込まれます。

  1. request_logs から、欠落している上位のプロンプトを特定します
  2. それらのプロンプトをゲートウェイ経由で実行します(実トラフィック、または再生したトラフィック)
  3. その後 30 分間、ヒット率の改善を監視します

エスカレーション​

症状対応
エンベッダー停止が 5 分超P1 インシデント — エンベッダーを再起動し、Redis のみのモードへフォールバックする
キャッシュ書き込みキューのドロップが毎分 10 超Redis のディスク I/O を確認する。cache_write_queue_size の増加を検討する
pgvector 拡張の欠落重大 — pgvector のマイグレーションが未適用。直ちにマイグレーション 0009 を実行する
フラッシュ後 1 時間超にわたってヒット率が 10% 未満正規化方針を見直す。リクエストパターンが大きく変わっていないか確認する

予防​

  • Grafana アラートを設定します: cache_hits_total{type="miss"} / (cache_hits_total{type="exact"} + cache_hits_total{type="semantic"} + cache_hits_total{type="miss"}) > 0.75 for 15m
  • ダッシュボードの savings_usd の推移を週次でレビューします
  • 正規化方針の月次監査: 誤った衝突の報告がないか確認します