المستوى: متوسط — يفترض إنك مستخدم Anthropic SDK قبل كده وعارف يعني إيه system prompt و input tokens و request lifecycle.
Prompt Caching في Claude: ليه بتدفع 10x على نفس التوكنز كل request؟
لو شات بوت دعم فني عندك بيبعت لـ Claude نفس الـ system prompt كل مرة (دليل سياسات الشركة، few-shot examples، تعليمات الصياغة) بطول 5000 توكن، ومستخدميك بيسألوه 2000 سؤال يومياً، أنت بتدفع 10 مليون توكن إدخال شهرياً على نص واحد متغيرش. Prompt Caching بينزّل ده لمليون توكن مدفوع — تقريباً 84% توفير حقيقي — بإضافة سطر JSON واحد على الـ payload.
المشكلة باختصار
كل ما بتبعت request لـ Claude، الموديل بيعالج الـ system prompt من الصفر، حتى لو هو نفسه بالحرف من الـ request اللي قبله بـ 3 ثواني. مفيش "ذاكرة" بين الـ requests افتراضياً. ده معناه حاجتين:
- بتدفع على نفس التوكنز ألف مرة في اليوم.
- زمن أول توكن (TTFT) بيزيد لأن الموديل بيـ pre-fill الـ KV vectors لكل توكن من الأول.
على system prompt 5000 توكن، الـ pre-fill لوحده بياخد 1.5 لـ 2.5 ثانية على Claude Sonnet 4.6 قبل ما الموديل يبدأ يولّد أول حرف للمستخدم.
ازاي Prompt Caching بيشتغل (مثال للمبتدئ)
تخيل مكتب بريد بيستلم 2000 طرد يومياً، وكل الطرود لنفس الحي: "مدينة نصر، الحي السابع". الموظف العادي بيكتب اسم الحي والعنوان كامل من الأول لكل طرد، فبياخد دقيقتين في كل واحد. الموظف الذكي بيستخدم ختم جاهز فيه اسم الحي مطبوع، وبس يضيف رقم الشقة. الختم ده هو الـ cache: محتوى ثابت محفوظ مرة، بيتعاد استخدامه آلاف المرات.
في Claude، أنت بتقول للـ API "البلوك ده ثابت، احفظه". Anthropic بتولّد content hash للبلوك، بتعالجه مرة، وبتخزّن النتيجة المعالجة على سيرفرها لمدة 5 دقايق افتراضياً. أي request جديد فيه نفس البلوك في نفس الترتيب بيقفز خطوة المعالجة ويبدأ من decode مباشرةً.
التعريف العلمي الدقيق
الـ Transformer model اللي Claude مبني عليه بيحوّل كل توكن إدخال إلى Key/Value vectors داخل كل layer من الـ self-attention. على موديل بـ ~80 layer، system prompt بطول 5000 توكن بيولّد مئات الآلاف من الـ vectors. الخطوة دي اسمها pre-fill وهي اللي بتاخد أغلب زمن أول توكن.
Prompt Caching بيخزّن الـ KV vectors دي على ephemeral storage معزولة لكل API key، بـ TTL 5 دقايق افتراضياً (أو ساعة كاملة لو فعّلت extended cache بسعر مختلف). المتطلبات الرسمية حسب توثيق Anthropic:
- الحد الأدنى للبلوك المخزّن: 1024 توكن لـ Sonnet و Opus، 2048 توكن لـ Haiku.
- الـ
cache_controlبيتحط على آخر بلوك في الـ prefix اللي عايز تخزنه (breakpoint). - أقصى عدد breakpoints لكل request: 4.
- الـ cache match بيشتغل من بداية الـ prompt للـ breakpoint، توكن بتوكن. أي اختلاف بايت واحد قبل الـ breakpoint بيبطل الـ cache.
الكود — السطر الواحد اللي بيغيّر الفاتورة
import anthropic
client = anthropic.Anthropic()
SYSTEM_PROMPT = """
أنت مساعد دعم فني لشركة برمجيات.
[... 4500 توكن من سياسات الشركة، few-shot examples، إرشادات صياغة ثابتة ...]
"""
response = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=1024,
system=[
{
"type": "text",
"text": SYSTEM_PROMPT,
"cache_control": {"type": "ephemeral"}
}
],
messages=[{"role": "user", "content": "ازاي أعمل refund لاشتراك سنوي؟"}]
)
print(response.usage)
أول استدعاء، الـ usage بيرجّع:
cache_creation_input_tokens: 4500
cache_read_input_tokens: 0
input_tokens: 25
الاستدعاء التاني (في نفس الـ 5 دقايق وبنفس الـ system بالحرف):
cache_creation_input_tokens: 0
cache_read_input_tokens: 4500
input_tokens: 25
السطر الوحيد اللي اضافيناه هو "cache_control": {"type": "ephemeral"}. مفيش API منفصلة، مفيش endpoint جديد، مفيش management للـ cache من طرفك. Anthropic بتتولى التخزين والتعرّف على الـ hits.
الأرقام الحقيقية — قبل وبعد على workload فعلي
الافتراض: شات بوت دعم بـ system prompt 5000 توكن، 2000 request يومياً، Claude Sonnet 4.6، متوسط الإجابة 200 توكن إخراج (للتبسيط هنركّز على فاتورة الإدخال).
أسعار Claude Sonnet 4.6 المرجعية (يرجى التأكد من الصفحة الرسمية لأن الأسعار قابلة للتعديل):
- Input عادي: $3 لكل مليون توكن.
- Cache write (5-min): $3.75 لكل مليون توكن — أي 25% زيادة عن العادي.
- Cache read: $0.30 لكل مليون توكن — أي 10% فقط من السعر العادي.
بدون cache: 5000 × 2000 = 10 مليون توكن إدخال يومياً × $3 = $30 يومياً.
مع cache (افتراض cache hit rate 95% لأن الـ system ثابت والـ traffic موزّع طول اليوم): 100 request منهم writes، 1900 reads.
- Writes: 5000 × 100 = 500K توكن × $3.75/M = $1.88
- Reads: 5000 × 1900 = 9.5M توكن × $0.30/M = $2.85
- المجموع: $4.73 يومياً
التوفير الفعلي: 84% على فاتورة الإدخال. شهرياً: من $900 لـ $142.
لزمن الاستجابة: حسب benchmarks Anthropic الرسمية، TTFT على prompts كبيرة بينزّل 80% تقريباً مع cache hit (من ~2.5 ثانية لـ ~0.5 ثانية على system بحجم 5K توكن).
الـ trade-offs اللي محدش بيقولك عليها
أولاً، الـ writes بتكلّف 25% زيادة. لو الـ prompt بتاعك متغيّر في كل request (مثلاً فيه timestamp ديناميكي أو user_id مدمج في الـ system)، أنت بتدفع write زيادة وما بتستفدش بـ read واحد. لازم تضمن الـ prefix قبل الـ breakpoint ثابت بايت ببايت.
ثانياً، ترتيب البلوكات بيهم. الـ cache match تسلسلي من أول الـ prompt لحد الـ breakpoint. لو غيّرت توكن واحد في النص الثابت، الـ cache بطل وبتدفع write جديد. القاعدة العملية: حط كل المتغيرات في الـ user message أو في آخر system block بعد الـ breakpoint.
ثالثاً، الـ TTL 5 دقايق فقط افتراضياً. لو شات بوتك بياخد فترات هدوء طويلة (مثلاً مابين 3 الفجر و 7 الصبح)، الـ cache بيموت وأول request بعد الفترة دي بيدفع write جديد. الـ extended cache (1 ساعة) متاحة بسعر write مضاعف، فا فيها break-even calculation محتاج تعمله.
رابعاً، الـ caching معزول لكل organization و API key. مش هتشارك cache مع تطبيقات تانية حتى لو على نفس الـ Anthropic account.
متى لا تستخدم Prompt Caching
الـ system prompt الكلي أقل من 1024 توكن (لـ Sonnet/Opus). الحد الأدنى مش هزل — تحت كده الـ API بترفض إنشاء breakpoint وبترجّع الـ request بدون cache. لو prompt صغير، الـ caching مش هيساعدك أصلاً.
الـ prompt بتاعك متفرد لكل user. مثلاً لو بتحقن history المستخدم أو preferences ديناميكية في أول الـ system، مفيش reuse ممكن. الحل: ابن الـ system من بلوكين — بلوك ثابت طويل مع cache_control، وبلوك متغير صغير من غيره.
traffic منخفض جداً. لو بتعمل أقل من 5 requests كل 5 دقايق على نفس الـ prompt، الـ writes بتكلفك زيادة من غير cache hits كافية تعوّض. اعمل الحسبة: لو الـ break-even أكبر من traffic بتاعك، شيل الـ caching.
تطوير وتجارب متغيّرة. لو لسه بتعدّل في الـ system prompt كل ساعة وانت بتـ iterate، كل تعديل بيبطل الـ cache. فعّل caching بعد ما تستقر على نسخة production.
الخطوة التالية
افتح آخر استدعاء لـ Claude في الكود بتاعك دلوقتي. اعرف طول الـ system prompt بـ client.messages.count_tokens(). لو فوق 1024 توكن وبيتبعت نفسه أكتر من 5 مرات في الساعة، ضيف "cache_control": {"type": "ephemeral"} على آخر بلوك في الـ system، شغّل الكود مرتين متتاليتين، اطبع response.usage، وتأكد إن cache_read_input_tokens فيه قيمة في المرة التانية. لو فاتورة الشهر الجاي قلّت أقل من 50% عن الشهر اللي فات، انت طبّقتها صح.