מטמון פרומפטים (Prompt caching)

איך זה עובד

• קידומת, לפי הסדר — הפרומפט נקרא לפי הסדר: system prompt, הגדרות כלים, ואז ההודעות. המטמון תואם מתחילת הרצף ועד לטוקן הראשון השונה.
• מה נחשב כ-hit (פגיעה במטמון) — בקשה שהפרומפט שלה מתחיל באותו תוכן של בקשה אחרונה — בדרך כלל התור הקודם של אותה שיחה עם הודעות חדשות שנוספו. הקידומת התואמת היא קלט במטמון; כל מה שאחריה הוא קלט רגיל.
• רזולוציה (Granularity) — המטמון שומר פרומפט בבלוקים של 1,568 טוקנים, ולכן פרומפט קצר מכ-1,500 טוקנים אינו נשמר במטמון. הכמות במטמון בתשובה היא כמות הקלט שלכם כפול החלק שבמטמון מהפרומפט, מעוגלת כלפי מטה. היא לא בהכרח כפולה של גודל הבלוק.
• בלי hit — בקשה שהתחלתה אינה במטמון מחויבת בתעריף הקלט הרגיל. לא מתפרסמת תקופת חיים לפרומפטים שבמטמון ו-hit אינו מובטח: קראו את usage כדי לראות מה בקשה לקחה מהמטמון.
• אין מתג — בקשה אינה מצטרפת במפורש, ואין שדה שמכבה את המטמון.
• אילו מודלים — כל מזהה (id) מאובחן מסוג open-weight. הפקודה GET /v1/models מדווחת על capabilities.prompt_caching: true ועל pricing.cached_input_per_million_usd עבורם. מודלי Shannon מחייבים תעריף אחיד.

איך רואים cache hit בתשובה

שלחו שתי בקשות שמתחילות באותו system prompt ארוך והדפיסו את נתוני השימוש של כל אחת. המספר הראשון הוא הקלט של הבקשה, השני הוא החלק ממנו שנקרא מהמטמון.

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

תמחור

טוקני קלט במטמון מחויבים ב-25% מעלות הקלט של המודל, מעוגלים ל-$0.001 ל-1M. כתיבה למטמון אינה עולה דבר, ופלט מחויב כרגיל. תעריף המטמון של כל מזהה מופיע בטבלת Models & pricing. מודלים ותמחור

הקלט של קריאה מחויב כ-(קלט − במטמון) × תעריף קלט + במטמון × תעריף מטמון. הכמות במטמון אף פעם אינה גדולה מכמות הקלט.

יומן השימוש מפרט את הקלט במטמון של כל קריאה. הטוקנים המחויבים והעלות בו כבר כוללים את תעריף המטמון. מפתחות ושימוש

שדות שימוש

{
  "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 והגדרות כלים יציבים (byte-for-byte) בין קריאות. הציבו ערכים המשתנים בכל קריאה, כגון חותמות זמן או מזהי בקשה, בסוף ההודעה האחרונה, ולא ב-system prompt.
• הוסיפו תוכן רק לסוף ההיסטוריה. עריכה, קיצור או סיכום של תורים קודמים משנים את הקידומת, וכל מה שבא לאחר השינוי הראשון מחויב כקלט רגיל.
• אל תשנו את סדר הכלים, ההודעות או בלוקי התוכן בין קריאות, וסדרו JSON (סכמות כלים, ארגומנטים ותוצאות) באותה צורה בכל פעם.
• הישארו עם מזהה מודל אחד לאורך שיחה, ושלחו את הקריאה הבאה זמן קצר אחרי הקודמת.

ה-API שומר על תחילת השיחה יציבה במקרים האלה:

• הודעת system או developer שנשלחת מאוחר יותר בשיחה נשארת במקומה. היא אינה משנה את תחילת הפרומפט, ולכן התורים שלפניה נשארים במטמון.
• הארגומנטים של קריאות לכלים בתורי assistant קודמים מושווים לפי ערך. סדר המפתחות והרווחים ב-JSON הזה לא משנים.
• שלושת ה-endpoints קוראים שיחה באותו אופן. שיחה שממשיכה ב-endpoint אחר שומרת על הקידומת המשותפת שלה כשהתוכן זהה.

שדות בקשה

השדות prompt_cache_key (ב-Chat Completions ו-Responses) ו-cache_control בבלוקי תוכן של הודעות נתמכים, כך שקוד לקוח קיים רץ ללא שינוי. אף אחד מהם אינו חובה: השמירה ב-cache היא אוטומטית ועובדת באותו אופן גם בלעדיהם.

ספירת tokens

שני endpoints חינמיים, POST /v1/tokenize ו-POST /v1/messages/count_tokens, סופרים את הטוקנים של טקסט או של בקשה שלמה עבור מודלי ה-open-weight המתארחים לפני שאתם שולחים אותם. לאלה יש דף משלהם: ספירת טוקנים