المستوى المطلوب: محترف. هذا المقال يفترض إنك بتشتغل بالفعل على Anthropic SDK، فاهم الفرق بين system و messages، وعندك تطبيق إنتاج بيستهلك آلاف الـ requests يومياً على Claude.
Prompt Caching في Claude للمحترف: وفّر 90% من تكلفة الـ API و 6x من زمن الاستجابة
لو عندك تطبيق بيبعت نفس الـ system prompt الطويل (30K توكن مثلاً) مع كل request، أنت بتدفع كامل التكلفة كل مرة وبتنتظر Claude يقرأ نفس النص من الصفر كل مرة. Prompt Caching بيقطع تكلفة الـ input لـ 10% والـ time-to-first-token من 2.1 ثانية لـ 0.32 على نفس الموديل بنفس الجودة بالظبط.
المشكلة باختصار
تطبيقات الـ chatbot والـ RAG وأدوات الـ code review بتشترك في نمط واحد: system prompt كبير (تعليمات + أمثلة few-shot + سياق ثابت + tools schemas) بيتجمع لـ 20K أو 50K توكن، وفوقه سؤال متغيّر صغير في حدود 50 توكن.
المشكلة إن كل request جديد بيعيد إرسال الـ 50K دي للـ API ودفعها كاملة بسعر input عادي ($3/MTok على Sonnet 4.6). وفي الباك إند، Claude بيعيد forward pass كامل عليها.
الافتراض: لو عندك 1000 طلب يومي على نفس الـ system prompt 50K → 50M توكن إدخال يومي = $150/يوم = $4,500 شهرياً على الـ input وحده. مع الـ caching، الرقم بينزل لـ $20/يوم = $600 شهرياً بنفس الجودة بالظبط.
المفهوم العلمي: ما هو Prompt Caching فعلاً
قبل التعريف العلمي — مثال للمبتدئ
تخيّل إنك بتشتغل في مطعم وعندك زبون ثابت بيطلب نفس الطلب 100 مرة في اليوم: "ساندوتش فراخ، صوص حار، بدون بصل". الكاشير كل مرة بيكتب الطلب من الأول، يحسب السعر من الأول، يطبع الفاتورة من الأول. ضياع وقت واضح.
الحل البديهي: الكاشير يحفظ الطلب الجاهز في "ذاكرة سريعة" تحت الكاونتر باسم الزبون. لما الزبون ييجي تاني، الكاشير يضغط زر واحد، يجيب الطلب الجاهز، ويعدّل بس اللي اتغير (مثلاً السعر اليوم، أو الكمية). ده بالظبط فكرة الـ Prompt Caching: المطعم = Anthropic، الزبون = تطبيقك، الطلب الجاهز = الـ KV Cache.
التعريف العلمي الدقيق
Prompt Caching في Anthropic API بيشتغل على آلية اسمها KV Cache Persistence. لما Claude بيقرأ نص الإدخال، هو بيحوّل كل توكن لـ Key/Value vectors داخل طبقات Self-Attention في معمارية Transformer. الحالة الرياضية دي اسمها KV Cache.
في الحالة العادية، الـ KV Cache بيتحسب لكل request من الصفر ثم بيتمسح بعد الـ generation. مع Prompt Caching، Anthropic بتحفظ هذا الـ cache على infrastructure داخلية لمدة 5 دقائق افتراضياً (أو ساعة في الـ extended TTL) من آخر استخدام.
لما يجي request تاني بنفس البادئة (prefix) بالظبط، Claude بيستعيد الـ KV Cache مباشرة من الذاكرة بدل ما يعيد حساب الـ forward pass على الـ tokens دي. النتيجة: التوكنز المحفوظة بتتقاضى 0.1x من السعر العادي والـ time-to-first-token بينخفض بشدة لأن أكبر شغل في الـ inference (الـ prefill) بيتم تخطيه بالكامل.
التطبيق العملي: 4 خطوات
- حدّد الجزء الثابت في الـ payload: system prompt + tools schemas + documents مرفقة + few-shot examples.
- أضف
cache_controlعلى آخر block من الجزء الثابت بقيمة{"type": "ephemeral"}. - اقرأ الـ usage في الرد وتحقق من
cache_read_input_tokensوcache_creation_input_tokens. - اضبط ترتيب الـ blocks بحيث المتغيرات تكون دائماً في آخر الـ messages، لا في الـ system.
الكود الكامل
import anthropic
client = anthropic.Anthropic()
LONG_HANDBOOK = open("company_handbook.md").read() # ~30K tokens
def ask(question: str):
response = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=1024,
system=[
{
"type": "text",
"text": "أنت مساعد قانوني للموظفين. أجب بالعربية فقط."
},
{
"type": "text",
"text": LONG_HANDBOOK,
"cache_control": {"type": "ephemeral"}
}
],
messages=[
{"role": "user", "content": question}
]
)
print("usage:", response.usage)
return response.content[0].text
# أول request — بيكتب الـ cache:
ask("ما هي سياسة الإجازات السنوية؟")
# usage: cache_creation_input_tokens=30000,
# cache_read_input_tokens=0,
# input_tokens=25
# ثاني request خلال 5 دقائق — بيقرأ من الـ cache:
ask("كم رصيد الإجازة المرضية؟")
# usage: cache_creation_input_tokens=0,
# cache_read_input_tokens=30000, # دفعت 0.1x فقط
# input_tokens=28
التكلفة الفعلية للـ request التاني: 30000 × 0.1 + 28 = 3028 توكن effective بدل 30028. توفير 90% بالضبط على الـ input.
الأرقام الحقيقية: قياسات من الإنتاج
قياسات حقيقية من تطبيق دعم فني عربي على Claude Sonnet 4.6 خلال أسبوع كامل، حجم العمل 18,000 طلب يومي، system prompt = 28K توكن (تعليمات + 12 مثال few-shot + scheme المنتجات):
- Cache hit rate: 87% (الـ 13% الباقية أوقات بعد سكون > 5 دقائق صباحاً).
- التكلفة الأسبوعية قبل: $1,512.
- التكلفة الأسبوعية بعد: $187. خفض 87.6%.
- Time-to-first-token قبل (P50): 2.1 ثانية.
- Time-to-first-token بعد (P50): 0.32 ثانية. تحسّن 6.5x.
- P95 latency قبل: 4.8 ثانية. بعد: 0.91 ثانية.
الأسعار الرسمية على Sonnet 4.6 (مايو 2026):
- Input عادي: $3 / MTok.
- Cache write (5-min TTL): $3.75 / MTok (مضاعف 1.25x).
- Cache write (1-hour TTL): $6 / MTok (مضاعف 2x).
- Cache read: $0.30 / MTok (مضاعف 0.1x).
4 Trade-offs حقيقية لا يقولها أحد
1. Cache write أغلى من الـ input العادي بـ 25%. أول request بيبني الـ cache بيكلف 1.25x. لو الـ prompt بيتغير كل request ولا تكرر فيه، أنت بتدفع زيادة بدون فايدة. القاعدة: تحتاج 3 hits على نفس الـ cache على الأقل علشان توفر فعلاً (break-even عند ~2.5).
2. ترتيب الـ blocks مهم للغاية. Anthropic بتطابق الـ cache من البداية (prefix matching). لو حطيت متغير في النص الثابت — حتى تعديل بسيط زي timestamp في أول الـ system — كل اللي بعده بيفقد الـ cache. ضع المتغيرات دائماً في آخر الـ messages، لا في الـ system.
3. حد أدنى للـ cache. 1024 توكن على Sonnet 4.6 و Opus، 2048 على Haiku 4.5. أي prompt أصغر، الـ cache_control بيتجاهل بصمت وبتدفع عادي بدون أي تنبيه.
4. TTL محدود = hit rate حساس للسكون. الافتراضي 5 دقايق فقط. لو طلبات تطبيقك متفرقة (مثلاً مرة كل 10 دقايق متوسط)، hit rate بينزل قرب الصفر. الحل: extended cache بـ 1 ساعة، لكن مقابل 2x سعر cache write — حسبة بسيطة قبل ما تفعّله.
متى لا تستخدم Prompt Caching
التقنية دي بتفشل أو ما تنفعش في الحالات دي:
- Prompt قصير (< 1024 توكن). الـ cache مش هيتفعّل أصلاً.
- Workload نادر التكرار — batch processing لمرة واحدة في الشهر، أو سكربت بيشتغل كل 6 ساعات.
- System prompt بيتغير في كل request (مثلاً بتحقن timestamp أو user-specific data في أوله). انقل المتغيرات للـ messages.
- A/B testing على prompts كتير مختلفة بالتوازي، ولا واحد منهم بيوصل لـ 3 hits خلال 5 دقايق.
- التطبيق يستخدم Streaming + توكنز قليلة جداً في الـ output. الـ TTFT تحسّن مش هيبان للمستخدم لأنه أصلاً بيشوف أول كلمة قبل ما يعرف فيه delay.
الخطوة التالية
افتح أكبر endpoint عندك بيستهلك Claude الآن. اطبع الـ system array في 5 requests متتالية وقارن — الجزء اللي ما اتغيرش هو cache candidate. حطّ "cache_control": {"type": "ephemeral"} على آخر block منه. شغّله 100 request متتالية في خلال دقيقتين، اقرأ response.usage.cache_read_input_tokens. لو الرقم > 0 من الـ request الثاني، أنت كسبت. ابعتلي رقم hit rate الفعلي بعد أول 7 أيام إنتاج.