التخزين المؤقت للمطالبات

كيف يعمل

• البادئة، بالترتيب — تُقرأ المطالبة بالترتيب: مطالبة النظام، ثم تعريفات الأدوات، ثم الرسائل. تتطابق ذاكرة التخزين المؤقت من بداية هذا التسلسل حتى أول token يختلف.
• ما الذي يُعتبر 'إصابة' (hit) — الطلب الذي تبدأ مطالبته بنفس محتوى طلب حديث — عادةً ما يكون الدور السابق من نفس المحادثة مع إضافة رسائل جديدة. البادئة المتطابقة هي مدخلات مخبأة؛ وكل شيء بعدها هو مدخلات عادية.
• الدقة (Granularity) — تحتفظ ذاكرة التخزين المؤقت بالمطالبة في كتل من 1,568 token، لذا لا تُخزَّن مؤقتاً المطالبة الأقصر من نحو 1,500 token. عدد المخبأ في الرد هو عدد مدخلاتك مضروباً في الحصة المخبأة من المطالبة، مقرباً إلى الأسفل. وليس بالضرورة من مضاعفات حجم الكتلة.
• من دون إصابة — الطلب الذي لا توجد بدايته في ذاكرة التخزين المؤقت يُحاسَب بسعر المدخلات العادي. لا تُنشر مدة بقاء للمطالبات المخبأة والإصابة غير مضمونة: اقرأ usage لمعرفة ما أخذه الطلب من ذاكرة التخزين المؤقت.
• بلا مفتاح تبديل — الطلب لا يشترك في الميزة، ولا يوجد حقل يوقف التخزين المؤقت.
• أي النماذج — كل معرف open-weight مستضاف. يبلغ GET /v1/models عن capabilities.prompt_caching: true و pricing.cached_input_per_million_usd لها. نماذج Shannon تفرض سعرًا موحدًا.

رؤية إصابة التخزين المؤقت في رد

أرسل طلبين يبدآن بنفس توجيهات النظام الطويلة واطبع استخدام كل منهما. الرقم الأول هو مدخلات الطلب، والثاني هو الجزء منها الذي قُرئ من ذاكرة التخزين المؤقت.

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

التسعير

تُحتسب tokens المدخلات المخبأة بنسبة 25% من سعر مدخلات النموذج، مقربة إلى $0.001 لكل 1M. الكتابة في ذاكرة التخزين المؤقت لا تكلف شيئًا إضافيًا، وتُحتسب المخرجات كالمعتاد. سعر التخزين المؤقت لكل معرف موجود في جدول 'النماذج والتسعير'. النماذج والأسعار

تُحاسَب مدخلات الاستدعاء على النحو (المدخلات − المخبأ) × سعر المدخلات + المخبأ × سعر المخبأ. عدد المخبأ لا يكون أبداً أكبر من عدد المدخلات.

يسرد سجل الاستخدام المدخلات المخبأة لكل استدعاء. وتشمل الـ tokens المحاسَبة والتكلفة فيه سعر المخبأ بالفعل. المفاتيح والاستخدام

حقول الاستخدام

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

يحمل الرد المبثوث الحقول نفسها في استخدامه الأخير. لا تحتاج إلى طلبه:

كيفية زيادة إصابات التخزين المؤقت

• حافظ على استقرار مطالبة النظام وتعريفات الأدوات بدقة (byte-for-byte) عبر الاستدعاءات. ضع القيم المتغيرة لكل استدعاء مثل الطوابع الزمنية أو معرفات الطلبات في نهاية الرسالة الأخيرة، وليس في مطالبة النظام.
• قم بالإلحاق بالسجل فقط. إن تحرير أو تقليم أو تلخيص الأدوار السابقة يغير البادئة، وكل شيء بعد أول تغيير يُحتسب كمدخلات عادية.
• لا تعيد ترتيب الأدوات أو الرسائل أو كتل المحتوى بين الاستدعاءات، وقم بتسلسل JSON (مخططات الأدوات، وسيطات الأدوات ونتائجها) بنفس الطريقة في كل مرة.
• ابقَ على معرّف نموذج واحد طوال المحادثة، وأرسل الاستدعاء التالي بعد السابق بوقت قصير.

تُبقي API بداية المحادثة ثابتة في هذه الحالات:

• رسالة system أو developer تُرسل لاحقاً في المحادثة تبقى في مكانها. فهي لا تغيّر بداية المطالبة، لذا تبقى الأدوار التي قبلها مخبأة.
• تُقارن وسائط استدعاءات الأدوات في أدوار المساعد السابقة بالقيمة. ترتيب المفاتيح والمسافات في ذلك JSON لا يهمان.
• تقرأ نقاط النهاية الثلاث المحادثة بالطريقة نفسها. المحادثة التي تُستكمل على نقطة نهاية أخرى تحتفظ ببادئتها المشتركة عندما يكون المحتوى نفسه.

حقول الطلب

يتم قبول prompt_cache_key (في Chat Completions و Responses) و cache_control في كتل محتوى Messages، لذا تعمل أكواد العميل الحالية دون تغيير. كلاهما ليس إلزامياً: فالتخزين المؤقت (caching) تلقائي ويعمل بنفس الطريقة بدونهما.

حساب الـ tokens

نقطتا نهاية مجانيتان، POST /v1/tokenize وPOST /v1/messages/count_tokens، تحسبان tokens نص أو طلب كامل للنماذج المفتوحة الأوزان المستضافة قبل أن ترسله. لها صفحتها الخاصة: عدّ الـ tokens