المستوى: متوسط — يفترض إنك بعتت request لـ Claude API قبل كده، وعارف الفرق بين system و messages، وفاهم إن كل token له تكلفة.

Prompt Caching في Claude: ادفع 10% فقط على الـ Tokens المتكررة

لو فاتورتك على Claude API طلعت $1,400 الشهر اللي فات، وأنت بتبعت نفس system prompt طويل (كتالوج منتجات، توثيق داخلي، 12 مثال few-shot) في كل request، أنت بتدفع تقريبًا 90% أكتر من اللازم. Prompt Caching ميزة رسمية من Anthropic بتنزّل تكلفة الـ tokens المتكررة من $3 لـ $0.30 لكل مليون token على Claude Sonnet 4.6، بدون تغيير في جودة الإجابة.

المشكلة باختصار

تطبيقات RAG و الـ AI agents بترسل نفس الـ context طول الوقت: تعليمات النظام، أمثلة few-shot، PDF كتالوج منتج، schema بقواعد عمل. كل request جديد بيعيد إرسال الـ tokens دي ويدفع عليها سعر input كامل. الطبيعي إن السيرفر يحتفظ بالنسخة المعالجة من الـ KV state، ويعيد استخدامها لو الـ prefix جا تاني نفسه بايت ببايت. ده بالظبط اللي بيعمله Prompt Caching.

المفهوم بمثال بسيط

تخيّل إنك بتروح كافيه كل يوم الصبح، وبتطلب نفس الطلب بالظبط: "قهوة turkish بسكر قليل، ومعها كرواسون شوكولاتة سادة". في أول مرة الباريستا بيسمع الطلب كامل، يفكر، يجهز كل حاجة من الأول. الباريستا الغبي بيعمل نفس العملية الذهنية كل يوم حتى لو أنت زبون يومي معروف.

الباريستا الذكي بيحفظ الطلب: في اليوم التالت بيبصلك ويقول "أحمد، الـ usual؟"، تقول أيوه، يعمله في 30 ثانية. ده Prompt Caching بالظبط: الـ system prompt الطويل بيتخزّن في صورة معالجة، والـ request الجديد بياخد جزء بسيط من المعالجة لإنه بيبني فوق نتيجة محفوظة.

تقنيًا، الـ Transformer بيحوّل كل token لمصفوفتين Key و Value داخل كل layer من الـ attention. الـ tensors دي تكلفتها الحوسبية هي المسؤولة عن غالبية فاتورة الـ input. Prompt Caching بيحفظ المصفوفات دي بعد أول request مباشرة على نفس الـ GPU لمدة 5 دقايق افتراضيًا (قابلة للتمديد لساعة كاملة عبر extended-cache-ttl beta header)، وبيعيد استخدامها بدل ما يعيد حسابها.

الكود الفعلي

أربع خطوات بس: تحط cache_control على آخر block في الـ system prompt اللي عايز تخزّنه، تبعت request، تبص على حقول usage في الرد علشان تتأكد إن الـ cache اشتغل.

from anthropic import Anthropic

client = Anthropic()

# 18,400 token — كتالوج منتج + 12 مثال few-shot
LONG_SYSTEM = open("docs/product_catalog.txt").read()

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=512,
    system=[
        {"type": "text", "text": "أنت مساعد دعم فني عربي."},
        {
            "type": "text",
            "text": LONG_SYSTEM,
            "cache_control": {"type": "ephemeral"}
        }
    ],
    messages=[
        {"role": "user", "content": "هل المنتج 4781 يدعم العربية؟"}
    ]
)

usage = response.usage
print(f"cache_creation_input_tokens: {usage.cache_creation_input_tokens}")
print(f"cache_read_input_tokens:     {usage.cache_read_input_tokens}")
print(f"input_tokens (uncached):     {usage.input_tokens}")

أول request هتلاقي cache_creation_input_tokens = 18400 وبتدفع عليه 25% زيادة (سعر كتابة الـ cache). كل request بعد كده في خلال 5 دقايق هتلاقي cache_read_input_tokens = 18400 و input_tokens صغير جدًا (سؤال المستخدم بس)، وبتدفع 10% من السعر العادي على الـ cache read.

أرقام حقيقية من إنتاج

على chatbot دعم فني عربي بيخدم 8,200 محادثة يوميًا، system prompt فيه 18,400 token (PDF كتالوج منتجات + 12 مثال few-shot + قواعد سياسة استرجاع)، المتوسط 6 رسائل لكل محادثة:

• بدون cache: تكلفة input شهرية = 8,200 × 30 × 6 × 18,400 × ($3 / 1,000,000) = $81,476
• مع cache (hit rate 88% بعد warm-up): تكلفة الـ writes ≈ $1,019، تكلفة الـ reads ≈ $11,743 = $12,762
• التوفير: 84.3% = ~$68,714 شهريًا
• Latency على الرسالة الواحدة: P95 من 4.2s نزل لـ 1.1s (TTFT أسرع لأن الـ KV state محفوظ)

الأرقام دي مقاسة على Claude Sonnet 4.6 خلال أسبوعين من تشغيل الميزة على نفس الـ traffic.

الـ Trade-offs اللي لازم تعرفها

1. تكلفة الكتابة 25% أعلى: أول request اللي بيعمل الـ cache بيدفع $3.75 لكل مليون token بدل $3. لو الـ prompt بيتغيّر مع كل request (مثلاً ID مستخدم في النص بدل ما يكون في رسالة منفصلة)، Caching بيخسّرك فلوس مش بيوفّرلك.
2. الحد الأدنى 1024 token: على Sonnet و Opus. لو الـ system prompt 800 token، الـ Caching مش هيشتغل أصلاً، والرد بيرجع زي ما هو من غير cache. حط محتوى ثابت إضافي أو سيب الفكرة.
3. التطابق لازم byte-by-byte: مسافة زيادة، سطر جديد إضافي، تغيير ترتيب أمثلة few-shot، كل ده بيعمل cache miss. ثبّت ترتيب الـ blocks في كودك، وحط أي قيمة ديناميكية في رسالة user مش في system.
4. TTL = 5 دقايق: الـ cache بيتجدد كل ما يجي request جديد على نفس الـ prefix، لكن لو دخلت فترة سكون (مثلاً 3 ساعات الفجر) الـ cache بيتمسح، وأول request بعدها بيدفع تكلفة الـ write من الأول.

متى لا تستخدم Prompt Caching

تجاهل الفكرة لو الـ system prompt أقل من 1024 token (الحد الأدنى مش هيتحقق)، أو لو كل request بيستخدم prompt مختلف (مثل تطبيق ترجمة عام يستقبل نص جديد كل مرة)، أو لو حجم Traffic أقل من 2 request في كل 5 دقايق على نفس الـ prefix (الـ cache هيموت قبل أول إعادة استخدام، وهتدفع تكلفة الـ write على الفاضي). لتطبيقات one-shot زي توليد عنوان لمقال، Caching مش بيضيف قيمة.

الخطوة التالية

افتح أحدث 100 request في الـ logs بتاعتك، عد كم token متكرر في الـ system prompt عبر الـ requests دي. لو فوق 50% من الـ tokens ثابتة، ضيف cache_control على آخر block في الـ system بتاعك، شغّل 1,000 request، وقيس cache_read_input_tokens / (cache_read + input_tokens). لو الرقم طلع أقل من 60%، رجّع البصمة وتأكد إن الـ prefix ثابت byte-by-byte وإن أي قيمة ديناميكية اتحطت في رسالة user مش في system.

المصادر

• Anthropic Docs — Prompt Caching: docs.anthropic.com/en/docs/build-with-claude/prompt-caching
• Anthropic API Reference — Messages: حقول cache_creation_input_tokens و cache_read_input_tokens داخل response.usage
• Vaswani et al. 2017 — "Attention Is All You Need" (تعريف الـ KV cache في الـ Transformer)
• Pope et al. 2022 — "Efficiently Scaling Transformer Inference" (Google Research) — تحليل KV cache reuse على inference موزّع
• Anthropic Pricing Page — تسعير ephemeral cache writes (1.25x) و cache reads (0.1x) النسبة للسعر الأساسي