کش پرامپت در API کلود: راهنمای فعال‌سازی و محاسبه هزینه

اگر هر درخواست شما با یک پرامپت سیستم بلند و فهرست ابزارها شروع می‌شود، دارید همان ورودی را بارها گران می‌خرید. کش پرامپت این بخش تکراری را نگه می‌دارد و دفعه‌های بعد با حدود یک‌دهم قیمت (در بعضی مدل‌ها کمتر) حساب می‌کند. در مثال همین مطلب، هزینه ورودی ۱۰۰ درخواست از ۸ دلار به کمتر از نیم دلار می‌رسد. اطلاعات و قیمت‌ها تا ۱۹ اکتبر ۲۰۲۶ از مستندات رسمی گرفته شده‌اند.

کش پرامپت دقیقاً چه چیزی را نگه می‌دارد؟

درخواست شما به ترتیب از سه بخش ساخته می‌شود: tools، بعد system، بعد messages. کش از ابتدای این زنجیره تا بلوکی را می‌گیرد که روی آن cache_control گذاشته‌اید. درخواست بعدی اگر با همین پیشوند شروع شود، آن بخش را از کش می‌خواند. خروجی مدل تغییری نمی‌کند، فقط قیمت و سرعت ورودی فرق می‌کند.

کلمه مهم «پیشوند» است. کش فقط از ابتدا کار می‌کند. اگر بلوکی وسط پرامپت عوض شود، از همان نقطه به بعد دیگر خوانده نمی‌شود.

دو روش فعال‌سازی

روش اول خودکار است. یک فیلد cache_control در سطح بالای درخواست می‌گذارید و نقطه کش با رشد گفتگو خودش به آخرین بلوک قابل‌کش می‌رود. برای چت‌بات‌ها و ایجنت‌های چندمرحله‌ای همین کافی است:

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},
    system="پرامپت سیستم بلند و ثابت شما",
    messages=[{"role": "user", "content": "سؤال کاربر"}],
)
print(response.usage)

روش دوم صریح است: cache_control را روی بلوک‌های مشخص می‌گذارید، تا ۴ نقطه. کش خودکار هم یکی از همین ۴ جا را مصرف می‌کند. این روش وقتی به کار می‌آید که بخش‌های پرامپت با سرعت‌های متفاوت عوض می‌شوند. مثلاً ابزارها هفته‌ها ثابت‌اند، پرامپت سیستم روزی یک بار عوض می‌شود و پیام‌ها هر لحظه.

قیمت: نوشتن گران‌تر، خواندن بسیار ارزان‌تر

قیمت‌ها نسبت به قیمت پایه ورودی سنجیده می‌شوند:

• نوشتن کش با عمر ۵ دقیقه: ۱٫۲۵ برابر.
• نوشتن کش با عمر یک ساعت ("ttl": "1h"): ۲ برابر.
• خواندن کش: ۰٫۱ برابر.

چند استثنا در خواندن وجود دارد: در Opus 5.5 و Sonnet 5.5 فقط ۰٫۰۵ برابر است و در Fable 5.1 و Mythos 5.1 فقط ۰٫۰۲۵ برابر. عمر پیش‌فرض کش ۵ دقیقه است و هر بار که از آن استفاده کنید، بدون هزینه تمدید می‌شود.

یک محاسبه واقعی

فرض کنید پرامپت سیستم شما ۲۰ هزار توکن است و ۱۰۰ بار پشت سر هم، با فاصله کمتر از ۵ دقیقه، استفاده می‌شود. فقط هزینه همین بخش ثابت را حساب می‌کنیم. قیمت‌ها از اعلام رسمی Haiku 5.5 و Opus 5.5 است (Haiku تا ۱۰۰ هزار توکن). محاسبه را با یک اسکریپت کوچک انجام دادم.

در Haiku 5.5 قیمت ورودی ۰٫۱۰ دلار، نوشتن کش ۰٫۱۲۵ و خواندن کش ۰٫۰۱ دلار در هر میلیون توکن است:

• بدون کش: ۲ میلیون توکن با قیمت ۰٫۱۰ دلار در هر میلیون می‌شود ۰٫۲۰۰۰ دلار.
• با کش: یک بار نوشتن (۰٫۰۰۲۵ دلار) به‌علاوه ۹۹ بار خواندن (۰٫۰۱۹۸ دلار) می‌شود ۰٫۰۲۲۳ دلار. صرفه‌جویی حدود ۸۹ درصد.

در Opus 5.5 قیمت ورودی ۴ دلار، نوشتن کش ۵ و خواندن ۰٫۲۰ دلار در هر میلیون توکن است:

• بدون کش: ۸٫۰۰۰۰ دلار.
• با کش: ۰٫۴۹۶۰ دلار. صرفه‌جویی حدود ۹۳٫۸ درصد.

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

حداقل طول پرامپت

اگر پرامپت از حداقل مدل کوتاه‌تر باشد، کش نمی‌شود و خطایی هم نمی‌گیرید، فقط سودی نمی‌برید. حداقل‌ها طبق مستندات:

• ۵۱۲ توکن: Opus 5.5، Opus 5، Sonnet 5.5 و Haiku 5.5.
• ۱٬۰۲۴ توکن: Sonnet 5، Sonnet 4.6 و Opus 4.8.
• ۲٬۰۴۸ توکن: Opus 4.7.
• ۴٬۰۹۶ توکن: Opus 4.5، Opus 4.6 و Haiku 4.5.

چطور مطمئن شوم کار می‌کند؟

دو بار یک درخواست با پیشوند یکسان بفرستید و usage را ببینید:

• cache_creation_input_tokens: توکن‌هایی که همین درخواست در کش نوشته است.
• cache_read_input_tokens: توکن‌هایی که از کش خوانده شده است.
• input_tokens: توکن‌های بعد از آخرین نقطه کش.

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

چه چیزی کش را باطل می‌کند؟

• تغییر تعریف ابزارها (نام، توضیح، پارامترها): همه چیز باطل می‌شود، یعنی ابزارها و سیستم و پیام‌ها.
• تغییر پرامپت سیستم: سیستم و پیام‌ها باطل می‌شوند.
• تغییر tool_choice، اضافه یا حذف شدن تصویر، یا تغییر تنظیمات تفکر و effort: بخش پیام‌ها باطل می‌شود.

یک اشتباه رایج: تاریخ و ساعت یا شناسه درخواست را در ابتدای پرامپت سیستم می‌گذارند. این بخش هر بار فرق می‌کند، پس هر بار هزینه نوشتن می‌دهید و هیچ‌وقت خواندن ارزان نمی‌بینید. هر چیز متغیر را بعد از آخرین نقطه کش بگذارید.

کش و ابزارهای MCP

فهرست ابزارها اولین بخش پیشوند است، پس هر تغییرش کل کش را می‌سوزاند. اگر ایجنت شما سرورهای MCP را یکی‌یکی وصل می‌کند و کاربر وسط کار سرویسی اضافه یا حذف می‌کند، فهرست ابزارها عوض می‌شود و کش از اول ساخته می‌شود.

روتر MCP همین مشکل را به شکل دیگری حل می‌کند. روتر همیشه فقط دو ابزار ثابت دارد، search_tools و call_tool، و سرویس‌های واقعی پشت آن‌اند. پس تغییر سرویس‌ها در داشبورد فهرست ابزارهای مدل را عوض نمی‌کند و بخش ابتدایی پرامپت ثابت می‌ماند. این یک ویژگی طراحی روتر است و به معنی کش خودکار نیست: خود شما باید cache_control را فعال کنید. نتیجه فراخوانی ابزارها هم به پیام‌ها اضافه می‌شود و آن بخش طبیعتاً تغییر می‌کند. توضیح کامل روتر در مطلب روتر MCP آمده است. تفاوت MCP با فراخوانی تابع در API را در مقایسه MCP و function calling ببینید و اگر با خود MCP تازه آشنا شده‌اید، MCP چیست را بخوانید.

برای شروع با سرویس‌های ایرانی

اگر ایجنتی می‌سازید که با دیوار یا دیجی‌کالا کار می‌کند، راهنمای شروع نشانی روتر و مسیر تنظیم هر برنامه را نشان می‌دهد. برای امتحان سریع بدون ساخت حساب هم می‌توانید از صفحه رایگان یا محیط آزمایش استفاده کنید. فعال‌کردن کش در کد خودتان است و به روتر ربطی ندارد.

بقیه ارائه‌دهنده‌ها

ارائه‌دهنده‌های دیگر، از جمله OpenAI، هم کش دارند، اما ضریب قیمت و شرط فعال‌سازی‌شان با Anthropic فرق می‌کند. در این مطلب برایشان عدد نمی‌دهم، چون منبع رسمی را بررسی نکرده‌ام. مستندات هر ارائه‌دهنده را جداگانه بخوانید. اگر مدل‌های تازه را مقایسه می‌کنید، مطلب مدل‌های هوش مصنوعی در مهر ۱۴۰۵ می‌تواند کمک کند.

یک نکته آخر درباره جداسازی: کش بین سازمان‌ها مشترک نیست و در Claude API بین workspaceها هم جداست. پس برای آزمایش و محیط واقعی که در دو workspace هستند، هر کدام کش خودش را گرم می‌کند.