Prompt-caching

Hur det fungerar

• Prefix, i ordning — Prompten läses i ordning: system-prompt, verktygsdefinitioner och sedan meddelandena. Cachen matchar från början av den sekvensen upp till den första token som skiljer sig.
• Vad som räknas som en hit — En förfrågan vars prompt börjar med samma innehåll som en nyligen gjord förfrågan — vanligtvis den föregående vändningen i samma konversation med nya meddelanden tillagda. Det matchande prefixet är cachad input; allt efter det är vanlig input.
• Granularitet — Cachen lagrar en prompt i block om 1,568 tokens, så en prompt kortare än cirka 1,500 tokens cachas inte. Det cachade antalet i ett svar är ditt inputantal multiplicerat med promptens cachade andel, avrundat nedåt. Det är inte nödvändigtvis en multipel av blockstorleken.
• Utan hit — En begäran vars början inte finns i cachen faktureras till ordinarie inputpris. Ingen livslängd anges för cachade prompter och en hit är inte garanterad: läs usage för att se vad en begäran tog från cachen.
• Ingen strömbrytare — En begäran behöver inte aktivera det, och inget fält stänger av cachingen.
• Vilka modeller — Varje hosted open-weight-id. GET /v1/models rapporterar capabilities.prompt_caching: true och pricing.cached_input_per_million_usd för dessa. Shannon-modeller debiteras med en fast takt.

Se en cache-hit i ett svar

Skicka två begäranden som börjar med samma långa systemprompt och skriv ut usage för var och en. Det första talet är begärans input, det andra är den del av den som lästes från 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ättning

Cachade input-tokens debiteras med 25 % av modellens input-takt, avrundat till $0,001 per 1M. Att skriva till cachen kostar inget extra, och output debiteras som vanligt. Varje id:s cachade takt finns i tabellen Modeller & prissättning. Modeller och priser

Inputen i ett anrop debiteras som (input − cachad) × inputpris + cachad × cachepris. Det cachade antalet är aldrig större än inputantalet.

Användningsloggen listar den cachade inputen för varje anrop. Dess fakturerade tokens och kostnad inkluderar redan cachepriset. Nycklar och användning

Användningsfält

{
  "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
  }
}

Ett streamat svar har samma fält i sin slutliga usage. Du behöver inte be om det:

Få fler cache-hits

• Håll system-prompten och verktygsdefinitionerna byte-för-byte stabila mellan anrop. Placera värden som ändras per anrop, såsom tidsstämplar eller request-id:n, i slutet av det senaste meddelandet, inte i system-prompten.
• Endast lägg till i historiken. Att redigera, trimma eller sammanfatta tidigare vändningar ändrar prefixet, och allt efter den första ändringen debiteras som vanlig input.
• Ändra inte ordningen på verktyg, meddelanden eller innehållsblock mellan anrop, och serialisera JSON (verktygscheman, verktygsargument och resultat) på samma sätt varje gång.
• Håll dig till ett modell-id under en konversation och skicka uppföljningsanropet kort efter det föregående.

API:et håller början av en konversation stabil i de här fallen:

• Ett system- eller developer-meddelande som skickas senare i en konversation stannar på sin plats. Det ändrar inte promptens början, så turerna före det förblir cachade.
• Argumenten i verktygsanrop i tidigare assistentturer jämförs efter värde. Nyckelordning och mellanrum i den JSON:en spelar ingen roll.
• De tre endpointsen läser en konversation på samma sätt. En konversation som fortsätter på en annan endpoint behåller sitt gemensamma prefix när innehållet är detsamma.

Begäranfält

prompt_cache_key (Chat Completions och Responses) och cache_control på Messages innehållsblock accepteras, så befintlig klientkod körs oförändrad. Ingen av dem är obligatorisk: cachning är automatisk och fungerar likadant utan dem.

Räkna tokens

Två kostnadsfria endpoints, POST /v1/tokenize och POST /v1/messages/count_tokens, räknar tokens i en text eller i en hel begäran för de hostade open-weight-modellerna innan du skickar den. De har en egen sida: Tokenräkning