Geavanceerde prompt-caching
Op deze pagina
Voorbij automatische caching
U heeft de basis van prompt-caching gezien in Les 3. Daar verscheen caching als een automatisch mechanisme dat u voordelen biedt zonder speciale inspanning, en dat klopt zolang uw applicatie goed geordende verzoeken verzendt. De productierealiteit is rommeliger: meerdere gebruikers raken tegelijkertijd dezelfde API, elk met hun eigen map, documenten en vragen. Het gemeenschappelijke prefix krimpt dan tot bijna niets, en het cache-hitpercentage stort in zonder dat iemand het merkt, aangezien niets kapot gaat—de rekening loopt alleen op.
Multi-user, multi-document, verwerkingspipelines: we pakken deze complexe scenario’s één voor één aan om het cache-hitpercentage te maximaliseren. Het leidende principe past in één zin: caching is niet iets dat u overkomt; het is iets dat u ontwerpt.
Prompt-architectuur om caching te maximaliseren
Caching is van toepassing op het langste gemeenschappelijke prefix across uw verzoeken. Hoe langer en stabieler dit prefix, hoe meer u bespaart. Het praktische gevolg is dat een prompt georganiseerd moet worden van meest stabiel naar meest variabel, als een boek waarvan de eerste pagina’s nooit veranderen en alleen het laatste hoofdstuk bij elke editie wordt herschreven.
Het onderstaande voorbeeld past dit principe toe op een documentanalyse-assistent voor een advocatenkantoor. Drie lagen volgen elkaar op: globale instructies, die bevroren zijn; de kennisbank, die eens per maand wordt herzien; en het dossier en de vraag, die bij elke oproep veranderen.
import openai
client = openai.OpenAI()
# Gelaagde architectuur: van meest stabiel naar meest variabel
# Laag 1: Globale instructies (veranderen nooit)
GLOBAL_INSTRUCTIONS = """
You are a document analysis assistant for a law firm.
Rules:
- Always respond in French
- Cite relevant legal articles
- Structure as: Analysis / Risks / Recommendations
- Be factual and precise
"""
# Laag 2: Kennisbank (verandert zelden)
KNOWLEDGE_BASE = """
[Insert 5,000+ tokens of case law, legal articles,
analysis templates here—this content changes at most once a month]
"""
# Laag 3: Casuscontext (verandert per cliënt)
def build_prompt(case_context: str, question: str) -> str:
return f"""{GLOBAL_INSTRUCTIONS}
{KNOWLEDGE_BASE}
--- Current Case ---
{case_context}
--- Question ---
{question}"""
De klassieke fout is het plaatsen van de cliëntnaam of de datum van vandaag aan het begin van de systeemprompt om deze te “personaliseren”. Een enkel variabel teken op de initiële positie is genoeg om het prefix uniek te maken, waardoor het cache-hitpercentage voor alle daaropvolgende lagen tot nul daalt. Alles wat varieert, moet als laatste komen.
Natuurlijk moet u verifiëren dat de theorie zich vertaalt naar cijfers. De volgende monitor leest input_tokens_details.cached_tokens bij elk antwoord en accumuleert de metingen, waardoor u een bruikbaar gemiddeld percentage krijgt in plaats van een onderbuikgevoel.
class CacheMonitor:
"""Monitort de efficiëntie van prompt-caching."""
def __init__(self):
self.calls: list[dict] = []
def record(self, usage) -> dict:
total_input = usage.input_tokens
cached_tokens = getattr(
usage.input_tokens_details, "cached_tokens", 0
)
rate = cached_tokens / total_input if total_input > 0 else 0
entry = {
"total_input": total_input,
"cached_tokens": cached_tokens,
"cache_rate": rate,
}
self.calls.append(entry)
return entry
@property
def average_rate(self) -> float:
if not self.calls:
return 0.0
return sum(a["cache_rate"] for a in self.calls) / len(self.calls)
def report(self) -> str:
if not self.calls:
return "Geen oproepen."
return (
f"Oproepen: {len(self.calls)} | "
f"Gemiddeld cache-percentage: {self.average_rate:.1%} | "
f"Tokens bespaard: "
f"{sum(a['cached_tokens'] for a in self.calls):,}"
)
monitor = CacheMonitor()
Drie patronen die het verschil maken
Het eerste patroon betreft de verwerkingsvolgorde. Wanneer u een batch heterogene verzoeken verwerkt, wisselt het uitvoeren ervan in aankomstvolgorde de prefixes af en voorkomt het dat de cache warm blijft. Groeperen op gedeelde context lost het probleem op: eerst verzamelen, later uitvoeren, zodat elke groep profiteert van het prefix dat door het eerste verzoek is voorbereid.
from collections import defaultdict
def group_by_context(
requests: list[dict],
) -> dict[str, list[dict]]:
"""Groepeert verzoeken op gemeenschappelijk prefix."""
groups = defaultdict(list)
for request in requests:
# Sleutel = hash van gedeelde context
key = hash(request.get("shared_context", ""))
groups[key].append(request)
return dict(groups)
def process_by_cohort(requests: list[dict]):
"""Verwerkt gegroepeerde verzoeken om caching te maximaliseren."""
groups = group_by_context(requests)
for key, group in groups.items():
# Alle verzoeken in de groep delen hetzelfde prefix
for request in group:
response = client.responses.create(
model="gpt-5.6-terra",
instructions=request["shared_context"],
input=request["question"],
)
monitor.record(response.usage)
Het tweede patroon behandelt koude starts. Het eerste verzoek in een reeks betaalt de volle prijs omdat er nog niets is gecachet; als dat eerste verzoek komt van een echte gebruiker op een maandagochtend om 9 uur, dragen zij de latentie. Een opwarmverzoek dat wordt verzonden voordat de service opent, verschuift die kosten naar waar het niemand hindert. Let op de bewaking aan het begin van de functie: onder de 1.024 tokens is caching niet van toepassing, en voorverwarmen zou pure kostenpost zijn.
def warm_up_cache(system_prompt: str):
"""Verzendt een minimaal verzoek om de cache voor te bereiden."""
if len(system_prompt) // 4 < 1024:
print("Prompt te kort voor caching (< 1.024 tokens)")
return
response = client.responses.create(
model="gpt-5.6-terra",
instructions=system_prompt,
input="Confirm that you are ready.",
max_output_tokens=10,
)
usage = response.usage
print(
f"Cache voorbereid: {usage.input_tokens} input-tokens, "
f"{getattr(usage.input_tokens_details, 'cached_tokens', 0)} gecachet"
)
Het derde patroon maakt cache-invalidatie zichtbaar. Het fixen van een komma in een systeemprompt van 5.000 tokens lijkt triviaal, toch spoelt die komma de cache voor iedereen leeg. Door een vingerafdruk aan de inhoud te koppelen, detecteert u de wijziging bij implementatie in plaats van de volgende dag op de rekening, en kunt u direct volgen met voorverwarmen.
import hashlib
class VersionedPrompt:
"""Beheert prompt-versies om caching te sturen."""
def __init__(self, content: str):
self.content = content
self.version = hashlib.md5(content.encode()).hexdigest()[:8]
def is_same_version(self, other: "VersionedPrompt") -> bool:
return self.version == other.version
# Als de versie verandert, wordt de cache ongeldig verklaard
prompt_v1 = VersionedPrompt("Instructions v1...")
prompt_v2 = VersionedPrompt("Instructions v2 modified...")
if not prompt_v1.is_same_version(prompt_v2):
print("Waarschuwing: prompt gewijzigd, cache wordt ongeldig verklaard")
warm_up_cache(prompt_v2.content)
Wat dit betekent in volume
Neem een realistisch geval van 10.000 oproepen per dag met een systeemprompt van 3.000 tokens. Zonder caching factureert u 10.000 × 3.000, oftewel 30 miljoen input-tokens elke dag. Met een hitpercentage van 80% blijven 6 miljoen tokens tegen de volle prijs en dalen 24 miljoen naar de halve prijs, wat de besparing op input-tokens op ongeveer 40% brengt. Het cijfer lijkt bescheiden ten opzichte van een enkele oproep; over een jaar productie verandert het de kostenstructuur van de applicatie.
Belangrijkste punten
- Structureer uw prompts in lagen van meest stabiel naar meest variabel
- Groepeer verzoeken op gedeelde context om de cache warm te houden
- Warm de cache op voordat het verkeer piekt
- Monitor het cache-percentage met
input_tokens_details.cached_tokens - Versioneer uw prompts om cache-invalidaties te anticiperen