کەشراوکردنی پرۆمپت

چۆن کار دەکات

• پێشینە، بە ڕیزبەندی — پرۆمپتەکە بە ڕیزبەندی دەخوێندرێتەوە: پرۆمپتی سیستم، پێناسەی ئامرازەکان، و پاشان نامەکان. کەشەکە لە سەرەتای ئەو ڕیزبەندییەوە دەست پێ دەکات تا دەگاتە یەکەم تۆکن کە جیاواز بێت.
• چی وەک 'hit' هەژمار دەکرێت — داخواستێک کە پرۆمپتەکەی بە هەمان ناوەڕۆکی داخواستێکی ڕایەکی دەست پێ بکات — بەتایبەت گەڕانەوەی پێشوەختەی هەمان گفتوگۆ کە نامەی نوێی لێی زیاد کرابێت. پێشینەی گونجاوەکە بریتییە لە ناوەڕۆکی کەشراو؛ هەموو شتێکی تری دوای ئەوە ناوەڕۆکی ئاساییە.
• وردەکاری (Granularity) — cache ـەکە prompt لە block ی 1,568 تۆکنی دەگرێت، بۆیە prompt ێک کورتتر لە نزیکەی 1,500 تۆکن cache ناکرێت. ژمارەی cached لە وەڵامێکدا ژمارەی input ـەکەتە بەرانبەر بەشی cached ی prompt ەکە، بەرەو خوارەوە خڕکراوەتەوە. پێویست نییە چەند هێندەی قەبارەی block بێت.
• بێ hit — داواکارییەک کە سەرەتاکەی لە cache دا نییە بە نرخی ئاسایی input حیساب دەکرێت. هیچ ماوەیەک بۆ prompt ی cache کراو بڵاو نەکراوەتەوە و hit گەرەنتی نەکراوە: usage بخوێنەرەوە بۆ بینینی ئەوەی داواکارییەک لە cache ی وەرگرتووە.
• هیچ گۆڕەک نییە — داواکارییەک بە ئارەزووی خۆی تێیدا بەشدار نابێت، و هیچ field ێک cache ناکوژێنێتەوە.
• کدام مۆدێلەکان — هەموو ئایدی-یەکانی hosted open-weight. 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

نرخاندن

تۆکنەکانی ناوەڕۆکی کەشراو بە ٢٥٪ی نرخی ناوەڕۆکی مۆدێلەکە هەژمار دەکرێن، کە بۆ هەر 1M دەگاتە $0.001. نووسین لە کەشەکەدا هیچ تێچووی زیادەی نییە، و دەرەورە بە شێوەیەکی ئاسایی هەژمار دەکرێت. نرخی کەشراوی هەر ئایدییەک لە خشتەی 'مۆدێلەکان و نرخاندن'دایە. مۆدێل و نرخ

input ی بانگکردنێک بەم شێوەیە حیساب دەکرێت (input − cached) × نرخی input + cached × نرخی cached. ژمارەی cached هەرگیز لە ژمارەی input گەورەتر نییە.

تۆماری usage ی input ی cache کراوی هەر بانگکردنێک لیست دەکات. تۆکنە حیسابکراوەکان و تێچووەکەی پێشتر نرخی cached لەخۆدەگرن. 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
  }
}

وەڵامی stream کراو هەمان field ەکان لە usage ی کۆتاییدا هەڵدەگرێت. پێویست ناکات داوای بکەیت:

چۆنیەتی زیادکردنی hit-ەکانی کەش

• پرۆمپتی سیستم و پێناسەی ئامرازەکان بە تەواوی جێگیر ڕابگرە لە نێوان بانگاوەکاندا. بەهاکانی هەر بانگاوێک وەک ستامپی کات یان ئایدی-یەکانی داخواست لە کۆتایی نوێترین نامە دابنێ، نەک لە پرۆمپتی سیستمدا.
• تەنها لە کۆتایی مێژووەکە زیاد بکە. دەستکاریکردن، کورتکردنەوە یان کورتکردنەوەی گەڕانەوەکانی پێشوو پێشینەکە دەگۆڕێت، و هەموو شتێکی دوای یەکەم گۆڕانکاری وەک ناوەڕۆکی ئاسایی هەژمار دەکرێت.
• ڕیزبەندی ئامرازەکان، نامەکان یان بلۆکەکانی ناوەڕۆک لە نێوان بانگاوەکاندا مەگۆڕە، و JSON-ەکان (سکیمای ئامرازەکان، ئارگیومێنتەکان و ئەنجامەکان) هەموو جارێک بە هەمان شێوە سێراییز بکە.
• بۆ گفتوگۆیەک لەسەر یەک id ی مۆدێل بمێنەرەوە، و بانگکردنی دواتر بە زوویی دوای ئەوی پێشوو بنێرە.

API سەرەتای گفتوگۆیەک لەم حاڵەتانەدا جێگیر دەهێڵێتەوە:

• نامەی system یان developer کە دواتر لە گفتوگۆیەکدا دەنێردرێت لە شوێنی خۆی دەمێنێتەوە. سەرەتای prompt ناگۆڕێت، بۆیە ئەو نۆبەتانەی پێش ئەو cache کراو دەمێننەوە.
• ئارگیومێنتەکانی بانگکردنی ئامراز لە نۆبەتەکانی پێشووی assistant بە بەها بەراورد دەکرێن. ڕیزبەندی کلیلەکان و بۆشایی ئەو JSON ـە گرنگ نییە.
• سێ endpoint ەکە گفتوگۆیەک بە هەمان شێوە دەخوێننەوە. گفتوگۆیەک کە لەسەر endpoint ێکی تر بەردەوام بێت، کاتێک ناوەڕۆکەکە هەمان بێت، پێشگری هاوبەشەکەی دەپارێزێت.

کۆمەڵەی fields-ەکانی داوا

prompt_cache_key (بۆ Chat Completions و Responses) و cache_control لەسەر content blocks-ەکانی Messages دەپێورێن، بۆیە کۆدی client-ی هەستاو بەبێ گۆڕانکاری دەخاتە ڕێگەی گەڕانەوە. هیچ کامێکیان پێویست نین: caching خۆکارە و بەبێ ئەوانەش بە هەمان شێوە کار دەکات.

ژماردنی tokens

دوو endpoint ی بێبەرامبەر، POST /v1/tokenize و POST /v1/messages/count_tokens، تۆکنەکانی دەقێک یان داواکارییەکی تەواو بۆ مۆدێلە open-weight هۆستکراوەکان پێش ناردنی دەژمێرن. لاپەڕەی تایبەتی خۆیان هەیە: هەژمارکردنی تۆکن