Caching ερωτημάτων

Πώς λειτουργεί

• Πρόθεμα, κατά σειρά — Το prompt διαβάζεται με τη σειρά: system prompt, ορισμοί εργαλείων και στη συνέχεια τα μηνύματα. Η cache αντιστοιχεί από την αρχή αυτής της ακολουθίας έως το πρώτο token που διαφέρει.
• Τι θεωρείται hit — Ένα αίτημα του οποίου το prompt ξεκινά με το ίδιο περιεχόμενο με ένα πρόσφατο αίτημα — συνήθως ο προηγούμενος γύρος της ίδιας συνομιλίας με προσθήκη νέων μηνυμάτων. Το αντιστοιχόμενο πρόθεμα είναι cached input· οτιδήποτε μετά από αυτό είναι κανονική είσοδος.
• Κοκκοφάνεια — Το cache κρατά ένα prompt σε blocks των 1,568 tokens, οπότε ένα prompt μικρότερο από περίπου 1,500 tokens δεν μπαίνει στο cache. Ο αριθμός cached σε μια απάντηση είναι ο αριθμός εισόδου σας πολλαπλασιασμένος με το cached μερίδιο του prompt, στρογγυλοποιημένος προς τα κάτω. Δεν είναι απαραίτητα πολλαπλάσιο του μεγέθους του block.
• Χωρίς hit — Ένα αίτημα του οποίου η αρχή δεν βρίσκεται στο cache χρεώνεται με την κανονική τιμή εισόδου. Δεν δημοσιεύεται διάρκεια ζωής για cached prompts και το hit δεν είναι εγγυημένο: διαβάστε το usage για να δείτε τι πήρε ένα αίτημα από το cache.
• Χωρίς διακόπτη — Ένα αίτημα δεν χρειάζεται να επιλέξει συμμετοχή και κανένα πεδίο δεν απενεργοποιεί το caching.
• Ποια μοντέλα — Κάθε hosted open-weight id. Το GET /v1/models αναφέρει capabilities.prompt_caching: true και pricing.cached_input_per_million_usd για αυτά. Τα μοντέλα Shannon χρεώνουν μια ενιαία τιμή.

Δείτε ένα cache hit σε μια απάντηση

Στείλτε δύο αιτήματα που ξεκινούν με το ίδιο μακρύ system prompt και εκτυπώστε τη χρήση του καθενός. Ο πρώτος αριθμός είναι η είσοδος του αιτήματος, ο δεύτερος το μέρος της που διαβάστηκε από το 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

Τιμολόγηση

Τα cached input tokens χρεώνονται στο 25% της τιμής εισόδου του μοντέλου, στρογγυλοποιημένα σε $0.001 ανά 1M. Η εγγραφή στην cache δεν κοστίζει τίποτα επιπλέον και η έξοδος χρεώνεται κανονικά. Η τιμή cached για κάθε id βρίσκεται στον πίνακα Models & pricing. Μοντέλα & τιμές

Η είσοδος μιας κλήσης χρεώνεται ως (είσοδος − cached) × τιμή εισόδου + cached × τιμή cached. Ο αριθμός cached δεν είναι ποτέ μεγαλύτερος από τον αριθμό εισόδου.

Το ιστορικό χρήσης απαριθμεί την cached είσοδο κάθε κλήσης. Τα χρεωμένα tokens και το κόστος του περιλαμβάνουν ήδη την τιμή cached. Κλειδιά & χρήση

Πεδία χρήσης

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

Μια απάντηση με streaming φέρει τα ίδια πεδία στην τελική της χρήση. Δεν χρειάζεται να το ζητήσετε:

Πώς να πετύχετε περισσότερα cache hits

• Διατηρήστε το system prompt και τους ορισμούς εργαλείων ακριβώς σταθερούς μεταξύ των κλήσεων. Τοποθετήστε τιμές που αλλάζουν ανά κλήση, όπως timestamps ή request ids, στο τέλος του τελευταίου μηνύματος, όχι στο system prompt.
• Προσθέστε μόνο στο ιστορικό. Η επεξεργασία, η διαγραφή ή η σύνοψη προηγούμενων γύρων αλλάζει το πρόθεμα, και οτιδήποτε μετά την πρώτη αλλαγή χρεώνεται ως κανονική είσοδος.
• Μην αλλάζετε τη σειρά των εργαλείων, των μηνυμάτων ή των blocks περιεχομένου μεταξύ των κλήσεων, και σειριοποιήστε το JSON (σχήματα εργαλείων, ορίσματα και αποτελέσματα) με τον ίδιο τρόπο κάθε φορά.
• Μείνετε σε ένα id μοντέλου για μια συνομιλία και στείλτε την επόμενη κλήση λίγο μετά την προηγούμενη.

Το API κρατά σταθερή την αρχή μιας συνομιλίας σε αυτές τις περιπτώσεις:

• Ένα μήνυμα system ή developer που στέλνεται αργότερα στη συνομιλία μένει στη θέση του. Δεν αλλάζει την αρχή του prompt, οπότε οι γύροι πριν από αυτό μένουν στο cache.
• Τα ορίσματα των κλήσεων εργαλείων σε προηγούμενους γύρους του assistant συγκρίνονται κατά τιμή. Η σειρά των κλειδιών και τα κενά σε αυτό το JSON δεν έχουν σημασία.
• Τα τρία endpoints διαβάζουν μια συνομιλία με τον ίδιο τρόπο. Μια συνομιλία που συνεχίζεται σε άλλο endpoint κρατά το κοινό της πρόθεμα όταν το περιεχόμενο είναι το ίδιο.

Πεδία αιτήματος

Δέχονται τα prompt_cache_key (Chat Completions και Responses) και το cache_control στα content blocks των Messages, ώστε ο υπάρχων κώδικας του client να εκτελείται αδιάλλακτος. Κανένα από τα δύο δεν είναι υποχρεωτικό: η προσωρινή αποθήκευση (caching) είναι αυτόματη και λειτουργεί το ίδιο χωρίς αυτά.

Καταμέτρηση tokens

Δύο δωρεάν endpoints, τα POST /v1/tokenize και POST /v1/messages/count_tokens, μετρούν τα tokens ενός κειμένου ή ενός ολόκληρου αιτήματος για τα φιλοξενούμενα μοντέλα ανοιχτών βαρών πριν το στείλετε. Έχουν τη δική τους σελίδα: Καταμέτρηση tokens