Prompt-caching

Hvordan det fungerer

• Præfiks, i rækkefølge — Prompten læses i rækkefølge: system prompt, værktøjsdefinitioner og derefter beskederne. Cachen matcher fra starten af denne sekvens op til den første token, der afviger.
• Hvad tæller som et hit — En anmodning hvis prompt starter med samme indhold som en nylig anmodning — typisk den forrige tur i den samme samtale med nye beskeder tilføjet. Det matchende præfiks er cached input; alt efter dette er regulært input.
• Granularitet — Cachen rummer en prompt i blokke på 1,568 tokens, så en prompt på under ca. 1,500 tokens caches ikke. Det cachede antal i et svar er dit inputantal ganget med den cachede andel af prompten, rundet ned. Det er ikke nødvendigvis et multiplum af blokstørrelsen.
• Uden hit — En anmodning, hvis begyndelse ikke findes i cachen, afregnes til den almindelige inputtakst. Der offentliggøres ingen levetid for cachede prompts, og et hit er ikke garanteret: læs usage for at se, hvad en anmodning tog fra cachen.
• Ingen kontakt — En anmodning tilmelder sig ikke, og intet felt slår caching fra.
• Hvilke modeller — Hvert hosted open-weight id. GET /v1/models rapporterer capabilities.prompt_caching: true og pricing.cached_input_per_million_usd for dem. Shannon-modeller afregnes med én flad takst.

Se et cache-hit i et svar

Send to anmodninger, der begynder med den samme lange system prompt, og udskriv forbruget for hver. Det første tal er anmodningens input, det andet er den del af det, der blev læst fra cachen.

from openai import OpenAI

client = OpenAI(api_key="YOUR_API_KEY", base_url="https://api.shannon-ai.com/v1")

handbook = open("handbook.txt").read()  # a long text that stays the same


def ask(question):
    response = client.chat.completions.create(
        model="Kimi-K3-3BIT-REAP",
        messages=[
            {"role": "system", "content": handbook},
            {"role": "user", "content": question},
        ],
    )
    usage = response.usage
    print(usage.prompt_tokens, usage.prompt_tokens_details.cached_tokens)


ask("What is the refund policy?")
ask("Who approves travel?")  # same start: read the second number

import { readFileSync } from "node:fs";
import OpenAI from "openai";

const client = new OpenAI({ apiKey: "YOUR_API_KEY", baseURL: "https://api.shannon-ai.com/v1" });

const handbook = readFileSync("handbook.txt", "utf8"); // a long text that stays the same

async function ask(question) {
  const response = await client.chat.completions.create({
    model: "Kimi-K3-3BIT-REAP",
    messages: [
      { role: "system", content: handbook },
      { role: "user", content: question },
    ],
  });
  const usage = response.usage;
  console.log(usage.prompt_tokens, usage.prompt_tokens_details.cached_tokens);
}

await ask("What is the refund policy?");
await ask("Who approves travel?"); // same start: read the second number

# handbook.txt is a long text that stays the same. jq builds the JSON body from it
# and prints the usage object of the reply. Run it twice with different questions.
jq -Rs '{
    model: "Kimi-K3-3BIT-REAP",
    messages: [
      {role: "system", content: .},
      {role: "user", content: "What is the refund policy?"}
    ]
  }' handbook.txt \
  | curl -s https://api.shannon-ai.com/v1/chat/completions \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d @- \
  | jq .usage

Prissætning

Cached input tokens afregnes til 25% af modellens input-takst, afrundet til $0,001 per 1M. Skrivning til cachen koster ikke ekstra, og output afregnes som sædvanlig. Hvert ids cached-takst findes i tabellen Models & pricing. Modeller og priser

Et kalds input afregnes som (input − cachet) × inputtakst + cachet × cache-takst. Det cachede antal er aldrig større end inputantallet.

Forbrugsloggen viser det cachede input for hvert kald. Dens afregnede tokens og omkostninger indeholder allerede cache-taksten. Nøgler og forbrug

Felter for brug

{
  "usage": {
    "prompt_tokens": 20000,
    "completion_tokens": 812,
    "total_tokens": 20812,
    "prompt_tokens_details": {
      "cached_tokens": 18000
    },
    "completion_tokens_details": {
      "reasoning_tokens": 604
    }
  }
}

{
  "usage": {
    "input_tokens": 20000,
    "input_tokens_details": {
      "cached_tokens": 18000
    },
    "output_tokens": 812,
    "output_tokens_details": {
      "reasoning_tokens": 604
    },
    "total_tokens": 20812
  }
}

{
  "usage": {
    "input_tokens": 2000,
    "cache_read_input_tokens": 18000,
    "cache_creation_input_tokens": 0,
    "output_tokens": 812
  }
}

Et streamet svar har de samme felter i sit sidste forbrug. Du behøver ikke bede om det:

Få flere cache-hits

• Hold system prompt og værktøjsdefinitioner byte-for-byte stabile på tværs af kald. Placer værdier per kald, såsom tidsstempler eller request-id'er, i slutningen af den seneste besked, ikke i system prompten.
• Tilføj kun til historikken. Redigering, beskæring eller opsummering af tidligere ture ændrer præfikset, og alt efter den første ændring afregnes som regulært input.
• Omorganiser ikke værktøjer, beskeder eller indholdsbokse mellem kald, og serialiser JSON (værktøjsskemaer, værktøjsargumenter og resultater) på samme måde hver gang.
• Hold dig til ét model-id gennem en samtale, og send opfølgningskaldet kort efter det forrige.

API'et holder begyndelsen af en samtale stabil i disse tilfælde:

• En system- eller developer-besked, der sendes senere i en samtale, bliver på sin plads. Den ændrer ikke begyndelsen af prompten, så turene før den forbliver cachet.
• Argumenterne til værktøjskald i tidligere assistent-ture sammenlignes på værdi. Rækkefølgen af nøgler og mellemrum i den JSON er ligegyldig.
• De tre endpoints læser en samtale på samme måde. En samtale, der fortsættes på et andet endpoint, beholder sit fælles præfiks, når indholdet er det samme.

Anmodningsfelter

prompt_cache_key (Chat Completions og Responses) og cache_control på Messages content blocks accepteres, så eksisterende klientkode kører uændret. Ingen af dem er påkrævet: caching er automatisk og fungerer på samme måde uden dem.

Tælling af tokens

To gratis endpoints, POST /v1/tokenize og POST /v1/messages/count_tokens, tæller tokens i en tekst eller i en hel anmodning for de hostede open-weight-modeller, før du sender den. De har deres egen side: Tælling af tokens