Prompt caching vuonna 2026: leikkaa Claude- ja GPT-API:n kustannuksia 90 %

Päivitetty: 9. kesäkuuta 2026

Prompt caching on yksittäin tehokkain vipu LLM-API-kustannusten leikkaamiseen vuonna 2026: kun palveluntarjoaja tallentaa kehotteesi pitkän, toistuvan prefiksin (järjestelmäkehotteet, työkalumääritykset, RAG-konteksti) välimuistiin, maksat lukuvaiheessa noin 10 % tavallisesta input-tokenien hinnasta. Käytännössä Anthropicin Claude- ja OpenAI:n GPT-mallien tuotantoasiakkaat saavuttavat 70–90 % syötteenpuoleisia kustannussäästöjä, kun toistuva konteksti ylittää 1 024–4 096 tokenia ja prefiksi pysyy tavu kerrallaan samana. Tämä opas käy läpi sekä toimittajakohtaiset toteutukset että ne hiljaiset invalidointiansat, jotka tekevät cache-osumista nollia ilman virheilmoituksia.

• Prompt caching toimii prefiksien täsmäyksellä: yksikin muuttunut tavu missä tahansa prefiksissä mitätöi kaiken sen jälkeen, myös datetime.now() järjestelmäkehotteessa.
• Claude 4.x -mallit vaativat vähintään 1 024–4 096 tokenia välimuistitettavalle prefiksille; alle jäävät kutsut eivät tallennu välimuistiin ilman virheilmoitusta.
• OpenAI:n GPT-4o-mallit (joulukuu 2025 ja uudemmat) tarjoavat automaattisen promptin välimuistituksen ilman erityisparametria yli 1 024 tokenin syötteille.
• Cache-osumat näkyvät vastauksen usage.cache_read_input_tokens-kentässä; nollatulos viittaa hiljaiseen invalidointiin, ei API-virheeseen.
• 5-minuutin TTL maksaa 1.25× kirjoituskustannuksen, 1-tunnin TTL maksaa 2×. Laskelma kannattaa, kun samaa prefiksiä luetaan vähintään 2–3 kertaa elinkaaressa.
• Cache-luotettava arkkitehtuuri vaatii deterministisen JSON-serialisoinnin, jäädytetyt työkalumääritykset ja muuttuvan kontekstin sijoittamisen vasta viimeisen cache_control-pisteen jälkeen.

Mitä prompt caching on ja milloin se kannattaa?

Prompt caching tarkoittaa, että LLM-palveluntarjoaja tallentaa kehotteen alkuosan (prefiksin) sisäisen tilan välimuistiin ja palauttaa sen seuraavissa kutsuissa ilman täyttä uudelleenlaskentaa. Anthropicin Claude prompt caching -dokumentaatio kuvaa mekanismin prefiksien täsmäykseksi: API laskee tarkat tavut kunkin cache_control-pisteen kohdalla ja käyttää niitä avaimena. Jos kaksi peräkkäistä kutsua ovat identtisiä ensimmäisen 10 000 tokenin osalta, jälkimmäinen lukee tämän osan välimuistista noin 10 %:n hinnalla.

Honestly, kolme tilannetta toistuvat tuotannossa kerta toisensa jälkeen: (1) suuri järjestelmäkehote tai työkalumäärittelysarja, jota käytetään monessa istunnossa, (2) RAG-pipelinen retrieval-konteksti, jossa samaa dokumenttijoukkoa kysytään eri kysymyksillä saman 5 minuutin ikkunan aikana, ja (3) monivuoroinen agenttisessio, jossa keskustelu kasvaa, mutta historian alkupää ei muutu. Jos kehotteesi alkuosa muuttuu joka pyynnössä (vaikkapa aikaleimalla tai pyyntö-ID:llä), caching ei toimi lainkaan.

On hyvä ymmärtää myös toinen suunta: missä caching ei kannata. Lyhyet luokittelu- tai poimintakutsut, joissa koko syöte mahtuu 500 tokeniin, jäävät joka tapauksessa alle välimuistituksen minimirajan eivätkä hyödy. Samoin yksittäiset analyysikutsut ilman toistoa: jos ajat yhden raportin kerran kuukaudessa, kirjoituskustannuksen (1.25×) maksaminen ilman lukuja on tappiollista. Olen kirjoittanut tästä lisää LLM-sovellusten arviointioppaassa, jossa korostan mittaamista ennen optimointia.

Claude API:n prompt caching käytännössä

Claude tukee promptin välimuistitusta kaikilla Claude 4.x -malleilla (Opus 4.6/4.7/4.8, Sonnet 4.6, Haiku 4.5). Käyttö tapahtuu lisäämällä cache_control: {"type": "ephemeral"} sille sisältölohkolle, jonka kohdalla haluat välimuistin rajan. Renderöintijärjestys API:ssa on aina tools → system → messages, joten merkitsemällä viimeisen system-lohkon välimuistitettavaksi tallennat sekä työkalut että system-promptin yhdessä.

from anthropic import Anthropic

client = Anthropic()

LARGE_SYSTEM_PROMPT = open("agent_instructions.md").read()  # ~8 000 tokenia

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    system=[{
        "type": "text",
        "text": LARGE_SYSTEM_PROMPT,
        "cache_control": {"type": "ephemeral"},
    }],
    messages=[{"role": "user", "content": "Yhteenveto kvartaaliraportista."}],
)

print(f"Kirjoitettu välimuistiin: {response.usage.cache_creation_input_tokens}")
print(f"Luettu välimuistista:    {response.usage.cache_read_input_tokens}")
print(f"Tavallisia input-tokeneja: {response.usage.input_tokens}")

Ensimmäisellä kutsulla cache_creation_input_tokens on noin 8 000 ja cache_read_input_tokens on nolla. Toisella saman 5 minuutin sisällä tehdyllä kutsulla luvut kääntyvät päinvastoin: kirjoitus on nolla, luku noin 8 000. Tämän jälkeen maksat järjestelmäkehotteesta vain ~10 % normaalihinnasta. Opus 4.8:n tapauksessa se on 5,00 $/M sijaan 0,50 $/M.

TTL-vaihtoehdot ja break-even-piste

Claude tarjoaa kaksi TTL-vaihtoehtoa: oletus 5 minuuttia (kirjoitushinta 1.25× perussyötteen hinta) ja yhden tunnin TTL {"type": "ephemeral", "ttl": "1h"} (kirjoitushinta 2×). Lyhyemmän TTL:n break-even-piste on kaksi kutsua: 1.25× + 0.1× = 1.35× vs. 2× kahdesta ilman cachea. Tunnin TTL vaatii vähintään kolme kutsua kannattaakseen. Käytännössä valitsen lyhyen TTL:n interaktiivisille agenteille ja pitkän TTL:n eräajopipelineille, joissa pyyntöjen välit voivat venyä useaan kymmeneen minuuttiin.

Vähintään 1 024–4 096 tokenin minimi

OpenAI:n GPT-mallien automaattinen välimuistitus

OpenAI otti käyttöön automaattisen prompt cachingin lokakuussa 2024 ja laajensi sitä vuoden 2025 aikana kattamaan kaikki uudemmat GPT-4o- ja o1/o3-mallit. Toisin kuin Claudessa, OpenAI:n välimuistitus ei vaadi cache_control-parametria. Se aktivoituu automaattisesti, kun syöte ylittää 1 024 tokenia. Cache-osumat näkyvät vastauksen usage.prompt_tokens_details.cached_tokens-kentässä, ja säästö on noin 50 % välimuistitetuista tokeneista (ei 90 % kuten Claudessa).

from openai import OpenAI

client = OpenAI()

response = client.chat.completions.create(
    model="gpt-4o-2024-11-20",
    messages=[
        {"role": "system", "content": LARGE_SYSTEM_PROMPT},  # > 1024 tokenia
        {"role": "user", "content": "Mikä on vuoden 2025 liikevaihto?"},
    ],
)

cached = response.usage.prompt_tokens_details.cached_tokens
print(f"Välimuistista luettu: {cached} tokenia")

Automaattisuus on mukavaa, mutta menetät tarkkuuden: et voi valita välimuistituspisteitä etkä saa pitkää TTL:ää. OpenAI:n välimuistin TTL on 5–10 minuuttia ruuhka-aikana ja voi pidentyä tuntiin matalan käytön aikana. Dokumentaation mukainen takuu on vain "best effort". Tämä tekee OpenAI:n cachingista vähemmän ennustettavaa eräajoissa.

Kun valita Claude vs. OpenAI cachingin perusteella?

Ominaisuus	Anthropic Claude	OpenAI GPT-4o	Google Gemini
Aktivointitapa	Eksplisiittinen cache_control	Automaattinen	Eksplisiittinen CachedContent
Lukuhinta välimuistista	~10 % perushinta	~50 % perushinta	~25 % perushinta
Minimitokenit	1 024 (Sonnet/Haiku) tai 4 096 (Opus)	1 024	32 768
Oletus-TTL	5 min (myös 1 h)	5–60 min, ei takuita	1 h (säädettävissä)
Kirjoituskustannus	1.25× (5 min) / 2× (1 h)	Ei lisämaksua	Tuntimaksu tallennuksesta
Hallinnan tarkkuus	4 cache_control-pistettä	Ei manuaalista hallintaa	Eksplisiittinen objekti

Google Geminin Context Caching ja erot Claudeen

Google Geminin Context Caching on filosofialtaan erilainen: luot CachedContent-objektin nimenomaisella API-kutsulla, ja Google laskuttaa sinulta sekä kirjoituksen että jatkuvan tuntimaksun niin kauan kuin objekti on olemassa. Vähimmäissyöte on huomattavasti suurempi (32 768 tokenia), mikä tekee Geminin cachingista käytännössä vain pitkän kontekstin (esim. koko PDF tai videosegmentti) optimointityökaluksi. Pienemmille agenttisovelluksille Claude tai GPT ovat sopivampia.

Geminin etu on hallinnan tarkkuus: voit luoda välimuistin, käyttää sitä satoja kertoja, poistaa sen ja olla maksamatta enää säilytyksestä. Claude-mallien efemerinen välimuisti taas vanhenee passiivisesti, mikä on yksinkertaisempaa, mutta vähemmän ennustettavaa kustannuksiltaan pitkillä ikkunoilla.

Hiljaiset invalidoijat: miksi cache-hit-rate on nolla

Yleisin ongelma, jonka kohtaan tiimien koodikatselmuksissa, on tämä: kaikki näyttää oikein, cache_control on paikallaan, mutta cache_read_input_tokens on aina nolla. Syy on lähes aina hiljainen invalidoija, eli jokin, joka muuttaa prefiksin tavuja huomaamatta. Tässä top-5-listani tuotantokoodeista:

1. Aikaleima järjestelmäkehotteessa. system_prompt = f"Tämänhetkinen aika: {datetime.now()}. Sinä olet..." on tuhoisaa. Aika muuttuu joka pyynnössä, ja koko prefiksi mitätöityy. Sijoita aikaleima viimeiseen user-viestiin, ei system-promptiin.
2. Ei-deterministinen JSON-serialisointi. json.dumps(data) Pythonissa ei takaa avainjärjestystä Python 3.7+:ssa dictien osalta, mutta jos data tulee setistä tai DB-kyselystä, järjestys voi vaihtua. Käytä aina json.dumps(data, sort_keys=True).
3. Työkalumäärittelyjen järjestys muuttuu. Jos rakennat tools-listan dynaamisesti käyttäjäoikeuksien perusteella ja listan järjestys vaihtelee, jokainen permutaatio on eri välimuisti.
4. Pyyntö-ID tai sessio-ID prefiksin alussa. Yleinen virhe lokituksen yhteydessä: system = f"Session: {session_id}\n{INSTRUCTIONS}". Sijoita ID:t metadata-kenttiin tai viimeiseen viestiin.
5. Mallin tai betan vaihto. Välimuistit ovat mallikohtaisia: claude-opus-4-7 ja claude-opus-4-8 eivät jaa välimuistia. Sama koskee beta-headerien lisäämistä: uusi header tarkoittaa uutta välimuistia.

Kustannuslaskelma: milloin caching maksaa itsensä takaisin?

Yksinkertainen break-even-laskenta Claude Opus 4.8:lle ($5/M input, $25/M output):

• Skenaario: 10 000 tokenin järjestelmäkehote, 500 user-viestiä päivässä.
• Ilman cachea: 10 000 × 500 = 5M input-tokenia/päivä = $25/päivä = $750/kk.
• Cachella (90 % osumat 5 min TTL:llä): kirjoitukset ~5 % kutsuista × 1.25× hinta + luvut 95 % × 0.1× hinta = $0.16 + $1.19 = $1.35/päivä = $40.50/kk.
• Säästö: ~95 % syötteenpuoleisista kustannuksista, yli $700/kk.

Säästö skaalautuu lineaarisesti volyymin mukaan. Olemme nähneet yhden asiakkaan multi-agent-järjestelmässä, jota käsittelin LangGraph- ja CrewAI-oppaassa, kuukausittaisten LLM-kustannusten putoavan 12 000 dollarista 1 800 dollariin pelkän järkevän cachingin avulla, ilman mallin vaihtoa tai promptin lyhentämistä.

Arkkitehtuuri pitkäkestoisille agenteille

Pitkäkestoisissa agenteissa, joissa keskustelu kasvaa kymmeniä tai satoja vuoroja, cachen säilyttäminen vaatii suunnittelua. Kolme käytännön sääntöä:

1. Jäädytä alkuosa. System-prompt ja työkalumäärittelyt eivät saa muuttua session aikana. Jos tarvitset dynaamista kontekstia (esim. käyttäjäpreferenssit), injektoi se ensimmäiseen user-viestiin, ei system-promptiin. Anthropicin virallinen ohje työkalujen käyttöön cachen kanssa korostaa samaa: työkalujen lisääminen tai poistaminen agenttisession aikana mitätöi cachen.

2. Cache_control viimeiselle stabiilille rajalle. Käytät enintään 4 cache_control-pistettä per pyyntö. Jaa niitä strategisesti: yksi system-promptin loppuun, yksi RAG-kontekstin loppuun, yksi keskustelun viimeisimmän vakaan vaiheen loppuun. Viimeinen user-viesti ei saa cache_control-merkkiä, sillä se on muuttuva osa.

3. Käytä alaagenteille halvempaa mallia. Yksi parhaista mallinvaihtokuvioista on pää-agentin pitäminen Opus 4.8:lla ja työn delegointi Haiku 4.5 -alaagenteille (RAG-haut, työkalukutsujen valmistelu). Koska välimuistit ovat mallikohtaisia, alaagenttien välimuistit pysyvät erillisinä, eikä pää-agentin koko 50 000 tokenin konteksti mitätöidy aina kun alaagentti aktivoituu. Kytkös tuotantovalmiiseen RAG-pipelineen on tässä luonteva.

Mittaus, monitorointi ja CI-validointi

Cachen toimivuus ei näy logissa ilman tietoista mittausta. Suosittelen kolmea konkreettista käytäntöä, jotka olen ottanut käyttöön jokaisessa projektissa viimeisen kahden vuoden aikana:

Metriikan keräys vastauksista. Lokita jokaisesta API-vastauksesta cache_creation_input_tokens, cache_read_input_tokens ja input_tokens Prometheus-, OpenTelemetry- tai Datadog-mittarina. Laskettava avainmittari on cache hit ratio: cache_read / (cache_read + input_tokens). Tuotantotavoitteeni on tyypillisesti yli 70 %.

from prometheus_client import Counter, Histogram

cache_hits = Counter("llm_cache_read_tokens", "Välimuistista luetut tokenit", ["model"])
cache_writes = Counter("llm_cache_write_tokens", "Välimuistiin kirjoitetut", ["model"])
input_tokens = Counter("llm_input_tokens", "Tavalliset input-tokenit", ["model"])

def record(response, model: str):
    cache_hits.labels(model).inc(response.usage.cache_read_input_tokens or 0)
    cache_writes.labels(model).inc(response.usage.cache_creation_input_tokens or 0)
    input_tokens.labels(model).inc(response.usage.input_tokens or 0)

CI-portti regressioita vastaan. Lisää testi, joka rakentaa tyypillisen tuotantopyynnön kahdesti ja vaatii toisessa kutsussa positiivisen cache_read-arvon. Tämä paljastaa heti, jos joku lisää aikaleiman system-promptiin tai vaihtaa työkalujen järjestystä.

Dashboard kustannuksille. Yhdistä token-mittarit hintakerrottimiin (esim. Grafana-paneeli, joka näyttää $/päivä ja erottaa cache-osumat, -kirjoitukset ja täyshintaiset tokenit). Tämä on aikuisin asia, jonka voit tehdä LLM-kustannusten hallitsemiseksi vuonna 2026.

Usein kysytyt kysymykset

Toimiiko prompt caching streaming-vastausten kanssa?

Kyllä. Sekä Anthropic että OpenAI tukevat cachingia streaming-tilassa. Cache_creation/read-arvot näkyvät streamin viimeisessä message_delta-tapahtumassa usage-kentässä, joten kerää ne stream-iteraation lopussa.

Miksi cache_read_input_tokens on nolla, vaikka cache_control on asetettu?

Lähes aina syynä on hiljainen invalidoija: aikaleima järjestelmäkehotteessa, ei-deterministinen JSON-serialisointi, työkalulistan järjestyksen muutos tai prefiksin alle minimitokenirajan jääminen (1 024 Sonnetille, 4 096 Opukselle). Tee diff kahden peräkkäisen pyynnön renderöidystä prefiksistä; ero löytyy yleensä ensimmäiseltä 100 tavulta.

Pitääkö 1-tunnin TTL:n käyttäminen aina enemmän kuin 5 minuutin TTL?

Ei. 1-tunnin TTL maksaa 2× kirjoitushinnan vs. 1.25× lyhyemmälle, joten se kannattaa vasta jos sama prefiksi luetaan vähintään kolme kertaa ennen vanhenemista. Interaktiivisille chat-sovelluksille 5 min on yleensä parempi; eräajopipelineille, joissa pyynnöt voivat venyä useita kymmeniä minuutteja, 1 tunti voittaa.

Mitkä Claude-mallit tukevat prompt cachingia vuonna 2026?

Kaikki Claude 4.x -mallit tukevat: Opus 4.6, 4.7 ja 4.8 (minimi 4 096 tokenia), Sonnet 4.6 ja Haiku 4.5 (minimi 1 024 tokenia). Vanhemmat 3.x-mallit on poistettu käytöstä 2026 alussa, joten cachingin käyttö niissä ei ole enää relevanttia. Fable 5 -malli noudattaa samaa rajapintaa kuin Opus 4.8.

Voiko prompt cachingia yhdistää extended thinkingin tai työkalujen kanssa?

Kyllä molempien kanssa. Adaptive thinking (thinking: {"type": "adaptive"}) ei vaikuta cachen toimintaan. Työkalut renderöidään ennen system-promptia, joten cache_control viimeisellä system-lohkolla tallentaa myös työkalumäärittelyt yhdessä. Tärkeä huomio: työkalulistan lisäys, poisto tai uudelleenjärjestäminen sessioiden välillä mitätöi koko cachen, joten pidä työkalusarja vakaana.