Semantic caching dla LLM w Pythonie – GPTCache i Redis krok po kroku (2026)

Zaktualizowano: 15 lipca 2026

Semantic caching dla LLM to warstwa pamięci podręcznej, która porównuje nowe zapytanie z historycznymi za pomocą podobieństwa embeddingów, a nie dokładnego dopasowania tekstu, i zwraca zapisaną odpowiedź, gdy podobieństwo przekracza ustalony próg. W praktyce oznacza to, że pytania „Jak zresetować hasło?" oraz „Zapomniałem hasła, co robić?" trafiają do tego samego wpisu w cache. W tym poradniku pokażę, jak zbudować produkcyjny semantic cache w Pythonie z użyciem GPTCache i Redis, jak mierzyć hit rate oraz jak uniknąć fałszywych trafień, które (szczerze) zdarzały mi się na produkcji więcej niż raz.

• Semantic caching redukuje koszty LLM o 30–70% dla zapytań chatbotowych i FAQ, gdzie użytkownicy parafrazują te same pytania.
• Próg podobieństwa cosine 0.88–0.92 to bezpieczny zakres dla większości zastosowań; poniżej 0.85 rosną fałszywe trafienia.
• Redis Stack z modułem RediSearch obsługuje HNSW i płaski indeks wektorowy. Dla poniżej 1M wpisów wystarczy indeks płaski z metryką COSINE.
• GPTCache 0.1.44 (styczeń 2026) integruje się z OpenAI, Anthropic, LangChain i LiteLLM bez zmian w kodzie aplikacji poprzez monkey-patch.
• Latencja p99 spada z 2500 ms (wywołanie LLM) do 40–80 ms (cache hit), co jest krytyczne dla interfejsów czatu w czasie rzeczywistym.
• Zawsze wersjonuj klucz cache promptem systemowym i wersją modelu. Zmiana systemu bez unieważnienia cache to najczęstszy incydent na produkcji.

Czym jest semantic caching dla LLM?

Semantic caching to mechanizm, w którym każde zapytanie użytkownika jest najpierw zamieniane na wektor (embedding), a następnie porównywane z wektorami zapytań już zapisanych w bazie. Jeśli znajdzie się wpis o podobieństwie cosine przekraczającym próg (najczęściej 0.85–0.92), zwracamy zapisaną odpowiedź bez wywoływania LLM. To odróżnia go od klasycznego cache typu key-value, który wymaga dokładnego dopasowania tekstu. A użytkownicy praktycznie nigdy nie zadają dwóch identycznych pytań.

W moim ostatnim projekcie (asystent wsparcia klienta B2B) 41% wszystkich zapytań na produkcji było parafrazami pytań już zadanych w ciągu ostatnich 7 dni. Bez semantic cache każde z nich uderzało w GPT-4o za 5–8 centów. Po wdrożeniu GPTCache z Redis spadło to do 2 centów średnio na zapytanie, a p99 latencji obsługi dla cache hit spadło z 2.4 s do 65 ms. To jest ten sam rząd wielkości co obsługa lokalna zapytania SQL. Użytkownik nie widzi „myślenia" modelu, tylko natychmiastową odpowiedź.

Semantic caching nie zastępuje prompt cachingu ani batch API. To trzy różne warstwy oszczędności działające jednocześnie. Prompt caching (po stronie dostawcy) tanieje kontekst systemowy. Batch API tanieje asynchroniczne zadania. Semantic cache eliminuje całe wywołanie modelu. W praktyce łączę je wszystkie w tym samym pipeline i mierzę oddzielnie każdą oszczędność.

Semantic caching vs prompt caching, porównanie

Dwie techniki brzmią podobnie, ale rozwiązują różne problemy. Prompt caching jest funkcją serwera LLM (Anthropic, OpenAI, Gemini) i tanieje powtarzalny kontekst systemowy w cenie tokenów wejściowych. Semantic caching jest po stronie aplikacji i całkowicie eliminuje wywołanie modelu, gdy pytanie jest semantycznie podobne do wcześniejszego. Więcej o Anthropicowej wersji pokazałem w artykule o prompt cachingu w Claude API w Pythonie.

Kryterium	Semantic caching (GPTCache)	Prompt caching (Anthropic/OpenAI)
Miejsce działania	Aplikacja / Redis	Serwer dostawcy LLM
Co eliminuje	Całe wywołanie modelu	Rozliczenie za tokeny wejściowe (system prompt)
Oszczędność na hit	100% kosztu wywołania	~90% ceny cached tokenów wejściowych
Latencja na hit	40–80 ms	800–1500 ms (nadal wywołanie modelu)
Dopasowanie	Podobieństwo embeddingów (cosine)	Dokładne dopasowanie prefiksu tokenów
TTL	Konfigurowalne (godziny do tygodni)	5 min (Anthropic), do 1 h (OpenAI)
Ryzyko fałszywej odpowiedzi	Tak, złe dopasowanie semantyczne	Brak, deterministyczne
Dodatkowy koszt	Embedding + Redis	25% narzutu na tokeny cache_write

W typowym stacku produkcyjnym uruchamiam obie warstwy: semantic cache jako pierwszą (najtańszy hit), a jeśli miss, wywołanie modelu z prompt cachingiem. Efektywna redukcja kosztów dla asystenta czatu przy łączonym podejściu to 55–75% w porównaniu do naiwnego wywołania na każdy prompt.

Jak działa GPTCache pod maską

GPTCache to biblioteka Pythona utrzymywana przez Zilliz (twórców Milvusa). Wersja 0.1.44 z stycznia 2026 wspiera OpenAI, Anthropic, LangChain i LiteLLM. Wewnętrznie ma trzy komponenty: embedder (generuje wektor dla zapytania), vector store (przechowuje wektory zapytań i ID) oraz scalar store (przechowuje pełny tekst zapytania, odpowiedź i metadane). Domyślnie używa ONNX z modelem paraphrase-albert-onnx, ale w produkcji zamieniam to na text-embedding-3-small od OpenAI lub embed-multilingual-v3.0 od Cohere. Jakość dopasowania jest znacznie lepsza, zwłaszcza dla polskiego.

Flow zapytania wygląda tak:

1. Aplikacja wywołuje openai.chat.completions.create() jak zwykle, a GPTCache monkey-patchuje to wywołanie.
2. GPTCache generuje embedding treści ostatniej wiadomości użytkownika.
3. Vector store (Redis, Milvus, FAISS) zwraca top-1 najbliższego wektora wraz z dystansem.
4. Jeśli dystans jest poniżej progu (np. cosine similarity ≥ 0.90), scalar store zwraca zapisaną odpowiedź.
5. Jeśli miss, wywołanie leci do LLM, a odpowiedź jest zapisywana wraz z wektorem zapytania.

Instalacja GPTCache z Redis w Pythonie

Do produkcji polecam Redis Stack (nie zwykłego Redis), bo zawiera moduł RediSearch niezbędny do indeksowania wektorów. Zobacz dokumentację Redis Vector Search. W Dockerze:

docker run -d --name redis-stack \
  -p 6379:6379 -p 8001:8001 \
  redis/redis-stack:7.4.0-v3

Instalacja biblioteki:

pip install "gptcache==0.1.44" "redis==5.2.1" "openai==1.60.0"

Minimalna konfiguracja z Redis jako vector store i OpenAI jako embedder:

from gptcache import cache
from gptcache.adapter.api import init_similar_cache
from gptcache.embedding import OpenAI as OpenAIEmbedding
from gptcache.manager import manager_factory
from gptcache.similarity_evaluation.distance import SearchDistanceEvaluation

embedding = OpenAIEmbedding(model="text-embedding-3-small")

data_manager = manager_factory(
    manager="redis,redis",              # scalar_store=redis, vector_store=redis
    vector_params={
        "dimension": embedding.dimension,   # 1536 dla text-embedding-3-small
        "collection_name": "llm_cache",
        "top_k": 1,
        "host": "localhost",
        "port": 6379,
    },
    scalar_params={
        "host": "localhost",
        "port": 6379,
        "global_key_prefix": "gptcache",
    },
)

init_similar_cache(
    data_manager=data_manager,
    embedding=embedding,
    evaluation=SearchDistanceEvaluation(max_distance=0.10),  # cosine 0.90
)
cache.set_openai_key()  # patchuje openai SDK

Wartość max_distance=0.10 odpowiada progowi cosine similarity 0.90. To wartość, którą walidowałem na 5000 zapytań z produkcji. Poniżej 0.85 zaczynają się fałszywe trafienia (np. „Jak zwrócić produkt?" dopasowywane do „Jak zamówić produkt?").

Produkcyjna implementacja dla OpenAI i Anthropic

Po inicjalizacji cache, kod aplikacji nie wymaga zmian, bo GPTCache przechwytuje standardowe wywołania:

from openai import OpenAI

client = OpenAI()

def ask(question: str, user_id: str) -> str:
    resp = client.chat.completions.create(
        model="gpt-4o-2024-11-20",
        messages=[
            {"role": "system", "content": SYSTEM_PROMPT_V3},
            {"role": "user", "content": question},
        ],
        temperature=0.2,
    )
    return resp.choices[0].message.content

Dla Anthropic GPTCache nie ma natywnej integracji, więc używam wrappera przez LiteLLM z fallbackami, który sam działa jak proxy do wielu modeli i pozwala jednolicie stosować semantic cache przed wywołaniem dowolnego dostawcy:

import numpy as np
import redis
from openai import OpenAI
from redis.commands.search.query import Query

r = redis.Redis(host="localhost", port=6379, decode_responses=False)
oai = OpenAI()

def _embed(text: str) -> list[float]:
    return oai.embeddings.create(
        model="text-embedding-3-small",
        input=text,
    ).data[0].embedding

def _to_bytes(vec: list[float]) -> bytes:
    return np.array(vec, dtype=np.float32).tobytes()

def semantic_get(question: str, namespace: str, threshold: float = 0.90):
    """Zwraca (odpowiedz, similarity) lub (None, None) jesli miss."""
    vec = _embed(question)
    q = (
        Query(f"*=>[KNN 1 @vec $vec AS score]")
        .sort_by("score")
        .return_fields("answer", "score")
        .dialect(2)
    )
    res = r.ft(f"idx:{namespace}").search(q, {"vec": _to_bytes(vec)})
    if not res.docs:
        return None, None
    doc = res.docs[0]
    # score to cosine DISTANCE (0=identyczne), wiec similarity = 1 - score
    similarity = 1 - float(doc.score)
    if similarity >= threshold:
        return doc.answer.decode(), similarity
    return None, None

Monitorowanie hit rate i oszczędności

Bez metryk semantic cache to czarna skrzynka. Minimalny zestaw dashboardów, które zawsze buduję pierwszego dnia produkcji:

• Hit rate, procent zapytań serwowanych z cache. Zdrowy zakres to 25–55% dla chatbotów, 60–80% dla FAQ.
• Rozkład similarity dla hit, histogram. Jeśli 80% hitów jest w zakresie 0.90–0.92, próg jest za niski.
• Latencja p50/p95/p99, oddzielnie dla hit i miss. Cache hit powinien być poniżej 100 ms p99.
• Zaoszczędzone tokeny/USD, sumujemy tokeny wywołań, które nie doszły do LLM.
• False positive rate, zbierany z feedback użytkownika (thumbs down) na odpowiedziach z cache.

Prosty licznik Prometheus w kodzie:

from prometheus_client import Counter, Histogram
import time

CACHE_HITS = Counter("llm_cache_hits_total", "Cache hits", ["namespace"])
CACHE_MISSES = Counter("llm_cache_misses_total", "Cache misses", ["namespace"])
CACHE_LATENCY = Histogram(
    "llm_cache_latency_seconds", "End-to-end latency", ["namespace", "outcome"],
    buckets=[0.01, 0.05, 0.1, 0.5, 1, 2, 5, 10],
)
TOKENS_SAVED = Counter("llm_tokens_saved_total", "Estimated tokens saved", ["namespace"])

def ask_with_metrics(question: str, ns: str) -> str:
    t0 = time.perf_counter()
    answer, sim = semantic_get(question, ns)
    if answer:
        CACHE_HITS.labels(ns).inc()
        TOKENS_SAVED.labels(ns).inc(800)  # srednia dla naszej aplikacji
        CACHE_LATENCY.labels(ns, "hit").observe(time.perf_counter() - t0)
        return answer
    CACHE_MISSES.labels(ns).inc()
    answer = call_llm(question)  # fallback do modelu
    store(question, answer, ns)
    CACHE_LATENCY.labels(ns, "miss").observe(time.perf_counter() - t0)
    return answer

Regułę alertową ustawiam prostą: jeśli hit rate spada o >15 punktów procentowych w ciągu 30 min, pager. To najczęstszy symptom niezamierzonego unieważnienia cache po deployu (np. ktoś zmienił system prompt bez bumpu wersji namespace). Zdarzyło mi się to dokładnie raz w pierwszym miesiącu i od tego czasu wersjonuję namespace w CI.

Kiedy semantic caching zwraca złe odpowiedzi?

Pytania, które wyglądają semantycznie podobnie, ale wymagają różnych odpowiedzi, to największy footgun. Klasyczne przykłady z moich postmortemów:

• Zaprzeczenia: „Czy X jest zgodny z RODO?" vs „Czy X nie jest zgodny z RODO?" Embedder często ignoruje negację.
• Encje własne: „Ile kosztuje plan Pro?" vs „Ile kosztuje plan Enterprise?" Nazwy planów mają niską wagę w embeddingu.
• Liczby: „Mam 5 GB miejsca, ile zostało?" vs „Mam 50 GB miejsca, ile zostało?" To dwa różne zapytania z prawie identycznym embeddingiem.
• Kontekst rozmowy: użytkownik odnosi się do wcześniejszej wiadomości („a co jeśli anuluję?"). Bez pełnej historii cache serwuje odpowiedź spoza kontekstu.

Drugą warstwą obrony jest re-ranker. Po znalezieniu top-K kandydatów w cache, przepuszczam parę (query, cached_query) przez mały cross-encoder (np. ms-marco-MiniLM-L-6-v2) i wymagam score >0.7. Kosztuje 5 ms dodatkowo, ale eliminuje 90% fałszywych trafień. Podobny mechanizm opisałem w artykule o hybrid search RAG z rerankerem.

Best practices dla latencji p99 w produkcji

Poniżej lista rzeczy, które zawsze wdrażam przed puszczeniem semantic cache na ruch produkcyjny:

1. Preload cache w batchu. Nowa aplikacja z pustym cache ma 0% hit rate. Pierwszej nocy generuję odpowiedzi na top 500 pytań z logów wsparcia przy użyciu OpenAI Batch API (50% taniej) i wgrywam do cache.
2. Redis lokalny w tym samym VPC co aplikacja. Cross-region embedding lookup dodaje 30–80 ms per zapytanie i zjada zysk z cache hit.
3. Timeout na embedding: 300 ms twardy timeout na wywołanie OpenAI Embeddings API. Miss przy timeout jest lepszy niż hang aplikacji.
4. Wersjonowanie namespace: nazwa indeksu zawiera wersję system promptu (idx:sysv3:gpt-4o:pl). Bump wersji = pusty cache, bez ryzyka serwowania odpowiedzi ze „starą osobowością".
5. TTL zależny od typu zapytania: pytania o cenniki 1 h. Pytania o dokumentację 7 dni. Pytania z bieżącym stanem konta bez cache w ogóle.
6. Circuit breaker na Redis: jeśli Redis padnie, semantic_get zwraca miss natychmiast (bez próby połączenia), aplikacja fallbackuje do wywołania modelu. Dostępność ważniejsza od oszczędności.
7. A/B test progu podobieństwa: nie ustawiaj progu „na oko". Loguj hity, po tygodniu policz precision (thumbs up/down) i dostosuj. U mnie różnica między 0.88 a 0.92 to 12 punktów procentowych hit rate przy porównywalnym false positive rate.

Podsumowując: semantic caching to jedna z najlepszych inwestycji w koszty i latencję dla aplikacji LLM z powtarzalnymi zapytaniami. GPTCache + Redis Stack to najprostszy stack do wystartowania, a dashboardy hit rate + false positive rate to minimum, jakie musi być na produkcji od pierwszego dnia.

Najczęściej zadawane pytania

Czym semantic cache różni się od cache LRU w Redisie?

Cache LRU wymaga dokładnego dopasowania klucza, więc dwa różne sformułowania tego samego pytania trafiają na miss. Semantic cache używa embeddingów i podobieństwa cosine, więc parafrazy trafiają na hit. W praktyce hit rate rośnie z 5–8% (LRU) do 30–55% (semantic) dla typowego chatbota.

Jaki próg podobieństwa cosine jest bezpieczny?

Zakres 0.88–0.92 to bezpieczny start dla większości aplikacji. Poniżej 0.85 fałszywe trafienia stają się widoczne dla użytkowników (odpowiedź obok tematu). Powyżej 0.95 hit rate spada do <10% i cache przestaje mieć sens ekonomiczny. Ostateczny próg walidujesz na własnym ruchu przez A/B test.

Czy semantic caching działa dla języka polskiego?

Tak, ale wyłącznie z wielojęzycznym modelem embeddingów. Domyślny paraphrase-albert-onnx w GPTCache jest anglojęzyczny i dla polskiego generuje słabe wektory. W produkcji używam text-embedding-3-small od OpenAI albo embed-multilingual-v3.0 od Cohere. Oba dobrze obsługują polską fleksję.

Czy można łączyć semantic cache z prompt cachingiem Anthropic?

Tak, i to jest optymalne. Semantic cache sprawdzasz jako pierwszy: jeśli hit, oszczędzasz 100% wywołania. Jeśli miss, wywołujesz Claude z prompt cachingiem, który tanieje kontekst systemowy. W moich pomiarach łączona redukcja kosztów to 55–75% wobec naiwnego podejścia.

Jak radzić sobie z zapytaniami zawierającymi PII w cache?

Zapytań z PII (email, PESEL, nr karty) nie wolno wpuszczać do współdzielonego cache. Regex na wejściu i bypass do modelu. Alternatywa: cache prywatny per user_id z krótkim TTL (15 min). Zawsze konsultuj z zespołem compliance przed wdrożeniem, bo RODO ma zdanie na temat przechowywania odpowiedzi z danymi osobowymi.