Caché de prompts

Como funciona

• Prefixo, por orde — O prompt léase por orde: prompt de sistema, definicións de ferramentas e, despois, as mensaxes. A caché coincide desde o inicio desa secuencia ata o primeiro token que difire.
• Que debeda considerarse un acerto (hit) — Unha requisição cuxo prompt comeza co mesmo contido que unha requisição Recente —normalmente o turno anterior da mesma conversación con novas mensaxes engadidas. O prefixo coincidente é entrada almacenada; todo o que vén despois é entrada regular.
• Granularidade — A caché garda un prompt en bloques de 1,568 tokens, así que un prompt máis curto que uns 1,500 tokens non se almacena na caché. O reconto de caché dunha resposta é o teu reconto de entrada multiplicado pola parte do prompt que está en caché, redondeado cara abaixo. Non é necesariamente un múltiplo do tamaño do bloque.
• Sen acerto — Unha solicitude cuxo comezo non está na caché factúrase á tarifa de entrada normal. Non se publica ningunha duración para os prompts en caché e un acerto non está garantido: le usage para ver o que tomou da caché unha solicitude.
• Sen interruptor — Unha solicitude non se acolle a ela, e ningún campo desactiva a caché.
• Que modelos — Cada id de open-weight hosted. GET /v1/models informa de capabilities.prompt_caching: true e pricing.cached_input_per_million_usd para eles. Os modelos Shannon facturan unha tarifa plana.

Ver un acerto de caché nunha resposta

Envía dúas solicitudes que comecen co mesmo system prompt longo e imprime o uso de cada unha. O primeiro número é a entrada da solicitude; o segundo é a parte dela que se leu da caché.

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

Prezos

Os tokens de entrada almacenada factúranse ao 25% da tarifa de entrada do modelo, arredondado a $0.001 por 1M. Escribir na caché non custa extra, e a saída factúrase como de costume. A tarifa de caché de cada id está na táboa de Modelos e prezos. Modelos e prezos

A entrada dunha chamada cóbrase como (entrada − caché) × tarifa de entrada + caché × tarifa de caché. O reconto de caché nunca é maior que o reconto de entrada.

O rexistro de uso lista a entrada en caché de cada chamada. Os seus tokens facturados e o custo xa inclúen a tarifa de caché. Claves e uso

Campos de uso

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

Unha resposta en stream leva os mesmos campos no seu uso final. Non fai falta pedilo:

Como conseguir máis acertos de caché

• Mantén o prompt de sistema e as definicións de ferramentas estables byte por byte entre chamadas. Coloca valores de cada chamada, como marcas temporais ou ids de requisição, ao final da última mensaxe, non no prompt de sistema.
• Só engade ao historial. Editar, recortar ou resumir turnos anteriores cambia o prefixo, e todo o que ven despois do primeiro cambio factúrase como entrada regular.
• Non reordenes ferramentas, mensaxes ou bloques de contido entre chamadas, e serializa JSON (esquemas de ferramentas, argumentos e resultados) da mesma maneira cada vez.
• Mantente nun só id de modelo durante unha conversa e envía a seguinte chamada pouco despois da anterior.

A API mantén estable o comezo dunha conversa nestes casos:

• Unha mensaxe system ou developer enviada máis tarde nunha conversa queda no seu lugar. Non cambia o comezo do prompt, así que os turnos anteriores seguen na caché.
• Os argumentos das chamadas a ferramentas en turnos anteriores do asistente compáranse por valor. A orde das claves e o espazado dese JSON non importan.
• Os tres endpoints len unha conversa da mesma maneira. Unha conversa continuada noutro endpoint mantén o seu prefixo compartido cando o contido é o mesmo.

Campos da solicitude

Aceptanse prompt_cache_key (Chat Completions e Responses) e cache_control nos bloques de contido de Messages, polo que o código do cliente existente execútase sen cambios. Ningún dos dous é obrigatorio: o caching é automático e funciona igual sen eles.

Contaxe de tokens

Dous endpoints gratuítos, POST /v1/tokenize e POST /v1/messages/count_tokens, contan os tokens dun texto ou dunha solicitude completa para os modelos open-weight alojados antes de que a envíes. Teñen a súa propia páxina: Reconto de tokens