د پرامپټ کیشینگ

دا څنګه کار کوي

• پری-فکس، په ترتیب سره — پرامپټ په ترتیب سره لوستل کیږي: سیسټم پرامپټ، د ټولز تعریفونه، او بیا پیغامونه. کیش د دې ترتیب څخه تر هغه لومړي ټوکن پورې چې توپیر ولري، میچ کیږي.
• څه شی 'hit'-شوي شميرل کیږي — یو ریکویسټ چې پرامپټ یې د یو अली-ناست ریکویسټ په څیر پیل کیږي — معمولاً د یوې خبرو-مصالنې تکرار چې نوي پیغامونه ورسره زیات شوي وي. میچ شوی پری-فکس 'کیش-شوی انپوټ' دی؛ او تر هغه وروسته هرڅه عادي انپوټ دی.
• د تفصیلو کچه (Granularity) — Cache prompt د 1,568 ټوکنونو په blocks کې ساتي، نو هغه prompt چې له شاوخوا 1,500 ټوکنونو لنډ وي cache نه کیږي. په ځواب کې د cached شمیر ستاسو د input شمیر دی چې د prompt په cached ونډه ضرب شوی او ښکته ګردول شوی. دا اړینه نه ده چې د block اندازې ضرب وي.
• پرته له hit — هغه غوښتنه چې پیل یې په cache کې نه وي په منظم input rate بیل کیږي. د cached prompts لپاره هیڅ عمر نه دی خپور شوی او hit تضمین نه دی: usage ولولئ چې وګورئ غوښتنې له cache څخه څه واخیستل.
• هیڅ سویچ نشته — غوښتنه opt in نه کوي، او هیڅ ساحه caching نه بندوي.
• کوم مودلونه — هر hosted open-weight id. د GET /v1/models په-پاسه capabilities.prompt_caching: true او pricing.cached_input_per_million_usd راپور ورکوي. Shannon مودلونه یو ثابت نرخ لري.

په ځواب کې cache hit وګورئ

دوه غوښتنې ولیږئ چې په هماغه اوږد system prompt پیلیږي او د هرې usage چاپ کړئ. لومړی شمیر د غوښتنې input دی، دویم یې هغه برخه ده چې له 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

بیې

کیش-شوي انپوټ ټوکنونه د مودل د انپوټ د نرخ په ۲۵٪ بیلاګیږي، چې تر $0.001 per 1M پورې راوګوړ کیږي. کیش ته لیکل هیڅ اضافي لګښت نلري، او اوټپوټ په عادي ډول بیلاګیږي. د هر id کیش-نرخ په Models & pricing جدول کې دی. ماډلونه او بیې

د یوې غوښتنې input داسې محاسبه کیږي: (input − cached) × input rate + cached × cached rate. د cached شمیر هیڅکله د input له شمیر لوی نه وي.

د usage log د هرې غوښتنې cached input لیست کوي. د بیل شوي ټوکنونه او لګښت یې دمخه cached rate پکې شامل دی. کیلي او کارونه

د کارولو ساحې

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

stream شوی ځواب په خپل وروستي usage کې هماغه ساحې لري. تاسو اړتیا نه لرئ چې غوښتنه یې وکړئ:

د کیش-هټونو (cache hits) زیاتول

• سیسټم پرامپټ او د ټولز تعریفونه په کالونو کې په دقیق ډول ثابته وساتئ. د کال-پو-کال قیمتونه لکه timestamps یا request ids د وروستۍ پیغام په پای کې کېږدئ، نه په سیسټم پرامپټ کې.
• یوازې تاریخ (history) ته پیغامونه زیاتوئ. د پخوانیوTurns ایډیټ کول، لنډول یا خلاصه کول پری-فکس بدلوي، او د لومړي بدلون څخه وروسته هرڅه د عادي انپوټ په توګه بیلاګیږي.
• د کالونو ترمنځ د ټولز، پیغامونو یا موادو ترتیب مه بدلوئ، او JSON (tool schemas, tool arguments and results) هر ځل په یو ډول سریالای de.
• د یوې ګفتګو لپاره په یو ماډل id پاتې شئ، او راتلونکې غوښتنه د مخکینۍ سمدلاسه وروسته ولیږئ.

API په دې قضیو کې د ګفتګو پیل ثابت ساتي:

• system یا developer message چې وروسته په ګفتګو کې لیږل کیږي په خپل ځای پاتې کیږي. دا د prompt پیل نه بدلوي، نو مخکینۍ turns cached پاتې کیږي.
• په پخوانیو assistant turns کې د tool calls آرګومنټونه د ارزښت له مخې پرتله کیږي. د دې JSON د کلیدونو ترتیب او فاصلې مهمې نه دي.
• درې endpoints یو ګفتګو په یو ډول لولي. ګفتګو چې په بل endpoint کې دوام ومومي، خپل ګډ prefix ساتي کله چې منځپانګه یو شان وي.

د غوښتنې ساحې (Request fields)

prompt_cache_key (Chat Completions او Responses) او cache_control په Messages content blocks کې ومنل کېږي، نو موجوده client code پرته له بدلون څخه کار کوي. هیڅ یو یې اړین نه دی: caching اتوماتیک دی او پرته له هغوی هم ورسره کار کوي.

د tokens شمېرنه

دوه وړیا endpoints، POST /v1/tokenize او POST /v1/messages/count_tokens، مخکې له لیږلو د کوربه شوو open-weight ماډلونو لپاره د متن یا بشپړې غوښتنې ټوکنونه شمیري. دوی خپله جلا پاڼه لري: د ټوکنونو شمېرنه