پرامپٹ کیشنگ

یہ کیسے کام کرتا ہے

• پریفکس، ترتیب کے مطابق — پرامپٹ ترتیب وار پڑھا جاتا ہے: سسٹم پرامپٹ، ٹول ڈیفینیشنز، اور پھر پیغامات۔ کیش اس ترتیب کے آغاز سے لے کر پہلے اس ٹوکن تک میچ کرتا ہے جو مختلف ہو۔
• ہٹ (hit) کب شمار ہوتا ہے — ایک ایسی ریکویسٹ جس کا پرامپٹ حالیہ ریکویسٹ کے مواد سے شروع ہوتا ہے — عام طور پر اسی گفتگو کا پچھلا مرحلہ جس میں نئے پیغامات شامل کیے گئے ہوں۔ میچنگ پریفکس کیشڈ ان پٹ ہے؛ اس کے بعد کی ہر چیز ریگولر ان پٹ ہے۔
• گرانولرٹی (Granularity) — کیش پرامپٹ کو 1,568 ٹوکنز کے بلاکس میں رکھتا ہے، اس لیے تقریباً 1,500 ٹوکنز سے چھوٹا پرامپٹ کیش نہیں ہوتا۔ جواب میں کیشڈ گنتی آپ کی ان پٹ گنتی کو پرامپٹ کے کیشڈ حصے سے ضرب دے کر نیچے کی طرف گول کرنے سے آتی ہے۔ یہ لازماً بلاک سائز کا ضرب نہیں ہوتی۔
• ہٹ کے بغیر — جس درخواست کا آغاز کیش میں نہ ہو اس کا بل عام ان پٹ نرخ پر بنتا ہے۔ کیشڈ پرامپٹس کی کوئی میعاد شائع نہیں کی گئی اور ہٹ کی ضمانت نہیں: usage پڑھ کر دیکھیں کہ درخواست نے کیش سے کیا لیا۔
• کوئی سوئچ نہیں — درخواست اسے آپٹ ان نہیں کرتی، اور کوئی فیلڈ کیشنگ بند نہیں کرتی۔
• کون سے ماڈلز — ہر ہوسٹڈ اوپن ویٹ id۔ GET /v1/models ان کے لیے capabilities.prompt_caching: true اور pricing.cached_input_per_million_usd کی رپورٹ کرتا ہے۔ Shannon ماڈلز ایک فلیٹ ریٹ پر بل کرتے ہیں۔

جواب میں کیش ہٹ دیکھیں

دو درخواستیں بھیجیں جو ایک ہی لمبے سسٹم پرامپٹ سے شروع ہوں اور ہر ایک کا usage پرنٹ کریں۔ پہلا عدد درخواست کا ان پٹ ہے، دوسرا اس کا وہ حصہ ہے جو کیش سے پڑھا گیا۔

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 per 1M تک راؤنڈ کیا جاتا ہے۔ کیش میں لکھنے کی کوئی اضافی قیمت نہیں ہے، اور آؤٹ پٹ معمول کے مطابق بل کیا جاتا ہے۔ ہر id کا کیشڈ ریٹ Models & pricing ٹیبل میں ہے۔ ماڈلز اور قیمتیں

کال کے ان پٹ کا چارج اس طرح لگتا ہے: (ان پٹ − کیشڈ) × ان پٹ نرخ + کیشڈ × کیشڈ نرخ۔ کیشڈ گنتی کبھی ان پٹ کی گنتی سے زیادہ نہیں ہوتی۔

usage لاگ ہر کال کا کیشڈ ان پٹ دکھاتا ہے۔ اس کے بل شدہ ٹوکنز اور لاگت میں کیشڈ نرخ پہلے ہی شامل ہے۔ Keys & usage

استعمال کے فیلڈز

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

سٹریم کیا گیا جواب اپنے آخری usage میں یہی فیلڈز رکھتا ہے۔ آپ کو اسے مانگنے کی ضرورت نہیں:

کیش ہٹس بڑھانے کے طریقے

• کالز کے دوران سسٹم پرامپٹ اور ٹول ڈیفینیشنز کو بائٹ-بائٹ مستحکم رکھیں۔ فی-کال ویلیوز جیسے ٹائم اسٹیمپ یا ریکویسٹ ids کو آخری پیغام کے آخر میں رکھیں، سسٹم پرامپٹ میں نہیں۔
• صرف ہسٹری میں اضافہ (append) کریں۔ سابقہ مراحل کی ایڈیٹنگ، ٹرمنگ یا خلاصہ کرنے سے پریفکس تبدیل ہو جاتا ہے، اور پہلی تبدیلی کے بعد کی ہر چیز ریگولر ان پٹ کے طور پر بل کی جاتی ہے۔
• کالز کے درمیان ٹولز، پیغامات یا مواد کے بلاکس کی ترتیب تبدیل نہ کریں، اور JSON (ٹول اسکیماز، ٹول آرگیومنٹ اور نتائج) کو ہر بار ایک ہی طریقے سے سیریلائز کریں۔
• ایک گفتگو کے لیے ایک ہی ماڈل id پر رہیں، اور اگلی کال پچھلی کال کے فوراً بعد بھیجیں۔

API ان صورتوں میں گفتگو کا آغاز مستحکم رکھتی ہے:

• گفتگو میں بعد میں بھیجا گیا system یا developer پیغام اپنی جگہ پر رہتا ہے۔ یہ پرامپٹ کا آغاز تبدیل نہیں کرتا، اس لیے اس سے پہلے کے ٹرنز کیشڈ رہتے ہیں۔
• پچھلے assistant ٹرنز میں ٹول کالز کے آرگیومنٹس قدر کے لحاظ سے موازنہ کیے جاتے ہیں۔ اس JSON میں کیز کی ترتیب اور خالی جگہوں سے فرق نہیں پڑتا۔
• تینوں endpoints گفتگو کو ایک ہی طرح پڑھتے ہیں۔ دوسرے endpoint پر جاری رکھی گئی گفتگو، مواد وہی ہو تو، اپنا مشترکہ پریفکس برقرار رکھتی ہے۔

درخواست کے فیلڈز

prompt_cache_key (Chat Completions اور Responses) اور Messages مواد کے بلاکس پر cache_control قبول کیے جاتے ہیں، تاکہ موجودہ کلائنٹ کوڈ بغیر تبدیلی کے چلے۔ دونوں ضروری نہیں ہیں: کیشنگ خودکار ہے اور ان کے بغیر بھی اسی طرح کام کرتی ہے۔

ٹکنز کی گنتی

دو مفت endpoints، POST /v1/tokenize اور POST /v1/messages/count_tokens، بھیجنے سے پہلے ہوسٹڈ اوپن ویٹ ماڈلز کے لیے کسی متن یا پوری درخواست کے ٹوکنز گنتے ہیں۔ ان کا اپنا صفحہ ہے: ٹوکن گنتی