Caching de prompt

Cum funcționează

• Prefix, în ordine — Promptul este citit în ordine: prompt de sistem, definiții de instrumente, apoi mesajele. Cache-ul se potrivește de la începutul acelei secvențe până la primul token care diferă.
• Ce se consideră un „hit” — O cerere al cărei prompt începe cu același conținut ca o cerere recentă — în general, runda anterioară a aceleiași conversații cu mesaje noi adăugate. Prefixul corespunzător este intrare din cache; tot ce urmează este intrare regulată.
• Granularitate — Cache-ul păstrează un prompt în blocuri de 1,568 token-uri, deci un prompt mai scurt de aproximativ 1,500 token-uri nu este pus în cache. Numărul din cache dintr-un răspuns este numărul tău de intrare înmulțit cu partea din prompt aflată în cache, rotunjit în jos. Nu este neapărat un multiplu al dimensiunii blocului.
• Fără hit — O cerere al cărei început nu se află în cache este facturată la tariful obișnuit de intrare. Nu se publică nicio durată de viață pentru prompt-urile din cache și un hit nu este garantat: citește usage pentru a vedea ce a luat o cerere din cache.
• Fără comutator — O cerere nu trebuie să se înscrie și niciun câmp nu dezactivează caching-ul.
• Ce modele — Orice ID hosted open-weight. GET /v1/models raportează capabilities.prompt_caching: true și pricing.cached_input_per_million_usd pentru acestea. Modelele Shannon facturează un tarif fix.

Vezi un cache hit într-un răspuns

Trimite două cereri care încep cu același system prompt lung și afișează utilizarea fiecăreia. Primul număr este intrarea cererii, al doilea este partea din ea citită din cache.

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

Prețuri

Token-urile de intrare din cache sunt facturate la 25% din tariful de intrare al modelului, rotunjit la $0.001 per 1M. Scrierea în cache nu costă suplimentar, iar ieșirea este facturată ca ownțial. Tariful de cache pentru fiecare ID se află în tabelul Models & pricing. Modele și prețuri

Intrarea unui apel este taxată ca (intrare − din cache) × tarif de intrare + din cache × tarif cache. Numărul din cache nu este niciodată mai mare decât numărul de intrare.

Jurnalul de utilizare listează intrarea din cache a fiecărui apel. Token-urile facturate și costul includ deja tariful cache. Chei și utilizare

Câmpuri de utilizare

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

Un răspuns în streaming poartă aceleași câmpuri în utilizarea finală. Nu trebuie să o ceri:

Cum să obțineți mai multe cache hits

• Mențineți promptul de sistem și definițiile instrumentelor stabile byte-la-byte între apeluri. Plasați valorile specifice fiecărui apel, cum ar fi timestamp-urile sau ID-urile de cerere, la sfârșitul ultimului mesaj, nu în promptul de sistem.
• Adăugați doar la finalul istoricului. Editarea, tăierea sau rezumarea rundelor anterioare modifică prefixul, iar tot ce urmează după prima modificare este facturat ca intrare regulată.
• Nu reordonați instrumentele, mesajele sau blocurile de conținut între apeluri și serializați JSON (schemele instrumentelor, argumentele și rezultatele instrumentelor) la fel de own dată.
• Rămâi la același id de model pe durata unei conversații și trimite apelul următor la scurt timp după cel dinainte.

API-ul menține stabil începutul unei conversații în aceste cazuri:

• Un mesaj system sau developer trimis mai târziu într-o conversație rămâne la locul lui. Nu schimbă începutul prompt-ului, deci rundele de dinaintea lui rămân în cache.
• Argumentele apelurilor de instrument din rundele anterioare ale asistentului sunt comparate după valoare. Ordinea cheilor și spațierea acelui JSON nu contează.
• Cele trei endpoint-uri citesc o conversație în același mod. O conversație continuată pe alt endpoint își păstrează prefixul comun când conținutul este același.

Câmpuri de cerere

prompt_cache_key (pentru Chat Completions și Responses) și cache_control pe blocurile de conținut Messages sunt acceptate, astfel încât codul client existent funcționează fără modificări. Niciunul nu este obligatoriu: caching-ul este automat și funcționează la fel și fără ele.

Numărarea token-urilor

Două endpoint-uri gratuite, POST /v1/tokenize și POST /v1/messages/count_tokens, numără token-urile unui text sau ale unei cereri întregi pentru modelele open-weight găzduite înainte să o trimiți. Ele au propria pagină: Numărarea token-urilor