RUBY ON RAILS · 19 MIN READ ·

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.

Rails LLM Semantic Cache: AI API-kosten verlagen met pgvector

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:

  1. Genereer een embedding voor de nieuwe query — één kleine API-aanroep, doorgaans 100× goedkoper dan een volledige LLM-completion
  2. Zoek in de cache naar opgeslagen embeddings binnen een cosinus-afstandsdrempel
  3. Als er een voldoende gelijkaardige match is, geef het gecachte antwoord terug
  4. 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.hour of 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.

#rails-llm-semantic-cache #semantic-caching-rails #rails-openai-cost-reduction #pgvector-rails-embeddings #rails-ai-caching #llm-cost-optimization-rails

Related Articles

Laatste sectie. Bel dan alsjeblieft.

Het is een telefoongesprek. Erger dan dat kan het niet worden.

Geen discovery-deck. Geen 45-minuten "kwalificatiegesprek." 30 minuten, jouw probleem, mijn mening. Als we een fit zijn weet je dat in minuut 12.

Directe lijn — Roger neemt zelf op
+31 6 5123 6132
Ma–vr, 09:00–18:00 CET · Nu beschikbaar

OF
info@ttb.software