Seni Bina Cache
Gambaran keseluruhan
Sistem cache semantik Yabanin mengurangkan kos dan kependaman LLM dengan menyimpan respons dalam cache pada beberapa lapisan. Ia menyokong kawalan privasi per organisasi, ujian A/B, dan kebolehcerapan yang menyeluruh.
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
Komponen
| Komponen | Penerangan |
|---|---|
| CacheService | Pengatur cara peringkat atas — mengurus cache tepat Redis, cache semantik pgvector, dan saluran tulis tak segerak |
| RedisStore | Stor kunci-nilai dalam memori disokong Redis. Kunci: cache:{org_id}:{model_tier}:{hash} |
| SemanticCache | Carian ANN atas pgvector menggunakan indeks HNSW dengan ambang keserupaan kosinus (0.95) |
| Writer | Saluran tulis tak segerak dengan 4 pekerja, Submit() tidak menyekat, pengurusan baris gilir buang-apabila-penuh |
| Cleaner | Janitor TTL berkala (selang 5 min) yang membersihkan entri tamat tempoh daripada kedua-dua bahagian belakang |
| Invalidator | Pembatalan berskop organisasi, berskop versi model, dan berskop cincang prompt melalui Redis SCAN + DELETE pgvector |
| PolicyCache | Cache dasar per organisasi dengan TTL 60 s — mengawal mod didayakan/dilumpuhkan/baca sahaja |
| Analytics | Penjejakan hit/miss dalam memori dengan pecahan per organisasi dan per peringkat |
| ABTest | Pembahagian berasaskan cincang deterministik untuk eksperimen A/B (kawalan lwn rawatan) |
| Warmer | Dialih keluar (W-CACHE): menulis entri tidak bertandatangan yang sentiasa ditolak oleh carian RT-05; /api/cache/warm menjawab 410 |
Aliran cache
Laluan baca (carian)
- Semakan Cache-Control: no-store — langkau jika ada
- Semakan dasar per organisasi — langkau jika dilumpuhkan/baca sahaja
- Carian tepat Redis mengikut
sha256(normalized_prompt)— laluan terpantas - Carian tepat pgvector mengikut prompt_hash + model_version — untuk entri
yang ditulis ke pgvector sahaja. Dilumpuhkan secara lalai
(
YABANIN_CACHE_PG_EXACT_LOOKUP=trueuntuk dayakan semula): Redis ialah lapisan tepat; carian tepat pg hanya membantu selepas kehilangan data Redis dan memerlukan perjalanan pergi balik Postgres pada setiap miss. - Carian ANN semantik — benam prompt → keserupaan kosinus ≥ 0.95 → pulangkan jika dijumpai
- Jika semua miss: teruskan ke penyedia huluan
Laluan tulis (selepas respons huluan berjaya)
- Semak
shouldCache()— langkau respons ralat, badan kosong, organisasi no-store - Tulis tepat Redis — segerak, sentiasa pantas
- Tulis pgvector tak segerak — kolam 4 pekerja, mengira embedding, upsert ke cache_entries
Model privasi
| Mod | Carian | Tulis | Penerangan |
|---|---|---|---|
off | ❌ | ❌ | Tiada cache sama sekali |
exact | ✅ (Redis sahaja) | ✅ (Redis + pgvector) | Padanan kunci tepat sahaja |
semantic | ✅ (Redis + pgvector) | ✅ (Redis + pgvector) | Cache semantik penuh |
Togol hanya untuk pentadbir, dengan pengelogan audit. Perubahan mencetuskan pembatalan cache automatik bagi organisasi yang terjejas.
Penalaan ambang
- Keserupaan kosinus: 0.95 (lalai). Lebih rendah = lebih banyak hit, risiko positif palsu lebih tinggi.
- HNSW ef_search: 100 (lalai). Lebih tinggi = ingatan semula lebih baik, pertanyaan lebih perlahan.
- TTL: 24 jam (Redis), boleh dikonfigurasi per organisasi melalui dasar.
- Model embedding:
BAAI/bge-small-en-v1.5(384 dimensi)
Overhed kos dan kependaman
Cache tidak percuma — ini bilnya, supaya anda boleh membandingkannya dengan penjimatan yang diukur pada trafik anda sendiri.
| Lapisan | Kos laluan panas | Nota |
|---|---|---|
| Hit tepat (Redis) | SHA-256 + satu Redis GET | Tiada panggilan model; perjalanan pergi balik sub-milisaat pada Redis seletak |
| Carian semantik | 1 embed (~20 ms CPU, bge-small) + 1 pertanyaan ANN pgvector | HNSW ef_search=100; kedua-dua laluan mempunyai histogram Prometheus (cache_lookup_duration_seconds) |
| Tulis cache | di luar laluan panas | Kolam tak segerak 4 pekerja; buang-apabila-penuh, tidak sekali-kali menyekat respons |
| Storan | ~1.6 KB/entri vektor (384 × float32) + JSONB respons | TTL 24 j, janitor setiap 5 min |
Asas infra: satu sidecar embedder (CPU sahaja mengendalikan ~100 RPS menurut
nota penskalaan pengelas) ditambah
Postgres/Redis yang anda sudah jalankan untuk gerbang. make bench-cache menghasilkan semula
nombor carian pada perkakasan anda; cache_hits_total{type} dan
cache_similarity_score menunjukkan nilai langsung pada trafik anda sendiri. Jika kadar hit
rendah bagi sesebuah organisasi, mod privasi (exact / off) mematikan lapisan semantik
per organisasi — lapisan tepat kekal.
Diukur (make bench-cache)
Rujukan: Apple M5 Max, Redis 7 dalam Docker pada localhost, 2026-09-02.
Hasilkan semula pada perkakasan anda dengan make bench-cache.
| Penanda aras | Hasil | Apa itu |
|---|---|---|
ExactCache_Get_Hit | ~0.22 ms/op, 11 allocs | hit tepat penuh: SHA-256 + perjalanan pergi balik Redis GET |
ExactCache_Get_Miss | ~0.24 ms/op, 14 allocs | laluan miss tepat |
SemanticNormalize_Normalized | ~1.7 µs/op | penormalan JSON kanonik sebelum embedding |
CosineDistance (384-dim) | ~93 ns/op, 0 allocs | penilaian keserupaan itu sendiri |
Tidak diliputi oleh penanda aras unit: panggilan HTTP embedder (~20 ms CPU untuk
bge-small menurut nota pengelas — lihat make bench-cache-live untuk angka
langsung) dan pertanyaan ANN pgvector, yang memerlukan Postgres yang berjalan; pada trafik
langsung kedua-duanya kelihatan dalam cache_lookup_duration_seconds{type=semantic}.
Pemantauan
Metrik Prometheus
| Metrik | Jenis | Penerangan |
|---|---|---|
cache_hits_total{type,org_id} | Kaunter | Hit cache mengikut sumber (exact/semantic/miss) |
cache_writes_total{status} | Kaunter | Percubaan tulis (written/dropped) |
cache_lookup_duration_seconds{type} | Histogram | Kependaman carian p50/p90/p99 |
cache_similarity_score | Histogram | Keserupaan kosinus pada hit semantik |
cache_size{backend} | Tolok | Kiraan entri per bahagian belakang |
cache_write_queue_size | Tolok | Kerja tulis yang belum selesai |
cache_janitor_runs_total | Kaunter | Larian janitor TTL |
cache_ab_arm_total{variant} | Kaunter | Penetapan lengan eksperimen A/B |
Papan pemuka Grafana
Papan pemuka 8 panel meliputi kadar hit, persentil kependaman, taburan keserupaan, kedalaman baris gilir, pecahan per organisasi, savings_usd, statistik janitor, dan kadar ralat. Import melalui docs/observability/cache-dashboard.json.
Aliran eksperimen A/B
- Pentadbir mencipta eksperimen dengan varian kawalan (cache=off) dan rawatan (cache=enabled)
- Gerbang menetapkan setiap organisasi secara deterministik:
hash(org_id + experiment_id) % 100 < traffic_pct - Lengan kawalan: langkau semua carian cache, sentiasa teruskan huluan
- Lengan rawatan: saluran carian cache penuh
- Hasil dikumpul melalui
/api/cache/experiments/{id}/resultsyang membandingkan savings_usd per varian
Pemanasan cache (dialih keluar)
Pemanasan cache telah dialih keluar (W-CACHE): entri yang dipanaskan tidak mempunyai tandatangan HMAC RT-05, jadi setiap carian menolaknya. /api/cache/warm kini menjawab 410 Gone; cache semantik belajar secara eksklusif daripada trafik langsung.