شروع کار

کش پرامپت

چگونه بخش ثابت پرامپت را علامت بزنید، هزینه‌ی خواندن و نوشتن کش چگونه حساب می‌شود و cached_tokens کجا دیده می‌شود.

کش پرامپت برای درخواست‌هایی است که یک ابتدای بلند و ثابت دارند (دستور سیستم، سند، تعریف ابزارها). مدل پردازش آن بخش را از کش می‌خواند و ورودی خوانده‌شده از کش ارزان‌تر حساب می‌شود.

علامت زدن با cache_control

در مدل‌هایی که کش علامت‌گذاری‌شده دارند، روی بلوکی که کش تا آنجا ادامه پیدا می‌کند cache_control بگذارید:

json
{
  "model": "anthropic/claude-sonnet-5.5",
  "messages": [
    {
      "role": "system",
      "content": [
        { "type": "text", "text": "<a long, stable system prompt>", "cache_control": { "type": "ephemeral" } }
      ]
    },
    { "role": "user", "content": "Summarize section 3." }
  ]
}

علامت {"type": "ephemeral"} کش کوتاه‌مدت است. با "ttl": "1h" کش یک‌ساعته می‌خواهید. cache_control روی /v1/chat/completions و /v1/messages پذیرفته می‌شود و روی بلوک‌های پیام، دستور سیستم و تعریف ابزارها می‌نشیند. بعضی مدل‌ها بدون علامت هم کش خودکار دارند. در آن‌ها هم خواندن از کش در usage دیده می‌شود. تأثیر علامت به مدل بستگی دارد؛ تعیین‌کننده، عددهای usage پاسخ است.

cached_tokens در usage

توکن‌های خوانده‌شده و نوشته‌شده در کش داخل prompt_tokens هستند و جدا هم گزارش می‌شوند:

json
{
  "usage": {
    "prompt_tokens": 2048,
    "completion_tokens": 120,
    "total_tokens": 2168,
    "prompt_tokens_details": { "cached_tokens": 1792, "cache_write_tokens": 0 }
  }
}
  • cached_tokens: چند توکن از ورودی از کش خوانده شد.
  • cache_write_tokens: چند توکن در این درخواست در کش نوشته شد. فقط وقتی بزرگ‌تر از صفر است می‌آید.
  • cache_creation.ephemeral_1h_input_tokens: بخشی از نوشته‌ها که کش یک‌ساعته بودند.

در قالب Anthropic (/v1/messages) همین دو عدد با نام cache_read_input_tokens و cache_creation_input_tokens برمی‌گردند. در /v1/responses در input_tokens_details هستند.

هزینه

  • ورودی خوانده‌شده از کش با قیمت cached_input_1k مدل حساب می‌شود.
  • ورودی نوشته‌شده در کش با cache_write_1k (و برای کش یک‌ساعته با cache_write_1k:1h) حساب می‌شود.
  • بقیه‌ی ورودی با input_1k.
  • اگر مدل قیمت جدا برای کش نداشته باشد، آن بخش با قیمت عادی ورودی حساب می‌شود.

قیمت‌ها در pricing مدل (GET /v1/models) هستند. نوشتن در کش معمولاً گران‌تر از ورودی عادی است و خواندن ارزان‌تر، پس برای پرامپتی که فقط یک بار می‌فرستید کش فایده ندارد.

رزرو اعتبار با علامت کش

اگر درخواست علامت cache_control داشته باشد، رزرو اعتبار پیش از اجرا فرض می‌کند همه‌ی ورودی در کش نوشته می‌شود (با نرخ یک‌ساعته اگر ttl یک ساعت خواسته شده)، و پس از تسویه مازاد برمی‌گردد. هیچ‌وقت فرض نمی‌شود که کش خوانده خواهد شد. پس برای درخواست دارای علامت، موجودی کمی بیشتر از هزینه‌ی نهایی لازم است.

محدودیت نرخ

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

چیزی که حساب نمی‌شود

بعضی مدل‌ها بالای یک اندازه‌ی مشخص پرامپت نرخ بالاتری دارند. این افزایش فعلاً در هزینه‌ی درخواست اعمال نمی‌شود.

صفحه‌های مرتبط