Skip to main content

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​

KomponenPakejKeterangan
Cache tepat Redispkg/cache/redis.goStor Redis berkunci SHA-256, TTL 24 jam
Storan pgvectorpkg/cache/store.goOperasi CRUD, pembantu I/O vektor
Carian semantikpkg/cache/semantic.goCarian ANN melalui jarak kosinus HNSW
Talian paip tulispkg/cache/writer.goKolam pekerja tak segerak untuk penulisan cache
Main semula SSEpkg/cache/replay.goRecordingWriter + 3 mod main semula
Penormalan kuncipkg/cache/normalize.goJSON kanonik untuk hash yang konsisten
Perkhidmatan pembenamanpkg/embeddings/client.goKlien HTTP untuk API pembenaman
Perkhidmatan bersatupkg/cache/service.goMengorkestrakan semua lapisan dengan kawalan privasi
Dasar privasipkg/cache/service.goMod enabled/disabled/read-only bagi setiap organisasi
Pembersih TTLpkg/cache/cleaner.goPembersihan berkala entri yang tamat tempoh
Metrik Prometheuspkg/cache/metrics.go8 vektor metrik khusus cache
Analitik + A/Bpkg/cache/analytics.goPenjejakan 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-small mengekalkan 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_PREFIX yang 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​

MetrikJenisLabelKeterangan
cache_hits_totalKauntertype, org_idHit cache mengikut jenis carian
cache_writes_totalKaunterstatusPercubaan tulis (written/dropped)
cache_purged_totalKaunterbackendEntri tamat tempoh yang dibuang
cache_sizeTolokbackendKiraan entri semasa
cache_lookup_duration_secondsHistogramtypeKependaman carian
cache_write_queue_sizeTolok—Tugas tulis yang menunggu
cache_write_queue_drops_totalKaunter—Tulisan yang digugurkan (giliran penuh)
cache_embedding_errors_totalKaunter—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/...