Cache semantik
Sistem cache semantik menyediakan cache berbilang lapisan untuk respons LLM, menggabungkan cache Redis padanan tepat dengan carian semantik berasaskan pgvector.
Seni bina
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
Komponen
| Komponen | Pakej | Keterangan |
|---|---|---|
| Cache tepat Redis | pkg/cache/redis.go | Stor Redis berkunci SHA-256, TTL 24 jam |
| Storan pgvector | pkg/cache/store.go | Operasi CRUD, pembantu I/O vektor |
| Carian semantik | pkg/cache/semantic.go | Carian ANN melalui jarak kosinus HNSW |
| Talian paip tulis | pkg/cache/writer.go | Kolam pekerja tak segerak untuk penulisan cache |
| Main semula SSE | pkg/cache/replay.go | RecordingWriter + 3 mod main semula |
| Penormalan kunci | pkg/cache/normalize.go | JSON kanonik untuk hash yang konsisten |
| Perkhidmatan pembenaman | pkg/embeddings/client.go | Klien HTTP untuk API pembenaman |
| Perkhidmatan bersatu | pkg/cache/service.go | Mengorkestrakan semua lapisan dengan kawalan privasi |
| Dasar privasi | pkg/cache/service.go | Mod enabled/disabled/read-only bagi setiap organisasi |
| Pembersih TTL | pkg/cache/cleaner.go | Pembersihan berkala entri yang tamat tempoh |
| Metrik Prometheus | pkg/cache/metrics.go | 8 vektor metrik khusus cache |
| Analitik + A/B | pkg/cache/analytics.go | Penjejakan kadar hit, pembahagian trafik, pemanasan |
Trafik berbilang bahasa (Jepun dan lain-lain)
bge-small-en-v1.5 dilatih dalam bahasa Inggeris: pada trafik Jepun (dan bahasa bukan Inggeris
yang lain) kepersisan cache semantik dan ketepatan pengelas merosot. Bagi
pelaksanaan berbilang bahasa, tukar embedder kepada model berbilang bahasa melalui
konfigurasi — tiada perubahan kod:
YABANIN_EMBEDDER_MODEL=intfloat/multilingual-e5-small
YABANIN_EMBEDDER_QUERY_PREFIX="query: "
Nota:
multilingual-e5-smallmengekalkan 384 dimensi yang sama seperti bge-small-en, jadi skema pgvector sedia ada (vector(384)) tidak memerlukan migrasi (sahkan dimensi pada but pertama — ketidakpadanan menggagalkan sisipan secara ketara dan bukannya merosakkan cache).- Model keluarga e5 dilatih dengan awalan input.
YABANIN_EMBEDDER_QUERY_PREFIXyang dikonfigurasi ditambah di hadapan setiap teks yang dibenamkan — carian mahupun penulisan — supaya perbandingan kosinus kekal simetri. Menukar awalan membatalkan entri semantik sedia ada; siram cache (POST /api/cache/flush) selepas pertukaran. - Pengelas tugas ialah model berasingan dengan data latihan (bahasa Inggeris) tersendiri; penentuan peringkat berpenghalaan pada trafik Jepun kembali kepada peringkat peraturan V0. Latihan semula pengelas pada prompt Jepun dijejaki secara berasingan.
Profil compose dengan sidecar embedder berbilang bahasa terdapat dalam
deploy/docker-compose.yml (embedder-multilingual).
Kawalan privasi
Setiap organisasi mempunyai dasar cache:
- enabled — akses cache baca/tulis penuh
- disabled — tiada cache sama sekali (privasi diutamakan)
- read-only — boleh mencari respons yang dicache tetapi tidak pernah menulis yang baharu
Dasar dicache dalam memori dengan TTL 60s untuk mengelakkan overhed pangkalan data pada setiap permintaan.
Penstriman SSE
Bagi respons penstriman, cache menangkap bingkai SSE individu beserta pemasaan:
rw := cache.NewRecordingWriter(w)
// ... upstream response is written through rw ...
chunks := rw.Chunks() // []SSEChunk{Data, DelayMS}
Mod main semula:
- faithful — kekalkan pemasaan asal (lalai)
- burst — hantar semua cebisan serta-merta
- paced — selang sama 10ms
Docker Compose
Sidecar pembenaman bge disertakan dalam 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"]
Metrik Prometheus
| Metrik | Jenis | Label | Keterangan |
|---|---|---|---|
cache_hits_total | Kaunter | type, org_id | Hit cache mengikut jenis carian |
cache_writes_total | Kaunter | status | Percubaan tulis (written/dropped) |
cache_purged_total | Kaunter | backend | Entri tamat tempoh yang dibuang |
cache_size | Tolok | backend | Kiraan entri semasa |
cache_lookup_duration_seconds | Histogram | type | Kependaman carian |
cache_write_queue_size | Tolok | — | Tugas tulis yang menunggu |
cache_write_queue_drops_total | Kaunter | — | Tulisan yang digugurkan (giliran penuh) |
cache_embedding_errors_total | Kaunter | — | Kegagalan pembenaman |
Migrasi
Jalankan migrasi 0009 untuk mencipta jadual cache:
-- 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')
);
Ujian
- Ujian unit:
go test ./pkg/cache/... - Penanda aras:
go test -bench=. ./pkg/cache/... - Integrasi (memerlukan Docker):
go test -race ./services/gateway/integration/...