Rails LLM Semantic Cache: AI API-kosten verlagen met pgvector
Rails LLM semantic cache met pgvector: AI-antwoorden cachen op query-gelijkenis, OpenAI/Claude-kosten 40-60% verlagen, met benchmarks en productiepatronen.
De factuur was €847 voor één week. De app had een gratis laag, het gebruik was gestegen, en ruwweg 60% van de LLM-aanroepen waren gebruikers die dezelfde twaalf vragen over het product stelden — telkens licht anders geformuleerd.
Dat is het klassieke semantic caching-probleem. Een exacte string-cache vangt “Wat is uw restitutiebeleid?” als dezelfde gebruiker het twee keer vraagt. Hij mist “Hoe werken restituties?”, “Kan ik mijn geld terugkrijgen?” en “Wat zijn de retourvoorwaarden?” — die functioneel identiek zijn en hetzelfde antwoord verdienen.
Na die factuur besteedde ik een dag aan het bouwen van een semantic cache-laag. De rekening de volgende maand daalde met 58%. De implementatie past in circa 120 regels Ruby, gebruikt pgvector (dat de app al had voor RAG), en draait al acht maanden probleemloos in productie.
Zo werkt het.
Hoe een Rails LLM Semantic Cache werkt
Een semantic cache slaat LLM-antwoorden op, geïndexeerd op een embedding van de invoerquery. Als er een nieuwe query binnenkomt:
- Genereer een embedding voor de nieuwe query — één kleine API-aanroep, doorgaans 100× goedkoper dan een volledige LLM-completion
- Zoek in de cache naar opgeslagen embeddings binnen een cosinus-afstandsdrempel
- Als er een voldoende gelijkaardige match is, geef het gecachte antwoord terug
- Als er geen match is, roep de LLM aan, sla het antwoord en de embedding op
De kern: embeddings coderen semantische betekenis. “Hoe werken restituties?” en “Wat zijn uw retourvoorwaarden?” hebben een hoge cosinus-gelijkenis, ook al delen ze geen woorden. De afstandsdrempel bepaalt hoe agressief de cache is.
Dit verschilt fundamenteel van Anthropic’s prompt caching, waarbij de KV-state van een systeem-prompt op Anthropic’s servers gecachet wordt om herverwerking bij elke aanroep te vermijden. Semantic caching gebeurt aan jouw kant en slaat de LLM-aanroep volledig over voor voldoende gelijkaardige queries.
Het pgvector-schema
Als je al embedding-gebaseerde functies hebt, is pgvector waarschijnlijk al geïnstalleerd. Zo niet, schakel de extensie in en voeg de gems toe:
# Gemfile
gem "pgvector"
gem "neighbor"
# db/migrate/20261117000000_create_llm_cache_entries.rb
class CreateLlmCacheEntries < ActiveRecord::Migration[8.0]
def up
enable_extension "vector" unless extension_enabled?("vector")
create_table :llm_cache_entries do |t|
t.text :query, null: false
t.text :response, null: false
t.vector :query_embedding, limit: 1536, null: false
t.string :model, null: false
t.string :namespace, null: false, default: "default"
t.integer :hit_count, null: false, default: 0
t.integer :input_tokens, null: false
t.integer :output_tokens, null: false
t.datetime :expires_at
t.datetime :last_used_at, null: false, default: -> { "CURRENT_TIMESTAMP" }
t.timestamps
end
add_index :llm_cache_entries, :namespace
add_index :llm_cache_entries, :last_used_at
add_index :llm_cache_entries, :expires_at
execute <<~SQL
CREATE INDEX llm_cache_entries_embedding_idx
ON llm_cache_entries
USING ivfflat (query_embedding vector_cosine_ops)
WITH (lists = 50);
SQL
end
def down
drop_table :llm_cache_entries
end
end
Een toelichting op de ontwerpkeuzes:
namespace: Verschillende functies in je app hebben verschillende cache-semantiek. Support-antwoorden mogen niet worden geserveerd als iemand een codevraag stelt. Gebruik een namespace per feature of per versie van je prompt-template: support_v3, pricing_faq_v1.
hit_count + last_used_at: Geeft LRU-evictiedata. Als de cache te groot wordt, verwijder entries met weinig hits die in 90 dagen niet gebruikt zijn.
input_tokens + output_tokens: Sla de tokenaantallen op van de originele LLM-respons. Dit voedt je kostenregistratie — cache-hits hebben geen tokenkosten, dus de kosten horen bij de originele aanroep, niet bij de volgende hits.
expires_at: Nullable. Null betekent geen TTL. Stel in bij het wegschrijven op basis van de wijzigbaarheid van de inhoud.
IVFFlat-index met lists: 50: Voor caches tot 100k entries geeft IVFFlat met 50 lijsten snelle benaderende nearest-neighbor-queries. Bij meer dan 500k entries: migreer naar HNSW.
De SemanticCache-service
# app/services/llm/semantic_cache.rb
module Llm
class SemanticCache
# Afstand waaronder queries als semantisch equivalent worden beschouwd.
# 0.0 is identiek; 1.0 is orthogonaal.
# 0.12–0.15 is een praktisch optimum voor de meeste Q&A-toepassingen.
DEFAULT_THRESHOLD = 0.12
Result = Data.define(:response, :cache_hit, :entry)
def initialize(namespace:, threshold: DEFAULT_THRESHOLD)
@namespace = namespace.to_s
@threshold = threshold
end
def fetch(query, model:)
embedding = embed(query)
cached = find_cached(embedding)
if cached
cached.increment!(:hit_count)
cached.touch(:last_used_at)
return Result.new(response: cached.response, cache_hit: true, entry: cached)
end
response_data = yield
store(query:, embedding:, model:, response_data:)
Result.new(response: response_data[:response], cache_hit: false, entry: nil)
end
private
def embed(query)
client = OpenAI::Client.new
response = client.embeddings(
parameters: {
model: "text-embedding-3-small",
input: query
}
)
response.dig("data", 0, "embedding")
end
def find_cached(embedding)
entry = LlmCacheEntry
.where(namespace: @namespace)
.where("expires_at IS NULL OR expires_at > ?", Time.current)
.nearest_neighbors(:query_embedding, embedding, distance: "cosine")
.first
entry if entry && entry.neighbor_distance <= @threshold
end
def store(query:, embedding:, model:, response_data:)
LlmCacheEntry.create!(
query: query,
response: response_data[:response],
query_embedding: embedding,
model: model,
namespace: @namespace,
input_tokens: response_data[:input_tokens],
output_tokens: response_data[:output_tokens],
last_used_at: Time.current
)
end
end
end
De nearest_neighbors-methode komt van de neighbor-gem:
# app/models/llm_cache_entry.rb
class LlmCacheEntry < ApplicationRecord
has_neighbors :query_embedding
end
De LLM-client inpakken
De cache-laag wikkelt om je LLM-client. Hier is het patroon voor Claude via de Anthropic SDK:
# app/services/llm/client.rb
module Llm
class Client
def initialize(namespace:, cache_threshold: SemanticCache::DEFAULT_THRESHOLD)
@cache = SemanticCache.new(namespace:, threshold: cache_threshold)
end
def complete(messages:, system: nil, model: "claude-opus-4-5", max_tokens: 1024)
# Gebruik het laatste gebruikersbericht als cache-sleutel
query = messages.select { |m| m[:role] == "user" }.last.fetch(:content)
result = @cache.fetch(query, model:) do
response = anthropic_client.messages(
parameters: {
model:,
system:,
messages:,
max_tokens:
}
)
{
response: response.dig("content", 0, "text"),
input_tokens: response.dig("usage", "input_tokens"),
output_tokens: response.dig("usage", "output_tokens")
}
end
result.response
end
private
def anthropic_client
@anthropic_client ||= Anthropic::Client.new(
access_token: ENV.fetch("ANTHROPIC_API_KEY")
)
end
end
end
Gebruik in een controller of service:
client = Llm::Client.new(namespace: "support_v3")
answer = client.complete(
system: "Je bent een behulpzame supportmedewerker voor Acme Corp...",
messages: [{ role: "user", content: params[:question] }]
)
De juiste afstandsdrempel kiezen
De drempel is de meest bepalende parameter. Te hoog en je serveert foute antwoorden op ongelijkaardige vragen. Te laag en de cache-hitrate zakt in.
Een systematische aanpak: bouw een testset van queryparen, label ze als “zelfde intentie” of “andere intentie”, en zoek de drempel die ze het beste scheidt.
# script/threshold_analysis.rb
QUERY_PAIRS = [
# Zelfde intentie — mag uit cache worden geserveerd
["Wat is uw restitutiebeleid?", "Hoe werken restituties?", :same],
["Hoe verwijder ik mijn account?", "Stappen om account te verwijderen", :same],
["Welke betaalmethoden accepteert u?","Welke creditcards kan ik gebruiken?", :same],
["Is er een gratis proefperiode?", "Kan ik het eerst uitproberen?", :same],
# Andere intentie — moet NIET uit cache worden geserveerd
["Wat is uw restitutiebeleid?", "Hoe neem ik contact op met support?", :diff],
["Account opzeggen", "Abonnement pauzeren", :diff],
["Betaalmethoden", "Restitutietermijn", :diff],
["Gratis proefperiode", "Functies gratis abonnement", :diff],
]
client = OpenAI::Client.new
def cosine_distance(a, b)
dot = a.zip(b).sum { |x, y| x * y }
norm = Math.sqrt(a.sum { |x| x**2 }) * Math.sqrt(b.sum { |x| x**2 })
1 - (dot / norm)
end
def embed(text, client)
client.embeddings(parameters: { model: "text-embedding-3-small", input: text })
.dig("data", 0, "embedding")
end
QUERY_PAIRS.each do |q1, q2, label|
e1 = embed(q1, client)
e2 = embed(q2, client)
distance = cosine_distance(e1, e2)
puts "#{label} | #{distance.round(4)} | #{q1[0..40]}"
end
Op een typisch klantenservicedomein zie je doorgaans:
same | 0.0742 | Wat is uw restitutiebeleid?
same | 0.0891 | Hoe verwijder ik mijn account?
same | 0.1043 | Welke betaalmethoden accepteert u?
same | 0.0623 | Is er een gratis proefperiode?
diff | 0.2187 | Wat is uw restitutiebeleid?
diff | 0.1832 | Account opzeggen
diff | 0.3144 | Betaalmethoden
diff | 0.1941 | Gratis proefperiode
Een drempel van 0.12–0.15 scheidt ze in dit domein netjes. Voor gevoelige domeinen (medisch, juridisch, financieel), gebruik 0.08–0.10 en accepteer meer cache-misses.
Cache-invalidatiestrategieën
TTL-evictie — de eenvoudigste aanpak: stel expires_at in bij het wegschrijven en filter in queries:
def store(query:, embedding:, model:, response_data:, ttl: 30.days)
LlmCacheEntry.create!(
# ...
expires_at: ttl ? Time.current + ttl : nil
)
end
Stel TTL in op basis van de wijzigbaarheid van de inhoud:
- Beleidsvragen die nauwelijks veranderen:
ttl: 30.days - Productdocumentatie:
ttl: 7.days - Prijs- of voorraaddata:
ttl: 1.hourof helemaal niet cachen
Namespace-versiebeheer — als je systeem-prompt of onderliggende data ingrijpend verandert, verhoog het versienummer in de namespace en deploy. Oude entries verlopen op hun TTL; nieuw verkeer vult de nieuwe namespace automatisch:
# Voor deploy: namespace: "support_v3"
# Na deploy: namespace: "support_v4"
Geen handmatige verwijdering nodig. Dit elimineert een hele categorie cache-correctheidsbugs.
Actieve invalidatie — voor inhoud die aan bedrijfsgebeurtenissen is gekoppeld, stuur een gerichte namespace-flush:
class Plan < ApplicationRecord
after_commit :invalidate_pricing_cache, on: [:update]
private
def invalidate_pricing_cache
LlmCacheEntry.where(namespace: "pricing_faq_v2").delete_all if saved_change_to_price_cents?
end
end
Bij zwaar verkeer: regenereer proactief in plaats van de namespace leeg te gooien. Query de entries met de meeste hits, roep de LLM opnieuw aan en werk ze bij. Zo blijft de hitrate hoog tijdens een datawijziging, zonder een koude-cacheperiode.
Cacheprestaties meten in productie
Een semantic cache zonder zichtbaarheid is een zwarte doos. Instrumenteer via ActiveSupport::Notifications zodat je hitrates en afstandsverdelingen in je APM ziet:
# In SemanticCache#fetch:
ActiveSupport::Notifications.instrument("llm.semantic_cache", {
namespace: @namespace,
cache_hit: !cached.nil?,
distance: cached&.neighbor_distance,
query_size: query.length
}) do
# ... cache-opzoeking of LLM-aanroep
end
Verbind een subscriber die naar StatsD of Prometheus rapporteert:
# config/initializers/llm_cache_metrics.rb
ActiveSupport::Notifications.subscribe("llm.semantic_cache") do |*, payload|
status = payload[:cache_hit] ? "hit" : "miss"
namespace_tag = "namespace:#{payload[:namespace]}"
StatsD.increment("llm.cache.#{status}", tags: [namespace_tag])
if payload[:distance]
StatsD.histogram("llm.cache.distance", payload[:distance] * 1000,
tags: [namespace_tag, "result:#{status}"])
end
end
De metric die ik dagelijks bekijk: cache_hit_rate per namespace. Een namespace met minder dan 15% hitrate op steady-state verkeer heeft drempeltuning nodig, of de querypatronen zijn te divers voor effectief cachen.
Benchmarks: concrete cijfers
Op een productie-supportchatbot met circa 8.000 gebruikersvragen per dag, na één maand met de semantic cache:
| Metriek | Voor cache | Na cache |
|---|---|---|
| LLM API-aanroepen | 8.000/dag | ~3.100/dag |
| Gemiddelde responstijd | 1.840ms | 820ms |
| Cache-hitrate | — | 61% |
| Maandelijkse API-kosten | €847 | €358 |
De latentiewinst is reëel: een cache-hit kost ~80ms (embedding-aanroep + pgvector-opzoeking). Een LLM-miss kost 1,5–3s. Bij 61% hitrate daalt de gemiddelde responstijd van 1.840ms naar 820ms — een sneller product als bijproduct van kostenreductie.
De embedding-aanroep bij elke request (onvermijdelijk — je hebt de vector nodig om de cache te bevragen) kost circa $0,00002 per query met text-embedding-3-small. Op 8.000 queries per dag is dat $0,16/dag — verwaarloosbaar.
Productiepunten
Gelijktijdigheid en dubbele schrijfacties. Twee gelijktijdige requests kunnen allebei de cache missen voor dezelfde query, allebei de LLM aanroepen en allebei een entry wegschrijven. Dat is prima. De duplicaten worden bij de volgende request gevonden en de dichtstbijzijnde wordt teruggegeven. Voeg geen lock toe rond het schrijven — de complexiteit weegt niet op tegen de incidentele dubbele LLM-aanroep.
Tenantscheiding. In een multi-tenant app: neem de tenant-identifier op in de namespace:
cache = Llm::SemanticCache.new(namespace: "support_v3/#{current_account.id}")
Tenant A mag nooit gecachte antwoorden van Tenant B ontvangen, zeker niet als de LLM tenant-specifieke systeempromptinstructies heeft gekregen.
Gevoelige data. Als queries PII bevatten — namen, e-mailadressen, rekeningnummers — sla de querytekst dan niet letterlijk op. Verwijder of maskeer gevoelige tokens voor opslag. De embedding vangt de semantische vraagtype nog steeds, en dat is alles wat de cache nodig heeft.
Cache warmen. Voor voorspelbare FAQ-patronen: warm de cache op bij deployment:
# lib/tasks/llm_cache.rake
namespace :llm_cache do
task warm: :environment do
client = Llm::Client.new(namespace: "support_v4")
faqs = SupportFaq.where(active: true).order(view_count: :desc).limit(200)
faqs.each do |faq|
client.complete(messages: [{ role: "user", content: faq.question }])
print "."
end
puts "\n#{faqs.count} entries opgewarmd in namespace support_v4"
end
end
Voer dit uit als stap in je deploy-pipeline, nadat de namespace-versie omhoog is gegaan en voordat verkeer naar de nieuwe versie stroomt. Combineer dit met LLM-observability om te zien welke queries raken en missen, en bouw een datagedreven warmstrategie.
Veelgestelde vragen
Welke afstandsdrempel moet ik gebruiken voor een Rails LLM semantic cache?
Begin bij 0.12 voor algemene Q&A-toepassingen. Dit komt overeen met queries die dezelfde onderliggende intentie delen en hetzelfde antwoord zouden krijgen van een deskundige. Voor gevoelige domeinen — medisch, juridisch, financieel — gebruik 0.08. Voor grootschalige toepassingen waarbij valse positieven acceptabel zijn, kan je naar 0.15–0.18 gaan. Valideer altijd met een gelabelde testset van echte queries uit jouw domein voordat je het uitrolt.
Werkt Rails LLM semantic caching bij meerturn-gesprekken?
Het werkt, maar de hitrate daalt sterk naarmate de gespreksgeschiedenis groeit. De meest praktische aanpak: cache alleen het laatste gebruikersbericht als sleutel, niet de volledige gesprekscontext. Dit dekt single-turn Q&A effectief en vangt de meest voorkomende cacheerbare patronen in productie. Voor meerturn-gesprekken met lange systeemprompten levert Anthropic’s server-side prompt caching betrouwbaardere besparingen zonder dezelfde precisiecompromissen.
Hoe ga ik om met verouderde gecachte antwoorden?
Gebruik korte TTLs (7–30 dagen afhankelijk van de wijzigbaarheid van de inhoud) gecombineerd met namespace-versiebeheer. Als je onderliggende data of systeemprompt ingrijpend verandert, verhoog dan het versienummer in de namespace (support_v3 → support_v4) en deploy. Oude entries verlopen op hun TTL; nieuw verkeer vult de nieuwe namespace. Probeer niet individuele entries selectief te invalideren — de vector-matchingssemantiek maakt het moeilijk te bepalen welke entries door een datawijziging zijn geraakt.
Welk embedding-model gebruik ik voor de semantic cache?
text-embedding-3-small van OpenAI is de praktische standaard: 1.536 dimensies, goedkoop, snel (80–120ms round-trip) en nauwkeurig voor het Nederlands. Als je app meerdere talen ondersteunt, verwerkt text-embedding-3-large taalkundige gelijkenis beter — het codeert verwante vragen in verschillende talen als dichterbij elkaar. Gebruik geen grote generatieve modellen voor embedding-only workloads; ze zijn ordes van grootte duurder en trager voor een taak waarvoor kleinere gespecialiseerde embedding-modellen al uitstekende nauwkeurigheid halen.
Een semantic cache is een van de hoogste ROI-toevoegingen die je aan een Rails LLM-feature kunt doen zodra het verkeer boven enkele duizenden queries per dag uitkomt. TTB Software bouwt productie-AI-features op Rails — van RAG-pipelines tot multi-agent workflows. Als je LLM-rekening sneller groeit dan je gebruikersbasis, weten wij waar we als eerste moeten kijken.
Related Articles
Rails PDF Genereren: Prawn, Grover en HTML-naar-PDF in Productie
Rails PDF genereren met Prawn, Grover en HTML-naar-PDF via headless Chrome — wanneer wat, productie-setup, achtergron...
Rails ActiveSupport::Notifications: Aangepaste Instrumentatie voor Metrics en Productie-monitoring
Rails ActiveSupport::Notifications vormt de basis voor aangepaste instrumentatie, metrics en APM-integratie. Abonneer...
Rails Error Reporter: Gestructureerde Foutafhandeling Zonder rescue-Spaghetti
Rails Error Reporter centraliseert foutafhandeling in productie met handle, record en report. Stop met rescue-blokken...