ランブック: キャッシュヒット率が 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)。エントリはライブトラフィックからのみ書き込まれます。
- request_logs から、欠落している上位のプロンプトを特定します
- それらのプロンプトをゲートウェイ経由で実行します(実トラフィック、または再生したトラフィッ ク)
- その後 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の推移を週次でレビューします - 正規化方針の月次監査: 誤った衝突の報告がないか確認します