المستوى المطلوب: متوسط — تحتاج إلمامًا بـ Claude API و Python و مفاهيم الـ pricing الأساسية للـ tokens.

chatbot شركة عقارات بيرد على 20,000 سؤال شهريًا، system prompt حجمه 50,000 token (سياسات + بيانات + few-shot examples). الفاتورة على Claude Sonnet بسعر مايو 2026 = حوالي $3,000 شهر، مع إن 99% من الـ tokens دي ثابتة ومتكررة. Prompt Caching بينزّل الرقم ده لـ $330 بسطرين كود، بدون أي تغيير في جودة الرد.

Prompt Caching في Claude API: ازاي توفّر 89% من فاتورتك في الإنتاج

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

Claude API stateless. كل request بيتعامل مع الـ context من الصفر — حتى لو نفس الـ system prompt اتبعت 1000 مرة في ساعة. النتيجة: لو عندك RAG context كبير، أو instructions طويلة، أو few-shot examples، إنت بتدفع نفس فلوس tokenization على كل طلب وتستهلك نفس الـ GPU compute.

الفكرة بمثال أمين المكتبة

تخيّل أمين مكتبة. كل ما طالب يطلب كتاب اسمه "أساسيات الفيزياء"، بيمشي 30 ثانية للـ rack ويرجّعه. لو 50 طالب طلبوا الكتاب في ساعة، أمين المكتبة هيمشي 25 دقيقة في نفس الرف.

أمين مكتبة شاطر بيخلّي الكتب الـ"شائعة الطلب" على المكتب قدامه. أول طالب بيستنّى 30 ثانية (وقت إحضار الكتاب + وضعه على المكتب). كل اللي بعد كده بياخدوه في ثانيتين.

Prompt Caching بيشتغل بنفس المنطق على مستوى GPU memory: أول مرة تكلفة عالية شوية، بعد كده قراءة سريعة ورخيصة.

التعريف العلمي: KV-Cache في الـ Transformer

Claude (زي كل LLM مبني على transformer) بيحوّل كل token لـ Key/Value matrices في كل attention layer. الـ KV-cache هو هيكل بيخزّن الـ matrices دي بعد ما تتحسب أول مرة.

بدون caching: لو بعتت 50K token، الـ GPU بيحسب 50K KV pair من الصفر لكل request. مع caching: أول request بيحسبهم وبيخزّنهم في VRAM لمدة 5 دقايق. الـ requests التالية بتقرأهم مباشرةً من الذاكرة.

تكلفة الـ caching الحقيقية بتيجي من 3 عوامل: الـ vRAM occupancy على الـ GPU، إدارة الـ TTL (time-to-live)، وضمان أن الـ prefix بايت بـ بايت نفسه.

الكود الفعلي على anthropic SDK

import anthropic

client = anthropic.Anthropic()
system_prompt = open("docs/codebase-context.md").read()  # ~50K tokens

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": "اشرحلي function processOrder()"}]
)

print(response.usage)
# UsageMetrics(input_tokens=18, cache_creation_input_tokens=49872,
#              cache_read_input_tokens=0, output_tokens=412)

الـ response.usage بترجع 4 حقول مهمة لازم تراقبهم:

• input_tokens: tokens الـ user message فقط
• cache_creation_input_tokens: tokens اتخزّنت في cache (أول مرة فقط)
• cache_read_input_tokens: tokens اتقرأت من cache (المرات التالية)
• output_tokens: tokens الرد المولّد

لو طلعت أرقام في cache_read_input_tokens من Request 2، الـ caching شغّال صح.

الأرقام الحقيقية على 100 request

على Claude Sonnet 4.6 بسعر Anthropic مايو 2026:

• Input عادي: $3 / 1M token
• Cache write: $3.75 / 1M token (1.25x)
• Cache read: $0.30 / 1M token (0.1x)

سيناريو فعلي: chatbot عقارات بيرد على 100 سؤال في الساعة، system prompt = 50K token (سياسات الشركة + قاعدة بيانات العقارات + few-shot examples).

• بدون Caching: 100 × $0.150 = $15.00 في الساعة
• مع Caching: $0.1875 (Request 1) + 99 × $0.015 = $1.67 في الساعة
• التوفير: 88.9% — على شهر كامل بنفس النمط، بتنزل من $10,800 لـ $1,200

الـ Trade-offs الخفية

1. الـ TTL = 5 دقايق فقط: لو الفجوة بين الـ requests زادت عن 5 دقايق، الـ cache بيتمسح. هتدفع cache write مرة تانية. (في beta لـ 1-hour cache بسعر 2x، استخدمه لو طلباتك متباعدة).
2. الحد الأدنى: cached portion لازم ≥1024 token على Sonnet/Opus، و≥4096 على Haiku. أقل من ده، الـ cache_control بيتجاهل بدون warning.
3. أول request دايمًا أغلى 25%: cache write × 1.25. لو request واحد بس متوقع، إنت بتخسر فلوس.
4. Cache invalidation حساس جدًا: byte واحد مختلف في الـ prefix = cache miss كامل. مسافة زيادة، تاريخ متغيّر داخل النص، random ID — كلهم بيدمّروا الـ cache بصمت.

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

الـ caching بيخسّرك فلوس في 3 حالات:

• الـ system prompt بيتغير كل request (مثلًا: datetime.now() مدمج جوّاه).
• الفجوة بين الـ requests دائمًا أكبر من 5 دقايق ومش هتفعّل beta cache.
• الـ system prompt أقل من 1024 token (الميزة مش بتشتغل أصلًا).

قاعدة عملية: لو الـ cache hit rate المتوقع أقل من 30%، التكلفة الإضافية على الـ writes بتاكل أي توفير.

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

افتح أكثر endpoint عندك بيرسل نفس الـ system prompt بشكل متكرر. ضيف cache_control: {"type": "ephemeral"} على آخر block ثابت في الـ system. شغّل 10 requests متتابعة وراقب cache_read_input_tokens. لو طلعت أرقام في الحقل ده بداية من Request 2، انت كسبت 89% من فاتورتك.

المصادر

• Anthropic Documentation — Prompt Caching: docs.anthropic.com/en/docs/build-with-claude/prompt-caching
• Anthropic Pricing Page (مايو 2026): anthropic.com/pricing
• Pope et al., "Efficiently Scaling Transformer Inference" (2022) — KV-cache foundation
• Anthropic Engineering Blog — Extended caching announcement (2025)
• Vaswani et al., "Attention Is All You Need" (2017) — أساس الـ Key/Value attention