> ## Documentation Index > Fetch the complete documentation index at: https://docs.apimart.ai/llms.txt > Use this file to discover all available pages before exploring further. # Leitfaden zum Gemini-Kontext-Caching > Gemini-Kontext-Caches (Context Cache) über die OpenAI-kompatible Chat Completions API oder die native Gemini API erstellen und wiederverwenden. Mit cache_control stabile Präfixe zwischenspeichern und Token-Kosten bei wiederholten langen Inhalten senken. In diesem Leitfaden erfahren Sie, wie Sie Gemini-Kontext-Caches (Context Cache) über die OpenAI-kompatible Chat Completions API oder die native Gemini API erstellen und wiederverwenden. Vorbereitung: ```bash theme={null} export API_KEY="IHR_API_SCHLUESSEL" ``` Die Beispiele in diesem Leitfaden verwenden `gemini-3.6-flash`. Ob andere Modelle Context Cache unterstützen, erfahren Sie in der Modelldokumentation und auf der Preisseite der Plattform. ## Anwendungsfälle Wenn mehrere Anfragen wiederholt dieselben umfangreichen Inhalte enthalten, können Sie den stabilen Präfix zwischenspeichern. Beispiele hierfür sind: * Ein sehr langer System-Prompt * Eine feste Wissensdatenbank oder Produktdokumentation * Ein stabiler Nachrichtenverlauf über mehrere Gesprächsrunden hinweg * Wiederverwendete Tool-Definitionen und Anweisungen Context Cache eignet sich für Anfragen, bei denen der Inhalt am Anfang unverändert bleibt, während sich die abschließende Frage fortlaufend ändert. ## Grundlegende Verwendung Fügen Sie `cache_control` zum Inhaltsblock der letzten Nachricht im stabilen Präfix hinzu: ```json theme={null} { "type": "text", "text": "Dies ist der letzte Abschnitt des stabilen Präfixes", "cache_control": { "type": "ephemeral", "ttl": "5m" } } ``` Unterstützte TTL-Werte: | TTL | Bedeutung | | ---- | --------------------------- | | `5m` | 5 Minuten zwischenspeichern | | `1h` | 1 Stunde zwischenspeichern | Wenn `ttl` weggelassen wird, gilt standardmäßig `5m`. ## Nachrichtenstruktur Wir empfehlen die folgende Struktur: ```text theme={null} system → Stabiler Langtext oder Nachrichtenverlauf → Grenze des stabilen Präfixes mit cache_control → Aktuelle Benutzerfrage (nicht zwischengespeichert) ``` Die Nachricht mit `cache_control` und alle vorangehenden Nachrichten bilden den Cache-Präfix. Danach muss mindestens eine aktuelle Nachricht folgen. ## Beispiel für eine OpenAI-kompatible Anfrage ```bash theme={null} curl "https://api.apimart.ai/v1/chat/completions" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gemini-3.6-flash", "stream": false, "messages": [ { "role": "system", "content": "Beantworten Sie Fragen ausschließlich anhand des bereitgestellten Referenzmaterials." }, { "role": "user", "content": "Fügen Sie hier das umfangreiche Referenzmaterial ein, das wiederverwendet werden soll..." }, { "role": "assistant", "content": [ { "type": "text", "text": "Ich habe das obige Referenzmaterial gelesen und verstanden.", "cache_control": { "type": "ephemeral", "ttl": "5m" } } ] }, { "role": "user", "content": "Fassen Sie die drei wichtigsten Punkte des Referenzmaterials zusammen." } ] }' ``` Bei der ersten Anfrage versucht das System, einen Cache zu erstellen, und verwendet den neuen Cache direkt für diese Anfrage. Sie müssen keinen separaten Endpunkt zur Cache-Erstellung aufrufen. `cache_control` legt sowohl die Cache-Grenze als auch die Cache-Gültigkeitsdauer fest. ## Beispiel für eine native Gemini-Anfrage Beim nativen Gemini-Endpunkt `generateContent` können Sie `cache_control` ebenfalls in `contents[].parts[]` einfügen: ```bash theme={null} curl "https://api.apimart.ai/v1beta/models/gemini-3.6-flash:generateContent" \ -H "x-goog-api-key: $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "systemInstruction": { "parts": [ { "text": "Beantworten Sie Fragen ausschließlich anhand des bereitgestellten Referenzmaterials." } ] }, "contents": [ { "role": "user", "parts": [ { "text": "Fügen Sie hier das umfangreiche Referenzmaterial ein, das wiederverwendet werden soll..." } ] }, { "role": "model", "parts": [ { "text": "Ich habe das obige Referenzmaterial gelesen und verstanden.", "cache_control": { "type": "ephemeral", "ttl": "5m" } } ] }, { "role": "user", "parts": [ { "text": "Fassen Sie die drei wichtigsten Punkte des Referenzmaterials zusammen." } ] } ] }' ``` `cache_control` ist eine Plattformerweiterung des Gemini-Anfrageformats. Nachdem die Plattform die Grenze erkannt hat, entfernt sie dieses Feld vor der Weiterleitung und erstellt oder verwendet automatisch zwischengespeicherte Inhalte (`cachedContent`). Der Streaming-Endpunkt verwendet denselben Anfragekörper. Sie müssen lediglich die URL wie folgt ändern: ```bash theme={null} curl -N "https://api.apimart.ai/v1beta/models/gemini-3.6-flash:streamGenerateContent?alt=sse" \ -H "x-goog-api-key: $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "contents": [ { "role": "user", "parts": [ { "text": "Fügen Sie hier das umfangreiche Referenzmaterial ein, das wiederverwendet werden soll...", "cache_control": { "type": "ephemeral", "ttl": "5m" } } ] }, { "role": "user", "parts": [ { "text": "Fassen Sie die drei wichtigsten Punkte des Referenzmaterials zusammen." } ] } ] }' ``` Lassen Sie bei der Wiederverwendung `systemInstruction`, die `contents` vor der Grenze, die TTL und tools unverändert. Ändern Sie nur die aktuellen Inhalte nach der Grenze. ## Ablauf der Erstellung und Wiederverwendung Wenn Sie zum ersten Mal eine Anfrage mit `cache_control` senden: ```text theme={null} Stabilen Präfix erkennen → Context Cache erstellen → Neuen Cache in der aktuellen Anfrage referenzieren → Modellergebnis zurückgeben ``` Wenn Sie denselben stabilen Präfix erneut senden: ```text theme={null} Identischen stabilen Präfix erkennen → Nicht abgelaufenen Context Cache wiederverwenden → Nur die aktuellen Inhalte senden → Modellergebnis zurückgeben ``` Daher kann bereits die erste Anfrage eine hohe Anzahl an Cache-Treffer-Tokens zurückgeben. Das ist normal und erfordert keine separate Aufwärmanfrage. ## Cache wiederverwenden Lassen Sie bei nachfolgenden Anfragen Folgendes unverändert: * Das Modell * Alle Nachrichten vor `cache_control` * `cache_control.ttl` * Tool-Definitionen (falls Sie tools verwenden) * `systemInstruction` in nativen Gemini-Anfragen Ändern Sie nur die aktuelle Frage nach der Grenze: ```json theme={null} { "role": "user", "content": "Welche Risiken werden im Referenzmaterial erwähnt?" } ``` Solange der stabile Präfix identisch und der Cache nicht abgelaufen ist, verwendet das System den bestehenden Cache wieder. Die folgenden Änderungen erzeugen einen anderen Cache: * Text oder Nachrichtenreihenfolge innerhalb des stabilen Präfixes ändern * Das Modell wechseln * `5m` in `1h` ändern * tools oder Definitionen von Tool-Parametern ändern * Einen anderen API-Benutzer oder Kanal verwenden ## Python-Beispiel ```python theme={null} from openai import OpenAI client = OpenAI( api_key="YOUR_API_KEY", base_url="https://api.apimart.ai/v1", ) stable_messages = [ { "role": "system", "content": "Beantworten Sie Fragen ausschließlich anhand des bereitgestellten Referenzmaterials.", }, { "role": "user", "content": "Fügen Sie hier das umfangreiche Referenzmaterial ein, das wiederverwendet werden soll...", }, { "role": "assistant", "content": [ { "type": "text", "text": "Ich habe das obige Referenzmaterial gelesen und verstanden.", "cache_control": { "type": "ephemeral", "ttl": "5m", }, } ], }, ] response = client.chat.completions.create( model="gemini-3.6-flash", messages=[ *stable_messages, { "role": "user", "content": "Fassen Sie die drei wichtigsten Punkte des Referenzmaterials zusammen.", }, ], ) print(response.choices[0].message.content) print(response.usage) ``` Verwenden Sie für nachfolgende Anfragen dieselben `stable_messages` und ersetzen Sie nur die letzte Benutzernachricht. ## Cache-Treffer überprüfen ### OpenAI-kompatible Antwort Prüfen Sie die folgenden Felder in der Antwort: ```json theme={null} { "usage": { "prompt_tokens": 14430, "prompt_tokens_details": { "cached_tokens": 14420, "cache_write_tokens": 0 } } } ``` Feldbeschreibungen: | Feld | Bedeutung | | -------------------- | --------------------------------------------------------- | | `prompt_tokens` | Alle Eingabe-Tokens dieser Anfrage | | `cached_tokens` | Bei dieser Anfrage aus dem Cache gelesene Eingabe-Tokens | | `cache_write_tokens` | In den Cache geschriebene Tokens; der Wert `0` ist normal | Auch die erste Anfrage kann einen hohen Wert für `cached_tokens` aufweisen, da das System einen Cache erstellen und ihn im selben Modellaufruf referenzieren kann. ### Native Gemini-Antwort Prüfen Sie `usageMetadata.cachedContentTokenCount` in der Antwort: ```json theme={null} { "usageMetadata": { "promptTokenCount": 13926, "cachedContentTokenCount": 13916, "totalTokenCount": 13954 } } ``` Feldbeschreibungen: | Feld | Bedeutung | | ------------------------- | -------------------------------------------------------- | | `promptTokenCount` | Alle Eingabe-Tokens dieser Anfrage | | `cachedContentTokenCount` | Bei dieser Anfrage aus dem Cache gelesene Eingabe-Tokens | | `totalTokenCount` | Gesamte Eingabe- und Ausgabe-Tokens dieser Anfrage | `streamGenerateContent` gibt dieselben `usageMetadata` in einem SSE-Antwort-Frame zurück. Der Client sollte den Frame mit diesem Feld lesen und nicht nur den ersten Text-Frame prüfen. ## Empfehlungen 1. Speichern Sie nur lange Inhalte zwischen, die tatsächlich stabil sind und mehrfach wiederverwendet werden. 2. Platzieren Sie die Frage, die sich mit jeder Anfrage ändert, nach der `cache_control`-Grenze. 3. Nehmen Sie keine Zeitstempel, zufälligen IDs oder dynamischen Benutzerinformationen in den stabilen Präfix auf. 4. Verwenden Sie `5m`, wenn Sie innerhalb kurzer Zeit wiederholte Aufrufe erwarten. 5. Verwenden Sie `1h`, wenn Sie ein längeres Wiederverwendungsfenster benötigen. 6. Wenn der Präfix zu kurz ist, das Modell Caching nicht unterstützt oder der Cache vorübergehend nicht verfügbar ist, kann die Anfrage automatisch im Standardmodus ausgeführt werden. 7. Bei nativen Gemini-Anfragen muss die Cache-Grenze in `contents[].parts[]` und nicht in `systemInstruction` platziert werden. ## Häufig gestellte Fragen Ja. `generateContent` und `streamGenerateContent` verwenden dieselbe `cache_control`-Struktur. Die Grenze muss in `contents[].parts[]` platziert werden, und nach dem Inhaltselement mit der Grenze muss mindestens ein aktuelles Inhaltselement verbleiben. Wenn die Anfrage ausdrücklich den Namen einer nativen `cachedContent`-Ressource angibt, verwendet die Plattform vorrangig die vom Benutzer angegebene Ressource und erstellt nicht automatisch einen Cache. Häufige Ursachen sind: * Der stabile Präfix stimmt nicht exakt mit der vorherigen Anfrage überein * Die TTL ist abgelaufen * Das Modell oder die tools wurden geändert * Der zwischengespeicherte Inhalt erreicht nicht die vom Modell verlangte Mindestanzahl an Tokens * `cache_control` wurde in der letzten Nachricht platziert, sodass keine aktuelle Frage danach verbleibt Dies wird nicht empfohlen. Die letzte Nachricht ist normalerweise die aktuelle Frage und sollte nicht zwischengespeichert werden. Wenn nach der Grenze keine aktuelle Nachricht folgt, wird die Anfrage im Standardmodus ausgeführt. Nein. Derzeit werden nur `5m` und `1h` unterstützt. Jeder andere Wert führt zu HTTP 400. Ja, aber alle Grenzen müssen dieselbe TTL verwenden, und das System verwendet die letzte Grenze. Für eine übersichtlichere Struktur wird im Allgemeinen nur eine Grenze pro Anfrage empfohlen. In der Regel nicht. Wenn die Bedingungen zum Erstellen oder Wiederverwenden eines Caches nicht erfüllt sind, sendet das System automatisch eine Standardanfrage. Ausnahmen sind Parameterfehler wie eine ungültige TTL oder gemischte TTL-Werte. Die Anfrage wird automatisch im Standardmodus ausgeführt, ohne einen expliziten Cache zu erstellen oder Cache-Speichergebühren zu verursachen. Reguläre Ein- und Ausgaben sowie eventuell vorhandenes implizites Caching werden weiterhin nach den bestehenden Regeln des Modells abgerechnet. Dies ist das erwartete Verhalten beim Gemini-Kontext-Caching. Die Kosten für die Cache-Erstellung werden als separate Cache-Speichergebühr erfasst; die Menge der in den Cache geschriebenen Daten wird nicht wie bei OpenAI oder Claude mit `cache_write_tokens` angegeben. Nicht unbedingt. Das System kann auch implizite Cache-Treffer erzeugen. Reguläre Benutzer können anhand der Cache-Lese-Tokens erkennen, ob diese Anfrage vom Lesen aus dem Cache profitiert hat. Um die Gebühren für die explizite Cache-Erstellung zu prüfen, sehen Sie in den Nutzungsprotokollen der Plattform nach Einträgen für Context Cache storage. Beim Erstellen eines Caches kann eine einmalige Cache-Speichergebühr anfallen. Bei Verwendung des Caches werden Treffer-Tokens zum Cache-Lesepreis abgerechnet. Die genauen Preise finden Sie in den auf der Plattform angezeigten Modellpreisen.