Skip to main content

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​

KomponenPenerangan
CacheServicePengatur cara peringkat atas — mengurus cache tepat Redis, cache semantik pgvector, dan saluran tulis tak segerak
RedisStoreStor kunci-nilai dalam memori disokong Redis. Kunci: cache:{org_id}:{model_tier}:{hash}
SemanticCacheCarian ANN atas pgvector menggunakan indeks HNSW dengan ambang keserupaan kosinus (0.95)
WriterSaluran tulis tak segerak dengan 4 pekerja, Submit() tidak menyekat, pengurusan baris gilir buang-apabila-penuh
CleanerJanitor TTL berkala (selang 5 min) yang membersihkan entri tamat tempoh daripada kedua-dua bahagian belakang
InvalidatorPembatalan berskop organisasi, berskop versi model, dan berskop cincang prompt melalui Redis SCAN + DELETE pgvector
PolicyCacheCache dasar per organisasi dengan TTL 60 s — mengawal mod didayakan/dilumpuhkan/baca sahaja
AnalyticsPenjejakan hit/miss dalam memori dengan pecahan per organisasi dan per peringkat
ABTestPembahagian berasaskan cincang deterministik untuk eksperimen A/B (kawalan lwn rawatan)
WarmerDialih keluar (W-CACHE): menulis entri tidak bertandatangan yang sentiasa ditolak oleh carian RT-05; /api/cache/warm menjawab 410

Aliran cache​

Laluan baca (carian)​

  1. Semakan Cache-Control: no-store — langkau jika ada
  2. Semakan dasar per organisasi — langkau jika dilumpuhkan/baca sahaja
  3. Carian tepat Redis mengikut sha256(normalized_prompt) — laluan terpantas
  4. Carian tepat pgvector mengikut prompt_hash + model_version — untuk entri yang ditulis ke pgvector sahaja. Dilumpuhkan secara lalai (YABANIN_CACHE_PG_EXACT_LOOKUP=true untuk dayakan semula): Redis ialah lapisan tepat; carian tepat pg hanya membantu selepas kehilangan data Redis dan memerlukan perjalanan pergi balik Postgres pada setiap miss.
  5. Carian ANN semantik — benam prompt → keserupaan kosinus ≥ 0.95 → pulangkan jika dijumpai
  6. Jika semua miss: teruskan ke penyedia huluan

Laluan tulis (selepas respons huluan berjaya)​

  1. Semak shouldCache() — langkau respons ralat, badan kosong, organisasi no-store
  2. Tulis tepat Redis — segerak, sentiasa pantas
  3. Tulis pgvector tak segerak — kolam 4 pekerja, mengira embedding, upsert ke cache_entries

Model privasi​

ModCarianTulisPenerangan
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.

LapisanKos laluan panasNota
Hit tepat (Redis)SHA-256 + satu Redis GETTiada panggilan model; perjalanan pergi balik sub-milisaat pada Redis seletak
Carian semantik1 embed (~20 ms CPU, bge-small) + 1 pertanyaan ANN pgvectorHNSW ef_search=100; kedua-dua laluan mempunyai histogram Prometheus (cache_lookup_duration_seconds)
Tulis cachedi luar laluan panasKolam tak segerak 4 pekerja; buang-apabila-penuh, tidak sekali-kali menyekat respons
Storan~1.6 KB/entri vektor (384 × float32) + JSONB responsTTL 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 arasHasilApa itu
ExactCache_Get_Hit~0.22 ms/op, 11 allocshit tepat penuh: SHA-256 + perjalanan pergi balik Redis GET
ExactCache_Get_Miss~0.24 ms/op, 14 allocslaluan miss tepat
SemanticNormalize_Normalized~1.7 µs/oppenormalan JSON kanonik sebelum embedding
CosineDistance (384-dim)~93 ns/op, 0 allocspenilaian 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​

MetrikJenisPenerangan
cache_hits_total{type,org_id}KaunterHit cache mengikut sumber (exact/semantic/miss)
cache_writes_total{status}KaunterPercubaan tulis (written/dropped)
cache_lookup_duration_seconds{type}HistogramKependaman carian p50/p90/p99
cache_similarity_scoreHistogramKeserupaan kosinus pada hit semantik
cache_size{backend}TolokKiraan entri per bahagian belakang
cache_write_queue_sizeTolokKerja tulis yang belum selesai
cache_janitor_runs_totalKaunterLarian janitor TTL
cache_ab_arm_total{variant}KaunterPenetapan 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​

  1. Pentadbir mencipta eksperimen dengan varian kawalan (cache=off) dan rawatan (cache=enabled)
  2. Gerbang menetapkan setiap organisasi secara deterministik: hash(org_id + experiment_id) % 100 < traffic_pct
  3. Lengan kawalan: langkau semua carian cache, sentiasa teruskan huluan
  4. Lengan rawatan: saluran carian cache penuh
  5. Hasil dikumpul melalui /api/cache/experiments/{id}/results yang 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.