کش کردن پرامپت

نحوه عملکرد

• پیشوند، به ترتیب — پرامپت به ترتیب زیر خوانده می‌شود: پرامپت سیستم، تعریف ابزارها و سپس پیام‌ها. کش از ابتدای این توالی تا اولین توکنی که متفاوت باشد، مطابقت داده می‌شود.
• چه چیزی Hit محسوب می‌شود — درخواستی که پرامپت آن با محتوای یک درخواست اخیر شروع شود — معمولاً نوبت قبلی از همان گفتگو که پیام‌های جدید به آن اضافه شده است. پیشوند منطبق، ورودی کش‌شده است؛ هر چیزی بعد از آن، ورودی معمولی است.
• دقت (Granularity) — کش یک پرامپت را در بلوک‌های 1,568 توکنی نگه می‌دارد، پس پرامپتی کوتاه‌تر از حدود 1,500 توکن کش نمی‌شود. تعداد کش‌شده در پاسخ برابر تعداد ورودی شما ضربدر سهم کش‌شده پرامپت است، گرد شده به پایین. لزوماً مضربی از اندازه بلوک نیست.
• بدون Hit — درخواستی که ابتدایش در کش نیست با نرخ عادی ورودی محاسبه می‌شود. برای پرامپت‌های کش‌شده مدت ماندگاری منتشر نشده و Hit تضمین‌شده نیست: usage را بخوانید تا ببینید یک درخواست چه مقدار را از کش گرفته است.
• بدون کلید فعال/غیرفعال — درخواست نیازی به فعال‌سازی ندارد و هیچ فیلدی کش را خاموش نمی‌کند.
• کدام مدل‌ها — تمام شناسه‌های hosted open-weight. متد GET /v1/models مقادیر capabilities.prompt_caching: true و pricing.cached_input_per_million_usd را برای آن‌ها گزارش می‌دهد. مدل‌های Shannon یک نرخ ثابت دارند.

دیدن یک Hit کش در پاسخ

دو درخواست بفرستید که با یک system prompt طولانی یکسان شروع می‌شوند و 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

قیمت‌گذاری

توکن‌های ورودی کش‌شده با ۲۵٪ نرخ ورودی مدل محاسبه شده و به $0.001 per 1M گرد می‌شوند. نوشتن در کش هزینه اضافی ندارد و خروجی طبق معمول محاسبه می‌شود. نرخ کش هر شناسه در جدول «مدل‌ها و قیمت‌گذاری» موجود است. مدل‌ها و قیمت‌ها

ورودی یک فراخوانی به این صورت محاسبه می‌شود: (ورودی − کش‌شده) × نرخ ورودی + کش‌شده × نرخ کش‌شده. تعداد کش‌شده هیچ‌وقت از تعداد ورودی بزرگ‌تر نیست.

گزارش مصرف ورودی کش‌شده هر فراخوانی را فهرست می‌کند. توکن‌های محاسبه‌شده و هزینه آن از قبل نرخ کش‌شده را در بر می‌گیرند. کلیدها و مصرف

فیلدهای استفاده

{
  "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 پایانی خود دارد. لازم نیست آن را درخواست کنید:

افزایش نرخ Hit کش

• پرامپت سیستم و تعریف ابزارها را در تمام فراخوانی‌ها دقیقاً یکسان نگه دارید. مقادیر متغیر مانند Timestamp یا ID درخواست‌ها را در انتهای آخرین پیام قرار دهید، نه در پرامپت سیستم.
• فقط به تاریخچه پیام‌ها اضافه کنید (Append). ویرایش، کوتاه کردن یا خلاصه‌سازی نوبت‌های قبلی، پیشوند را تغییر می‌دهد و هر چیزی بعد از اولین تغییر، به عنوان ورودی معمولی محاسبه می‌شود.
• ترتیب ابزارها، پیام‌ها یا بلوک‌های محتوا را بین فراخوانی‌ها تغییر ندهید و JSONها (طرح‌واره ابزارها، آرگومان‌ها و نتایج) را هر بار به یک شکل سریالایز کنید.
• در یک گفتگو روی یک شناسه مدل بمانید و فراخوانی بعدی را کمی پس از قبلی بفرستید.

API در این موارد ابتدای گفتگو را ثابت نگه می‌دارد:

• پیام system یا developer که بعداً در گفتگو فرستاده شود در جای خودش می‌ماند. ابتدای پرامپت را تغییر نمی‌دهد، پس نوبت‌های پیش از آن کش‌شده می‌مانند.
• آرگومان‌های فراخوانی ابزار در نوبت‌های قبلی assistant بر اساس مقدار مقایسه می‌شوند. ترتیب کلیدها و فاصله‌گذاری آن JSON اهمیتی ندارد.
• این سه endpoint یک گفتگو را یکسان می‌خوانند. گفتگویی که روی endpoint دیگری ادامه یابد، اگر محتوا یکی باشد پیشوند مشترک خود را حفظ می‌کند.

فیلدهای درخواست

فیلدهای prompt_cache_key (در Chat Completions و Responses) و cache_control در بلوک‌های محتوای Messages پذیرفته شده‌اند، بنابراین کدهای فعلی کلاینت بدون تغییر اجرا می‌شوند. هیچ‌کدام الزامی نیستند: کشینگ خودکار است و بدون آن‌ها نیز به همین شکل عمل می‌کند.

شمارش توکن‌ها

دو endpoint رایگان، POST /v1/tokenize و POST /v1/messages/count_tokens، پیش از ارسال، توکن‌های یک متن یا کل یک درخواست را برای مدل‌های open-weight میزبانی‌شده می‌شمارند. آن‌ها صفحه خودشان را دارند: شمارش توکن