Übersicht
GoModel bringt zwei Response-Cache-Ebenen für Streaming- und Nicht-Streaming-Requests auf folgenden Endpunkten mit:/v1/chat/completions/v1/responses/v1/messages/v1/embeddings/v1/systemone(sowie Kevs/permuteund/separate)
text/event-stream wieder ab. Ein Stream
über 4 MiB erreicht den Client trotzdem vollständig, wird aber nicht gecacht.
Der Exact-Match-Cache liefert byte-identische Responses mit:
/v1/embeddings nimmt nur am exakten Cache teil. Ein Embedding muss genau den
Text repräsentieren, für den es angefordert wurde; den Vektor einer lediglich
ähnlichen Eingabe wiederzugeben, wäre also eine falsche statt einer gleichwertigen
Antwort. Embeddings-Requests werden außerdem nie gestreamt, daher wird nur die
JSON-Response gecacht. Dasselbe gilt für Entscheidungen von
System One: Ein ähnlicher Zustand ist nicht
dieselbe Entscheidung.Exakten Cache aktivieren
Richten Sie das Response-Caching auf Redis aus:REDIS_URLREDIS_KEY_RESPONSESREDIS_TTL_RESPONSES
Semantisches Caching aktivieren
Fügen Sie einensemantic-Block mit einem Embedder-Provider und einem Vector Store
hinzu:
qdrantpgvectorpineconeweaviate
Cache-Control: no-cache oder Cache-Control: no-store, um das Caching pro
Request zu umgehen. Ein Plugin kann eine einzelne
Response auch mit NoStore in seiner Entscheidung aus beiden Ebenen heraushalten;
das nutzt eine Guardrail, die request-spezifische Daten in die Antwort
zurückschreibt, damit der wiederhergestellte Text nie an einen anderen Aufrufer
ausgespielt wird. Ein Request mit background: true auf
/v1/responses umgeht ebenfalls
beide Ebenen: Sein queued-Body enthält eine ID, die zur Response eines einzelnen
Aufrufers gehört.
Das vollständige Design des semantischen Caches und die Speicheroptionen finden Sie
in ADR-0006.
Woraus der Schlüssel des exakten Caches besteht
Der exakte Cache bildet einen Hash über:- den Request-Pfad
- den aufgelösten Workflow-Kontext, der für die Ausführung verwendet wird, konkret Ausführungsmodus, Provider-Typ und aufgelöstes Modell
- die Guardrail-Kette, zu der der Request aufgelöst wird, über die Phasen Prompt, Response und Stream hinweg
- den endgültigen Request-Body
- den effektiven
user_path, nur wennpartition_by_user_pathaktiv ist (siehe unten)
Woraus der Schlüssel des semantischen Caches besteht
Ein semantischer Treffer braucht eine ähnliche letzte Nutzernachricht und eine exakte Übereinstimmung bei allem anderen:- Request-Pfad, aufgelöster Provider und aufgelöstes Modell, Guardrail-Kette und Embedder
- die früheren Gesprächsrunden sowie alle Nicht-Text-Teile der letzten Nutzernachricht
- alle anderen Felder der obersten Ebene des Requests, etwa
temperature,seed,stop,n,tools,tool_choice,response_format,text,reasoning_effort,thinkingodersystem, sowie jedes Feld, das GoModel nicht kennt - ob der Request streamt;
stream_optionszählt nur, wennstreamauftruesteht
user,
metadata, safety_identifier, prompt_cache_key und
prompt_cache_retention. Bei /v1/responses zählen sie, weil die Response sie
an den Aufrufer zurückgibt. Mit exclude_system_prompt: true bleiben auch
System-Nachrichten und ein system auf oberster Ebene außen vor;
instructions der Responses API zählen immer.
Planung des Provider-Prompt-Caches
Nachdem das Routing den konkreten Provider und das Modell aufgelöst hat, fügt GoModel einen Cache-Plan hinzu, wenn das stabile Präfix die Mindestgröße dieses Providers erreicht und der Client nicht bereits selbst eine Cache-Direktive mitgeliefert hat:- OpenAI erhält einen stabilen
prompt_cache_key; Modelle, die explizites Caching unterstützen, erhalten zusätzlich einen Breakpoint und den expliziten Cache-Modus. - Anthropic erhält automatisches ephemeres Caching auf oberster Ebene.
- Amazon Bedrock Converse erhält einen Cache-Point nach dem stabilen Präfix.
- Natives Gemini AI Studio erstellt ein Cached-Content-Objekt mit fünf Minuten Lebensdauer und verwendet es wieder; gleichzeitige Erstellungen werden pro Präfix und stabilem Zugangsdatum zusammengeführt.
true) bei, und ein ungültiger Wert
erzeugt beim Start eine Warnung.
Verhalten von user_path
Standardmäßig ist user_path in keiner der beiden Cache-Ebenen Teil des
Cache-Schlüssels.
Das ist beabsichtigt. Haben zwei Requests am Ende denselben Pfad, denselben
aufgelösten Workflow und denselben endgültigen Request-Body, können sie sich
denselben Eintrag teilen, selbst wenn sie von unterschiedlichen
user_path-Werten stammen; im semantischen Cache gilt das auch für ähnliche
Prompts. Das ergibt die beste Trefferquote, bedeutet aber auch, dass ein Tenant
eine für einen anderen Tenant gecachte Response erhalten kann.
Cache nach user_path partitionieren
Aktivieren Sie die Partitionierung, wenn Aufrufer nicht die gecachten Responses
der anderen erhalten dürfen, zum Beispiel wenn an einen user_path gebundene
API-Keys unterschiedlichen Tenants gehören:
RESPONSE_CACHE_PARTITION_BY_USER_PATH=true.
Die Einstellung gilt für jede Cache-Ebene, die die oben genannten Endpunkte
nutzen (Embeddings und System One nutzen nur den exakten Cache), mit und ohne
Streaming:
- Requests mit unterschiedlichem effektivem
user_pathteilen nie einen Eintrag. Im exakten Cache warten gleichzeitige identische Misses nur auf Requests desselben Pfads. - Pfade müssen exakt übereinstimmen.
/team/alphaverwendet keine Einträge von/teamoder/team/alpha/bob. - Requests ohne
user_pathbilden eine eigene Partition, getrennt von/. - Jeder Pfad bezahlt seinen ersten Request selbst, die Trefferquote sinkt also, wenn Tenants dieselben Prompts senden.
ttl: 0 laufen nie ab; leeren Sie diese.
Andere Wege, den Cache einzugrenzen
Wenn Sie nur unterschiedliches Cache-Verhalten pro Scope brauchen, aber keine Isolation:- den Cache in einem Scoped Workflow deaktivieren
- unterschiedliche Scoped Workflows für unterschiedliche
user_path-Werte verwenden - scope-spezifischen Kontext einfügen, sodass sich der endgültige Request-Body unterscheidet
Über Failover bediente Responses werden nicht gecacht
Wird ein Request von einem Failover-Ziel beantwortet statt von dem Ziel, das das Routing zuerst gewählt hat, wird die Response nicht gespeichert. Der Schlüssel des exakten Caches wird aus der Auflösung vor dem Failover gebildet; die Antwort des Ersatzziels zu speichern, würde sie also unter dem Schlüssel des primären Ziels ausliefern, sobald dieses wieder verfügbar ist. Die praktische Folge: Ein virtuelles Modell, dessen erstes Ziel dauerhaft ausfällt, sammelt so lange keine Cache-Einträge mehr an, wie der Ausfall andauert — jeder Request mit Miss wechselt per Failover und wird frisch bedient, und nichts davon wird gespeichert. Einträge, die vor dem Ausfall geschrieben wurden, werden weiterhin ausgeliefert, bis ihre TTL abläuft: Der Lookup läuft vor der Weiterleitung, sodass ein Hit zurückgegeben wird, ohne eines der Ziele zu berühren. Wenn ein Ziel für längere Zeit nicht verfügbar sein wird, ändern Sie die Reihenfolge der Kette (oder richten Sie das virtuelle Modell auf ein funktionierendes Ziel aus), damit die Responses, die es beantworten, wieder cachebar sind. Retries innerhalb eines Ziels sind nicht betroffen: Nur eine Response, die erzeugt wurde, nachdem der Durchlauf zu einem anderen Ziel gewechselt ist, wird beiden Cache-Ebenen vorenthalten.Cache-Analysen
Sind Response-Caching und Nutzungserfassung aktiviert, stellt die Admin API eine Übersicht nur für gecachte Requests bereit unter:user_path des
Aufrufers und einem cache_type von exact oder semantic. Die Nutzungs-Endpunkte
(/admin/usage/* und /v1/usage) lassen sie standardmäßig weg, damit Summen und
Kosten die Provider-Ausgaben abbilden; übergeben Sie cache_mode=all, um sie
einzuschließen, oder cache_mode=cached, um nur die Hits zu sehen.
/admin/usage/sessions ist die Ausnahme: Die Request- und Token-Summen pro Session
enthalten immer Cache-Hits, während die Kostenfelder dort nur Provider-Kosten
abbilden.