Caching de prompts

Com funciona

• Prefix, en ordre — El prompt es llegeix en ordre: prompt de sistema, definicions d'eines i després els missatges. La cache coincideix des de l'inici d'aquesta seqüència fins al primer token que difereix.
• Què es considera un 'hit' — Una sol·licitud el seu prompt de la qual comença amb el mateix contingut que una sol·licitud recent —típicament el torn anterior de la mateixa conversa amb nous missatges adjunts. El prefix coincident és entrada en cache; tot el que segueix és entrada regular.
• Granularitat — La cache guarda un prompt en blocs de 1,568 tokens, de manera que un prompt de menys d'uns 1,500 tokens no es desa a la cache. El recompte en cache d'una resposta és el teu recompte d'entrada multiplicat per la part en cache del prompt, arrodonit cap avall. No és necessàriament un múltiple de la mida del bloc.
• Sense hit — Una sol·licitud l'inici de la qual no és a la cache es factura a la tarifa d'entrada normal. No es publica cap durada per als prompts en cache i un hit no està garantit: llegeix usage per veure què ha pres una sol·licitud de la cache.
• Sense interruptor — Una sol·licitud no s'hi ha d'adherir, i cap camp desactiva la cache.
• Quins models — Cada id hosted open-weight. GET /v1/models informa de capabilities.prompt_caching: true i pricing.cached_input_per_million_usd per a ells. Els models Shannon facturen una tarifa plana.

Veure un hit de cache en una resposta

Envia dues sol·licituds que comencin amb el mateix prompt de sistema llarg i imprimeix l'ús de cadascuna. El primer número és l'entrada de la sol·licitud, el segon és la part que s'ha llegit de la 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

Preus

Els tokens d'entrada en cache es facturen al 25% de la tarifa d'entrada del model, arroblat a $0.001 per 1M. Escriure a la cache no costa res extra, i la sortida es factura com de habitual. La tarifa de cache de cada id és la taula de Models i preus. Models i preus

L'entrada d'una crida es cobra com (entrada − en cache) × tarifa d'entrada + en cache × tarifa de cache. El recompte en cache mai és més gran que el recompte d'entrada.

El registre d'ús llista l'entrada en cache de cada crida. Els seus tokens facturats i el cost ja inclouen la tarifa de cache. Keys & usage

Camps d'ús

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

Una resposta en stream porta els mateixos camps al seu ús final. No cal que el demanis:

Com aconseguir més hits de cache

• Manteniu el prompt de sistema i de la definició d'eines estables byte per byte entre crides. Poseu els valors per crida, com de la data o els ids de sol·licitud, al final del darrer missatge, no al prompt de sistema.
• Només adjunteu a l'historial. Editar, tallar o resumir torns anteriors canvia el prefix, i tot el que segueu al primer canvi es factura com a entrada regular.
• No reordoneu eines, missatges o blocs de contingut entre crides, i serialitzeu el JSON (esquemes d'eines, arguments i resultats) de la mateixa manera cada vegada.
• Mantén-te en un sol id de model durant una conversa i envia la crida següent poc després de l'anterior.

L'API manté estable l'inici d'una conversa en aquests casos:

• Un missatge system o developer enviat més tard en una conversa es manté al seu lloc. No canvia l'inici del prompt, de manera que els torns anteriors continuen en cache.
• Els arguments de les crides d'eina dels torns anteriors de l'assistent es comparen per valor. L'ordre de les claus i els espais d'aquest JSON no importen.
• Els tres endpoints llegeixen una conversa de la mateixa manera. Una conversa continuada en un altre endpoint conserva el seu prefix compartit quan el contingut és el mateix.

Camps de la sol·licitud

Es demanen prompt_cache_key (Chat Completions i Responses) i cache_control en els blocs de contingut de Messages, de manera que el codi del client existent s'executa sense canvis. Cap dels dos és obligatori: el caching és automàtic i funciona igual sense ells.

Comptabilització de tokens

Dos endpoints gratuïts, POST /v1/tokenize i POST /v1/messages/count_tokens, compten els tokens d'un text o d'una sol·licitud sencera per als models open-weight hostejats abans d'enviar-la. Tenen la seva pròpia pàgina: Recompte de tokens