Caching promptov

Ako to funguje

• Prefix v poradí — Prompt sa číta v tomto poradí: systémový prompt, definície nástrojov a následne správy. Cache sa zhoduje od začiatku tejto sekvencie až po prvý token, ktorý sa líši.
• Čo sa považuje za hit — Request, чеjho prompt začína rovnakým obsahom ako nedávny request — typicky predchádzajúci krok v tej istej konverzácii s pridanými novými správami. Zhodujúci sa prefix je cache vstup; všetko po ňom je regulárny vstup.
• Granularita — Cache drží prompt v blokoch po 1,568 tokenoch, takže prompt kratší než asi 1,500 tokenov sa necachuje. Počet cachovaných tokenov v odpovedi je váš počet vstupných tokenov vynásobený cachovaným podielom promptu, zaokrúhlený nadol. Nemusí byť násobkom veľkosti bloku.
• Bez hitu — Request, ktorého začiatok nie je v cache, sa účtuje bežnou sadzbou vstupu. Pre cachované prompty sa nezverejňuje žiadna životnosť a hit nie je zaručený: z usage zistíte, čo si request z cache vzal.
• Žiadny prepínač — Request sa do cachovania nezapája a žiadne pole ho nevypína.
• Ktoré modely — Každé hostované open-weight ID. GET /v1/models hlási capabilities.prompt_caching: true a pricing.cached_input_per_million_usd pre ne. Modely Shannon fakturujú jednu paušálnu sadzbu.

Cache hit v odpovedi

Pošlite dva requesty, ktoré začínajú rovnakým dlhým systémovým promptom, a vypíšte usage každého. Prvé číslo je vstup requestu, druhé je jeho časť prečítaná z 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

Cenenie

Tokeny cache vstupu sa fakturujú za 25 % ceny vstupu modelu, zaokrúlené na $0.001 per 1M. Zápis do cache nestojí nič navyše a výstup sa fakturuje ako obvykle. Cena cache pre každé ID je v tabuľke Modely a ceny. Modely a ceny

Vstup volania sa účtuje ako (vstup − cachovaný) × sadzba vstupu + cachovaný × sadzba cachovaného. Počet cachovaných nikdy nie je väčší než počet vstupných.

Záznam využitia uvádza cachovaný vstup každého volania. Jeho účtované tokeny a cena už zahŕňajú sadzbu cachovaného. Kľúče a využitie

Polia používania

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

Streamovaná odpoveď nesie rovnaké polia v záverečnom usage. Nemusíte oň žiadať:

Ako dosiahnuť viac cache hitov

• Udržujte systémový prompt a definície nástrojov byte-po-byte stabilné medzi volaniami. Hodnoty špecifické pre konkrétne volanie, ako časové značky alebo ID requestov, umiestňujte na koniec poslednej správy, nie do systémového promptu.
• Do histórie len dopisujte. Upravovanie, deštruktúrovanie alebo zhrnutie predchádzajúcich krokov mení prefix a všetko po prvej zmene sa fakturuje ako regulárny vstup.
• Nemeňte poradie nástrojov, správ alebo blokov obsahu medzi volaniami a JSON (schémy nástrojov, argumenty a výsledky) serializujte vždy rovnakým spôsobom.
• V jednej konverzácii zostaňte pri jednom id modelu a ďalšie volanie posielajte krátko po predchádzajúcom.

API drží začiatok konverzácie stabilný v týchto prípadoch:

• Správa system alebo developer poslaná neskôr v konverzácii zostáva na svojom mieste. Nemení začiatok promptu, takže predchádzajúce kolá zostávajú v cache.
• Argumenty volaní nástrojov v skorších kolách asistenta sa porovnávajú podľa hodnoty. Na poradí kľúčov a medzerách v tomto JSON nezáleží.
• Tri endpointy čítajú konverzáciu rovnako. Konverzácia pokračujúca na inom endpointe si zachová spoločný prefix, ak je obsah rovnaký.

Polia requestu

Prijíma sa prompt_cache_key (Chat Completions a Responses) a cache_control v content blockoch správ, takže existujúci kód klienta beží bez zmien. Žiadne z nich nie sú povinné: caching je automatický a funguje aj bez nich.

Počítanie tokenov

Dva bezplatné endpointy, POST /v1/tokenize a POST /v1/messages/count_tokens, spočítajú tokeny textu alebo celého requestu pre hostované open-weight modely skôr, než ho odošlete. Majú vlastnú stránku: Počítanie tokenov