Prompt Caching

Wéi et funktionéiert

• Prefix, an der Rei — De Prompt gëtt an dëser Rei gelies: System-Prompt, Tool-Definitiounen, dann d'Messagen. De Cache matcht vum Ufank vun dëser Sequenz bis zum éischte Token, dee sech ënnerscheet.
• Wat gëtt als Hit gezielt — Eng Request, deren Prompt mat deem gellchen Content vun enger rezente Request ufänkt — typischerweis de virausgoende Tour vun der gellcher Conversatioun mat neie Messagen am Enn. De matching Prefix ass cached Input; alles dropout ass regulären Input.
• Granularitéit — De Cache hält e Prompt a Blöck vun 1,568 Tokens, dofir gëtt e Prompt, dee méi kuerz ass wéi ongeféier 1,500 Tokens, net gecacht. D'Cached-Zuel an enger Äntwert ass Är Input-Zuel multiplizéiert mam gecachten Undeel vum Prompt, ofgerënnt. Si ass net onbedéngt e Multipel vun der Blockgréisst.
• Ouni Hit — Eng Ufro, där hire Start net am Cache ass, gëtt zum normalen Input-Tarif ofgerechent. Fir gecachte Prompts gëtt keng Liewensdauer verëffentlecht an en Hit ass net garantéiert: liest usage, fir ze gesinn, wat eng Ufro aus dem Cache geholl huet.
• Kee Schalter — Eng Ufro mellt sech net un, a kee Feld schalt d'Caching of.
• Wéich Modeller — Jeden hosted open-weight ID. GET /v1/models reportéiert capabilities.prompt_caching: true an pricing.cached_input_per_million_usd fir se. Shannon Modeller berechnen e flachen Tarif.

Een Cache-Hit an enger Äntwert gesinn

Schéckt zwou Ufroen, déi mat deemselwechte laange System-Prompt ufänken, a gitt d'Usage vun all Ufro aus. Déi éischt Zuel ass den Input vun der Ufro, déi zweet ass den Deel dovun, deen aus dem Cache gelies gouf.

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

Pris

Cached Input Tokens ginn mat 25% vum Input-Tarif vum Modell abgerechnet, gerundet op $0.001 pro 1M. D'Schreiwen an de Cache kascht näischt extra, an den Output gëtt wéi gewillt abgerechnet. De cached Tarif vun jedem ID ass an der Tabell 'Models & pricing' ze fannen. Modeller a Präisser

Den Input vun engem Opruff gëtt als (Input − cached) × Input-Tarif + cached × Cached-Tarif berechent. D'Cached-Zuel ass ni méi grouss wéi d'Input-Zuel.

D'Notzungslog lëscht den Cached Input vun all Opruff. Seng ofgerechent Tokens a Käschte enthalen den Cached-Tarif schonn. Schlësselen & Notzung

Usage Felder

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

Eng gestreamt Äntwert huet déiselwecht Felder an hirer lescht Usage. Dir musst net dornach froen:

Méi Cache Hits kréien

• Halt de System-Prompt an d'Tool-Definitiounen Byte-fir-Byte stabil iwwer d'Calls hinweg. Setzt per-Call Wäerter wéi Timestamps oder Request IDs un den Enn vun der letschter lëscht Message, net an den System-Prompt.
• Fügegt nëm de History un. Wann Dir fréier Tourën editéiert, kürzt oder resuméiert, ännert Dir de Prefix, an alles no der éischter Ännerung gëtt als regulären Input abgerechnet.
• Ännert d'Rei follong vun Tools, Messagen oder Content Blöck tëscht de Calls net, an serialiséiert JSON (Tool Schemas, Tool Argumenter an Resultater) ëmmer op déi gläich Manéier.
• Bleift fir e Gespréich bei enger Modell-ID, a schéckt déi nächst Ufro kuerz no der virdrun.

D'API hält de Start vun engem Gespréich an dëse Fäll stabil:

• Eng system- oder developer-Message, déi méi spéit an engem Gespréich geschéckt gëtt, bleift op hirem Plaz. Si ännert de Start vum Prompt net, sou datt d'Tourë virun hir gecacht bleiwen.
• D'Argumenter vun Tool-Ufruffer a fréiere Assistant-Tourë ginn nom Wäert verglach. D'Rei vun de Schlësselen a Leerzeechen an deem JSON spillen keng Roll.
• Déi dräi Endpoints liesen e Gespréich op déiselwecht Manéier. E Gespréich, dat op engem aneren Endpoint weidergefouert gëtt, behält säi gemeinsame Prefix, wann den Inhalt dee selwechte ass.

Request-Felder

prompt_cache_key (Chat Completions an Responses) an cache_control op Messages Content Blocks ginn akzeptéiert, sou datt bestehende Client-Code ouni Änderung funktionéiert. Keen vun dene ass obligatoresch: Caching ass automatesch an funktionéiert och ouni se gläich.

Tokens zielen

Zwee gratis Endpoints, POST /v1/tokenize an POST /v1/messages/count_tokens, zielen d'Tokens vun engem Text oder vun enger ganzer Ufro fir d'Hosted Open-Weight-Modeller, éier Dir se schéckt. Si hunn hir eege Säit: Tokenzielung