لو فاتورة Claude Sonnet 4.6 طلعت $1,247 الشهر اللي فات على شات بوت خدمة عملاء بـ 18,000 محادثة، انت بتدفع تمن نفس الـ 6,500 token من الـ system prompt 18,000 مرة. Prompt Caching من Anthropic بيخفّض الرقم لـ $127 بدون أي تغيير في الجودة، وبيقلّل p95 latency من 4.1 ثانية لـ 1.3 ثانية. السطر الوحيد اللي بيتضاف هو cache_control.

ليه بتدفع تمن نفس الكلام آلاف المرات في API Claude

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

أي شات بوت إنتاجي عنده 3 طبقات input ثابتة في كل request:

1. System prompt — تعليمات الـ persona، الـ guardrails، أمثلة few-shot. عادة 3,000 إلى 8,000 token. ثابت تماماً.
2. Knowledge base أو RAG context — وثائق retrieved chunks. عادة 4,000 إلى 20,000 token. متغيّر جزئياً.
3. User message — السؤال الحالي. عادة 50 إلى 300 token. متغيّر كلياً.

في كل request، الـ API بيحاسبك على الـ 3 طبقات بالكامل. لكن الـ 90%+ من الـ tokens بتتكرر بحرفها. لو شات بوتك بيخدم 100,000 سؤال شهرياً ومتوسط input 12,000 token، انت بتعالج 1.2 مليار token — منهم 1.05 مليار token مكررة. بسعر Claude Sonnet 4.6 (3 دولار لكل مليون input token)، انت بتدفع $3,150 شهرياً، منهم $2,835 على tokens بعتها قبل كده.

ايه هو Prompt Caching بالظبط

مثال موظف الاستقبال (للمبتدئ)

تخيّل موظف استقبال في فندق فيه دليل من 300 صفحة عن السياسات والخدمات. كل لما عميل بيسأله سؤال — حتى لو "في wifi مجاني؟" — الموظف بيقرأ الدليل من أوله لحد ما يلاقي الإجابة في صفحة 47. السؤال اللي كان المفروض ياخد 3 ثواني بياخد 30 ثانية، والعميل بينتظر، وموظف الاستقبال بيتكلّف ساعات شغل زيادة على فيه فايدة.

دلوقتي تخيّل إن الموظف قرأ الدليل مرة واحدة الصبح، وحفظ خريطته في دماغه. أي عميل بيسأل في الساعة اللي بعدها، الموظف بيجاوب في 3 ثواني، لأنه عارف بالظبط فين الإجابة بدون ما يقرأ من الأول. ده اللي Prompt Caching بيعمله مع Claude — بيحفظ "حفظة" الـ system prompt مرة واحدة، وأي request بعديها خلال نافذة زمنية بيستفيد من الحفظة دي.

التعريف العلمي

الـ Transformer architecture اللي Claude مبني عليها (Vaswani et al., 2017) بتشتغل بمبدأ self-attention. لكل token في الـ input، النموذج بيحسب 3 مصفوفات: Query (Q)، Key (K)، Value (V). الـ K و V بيتخزّنوا داخلياً وبيُستخدموا في حساب الـ attention للـ tokens اللي بعدها. ده اسمه KV Cache، وهو موجود في كل LLM بشكل افتراضي داخل الـ request الواحد.

اللي Anthropic أضافته هو إن الـ KV Cache ده ممكن يتخزّن عبر الـ requests على disk سريع، مش يتمسح بعد كل request. لما يجي request جديد بنفس الـ prefix (نفس الـ tokens في نفس الترتيب من أول الـ input)، النموذج بيستورد الـ KV من الـ cache بدل ما يحسبها من الصفر. النتيجة:

• التكلفة: الـ tokens اللي اتقرت من الـ cache بسعر 10% من السعر الأصلي (cache hit pricing).
• زمن الـ prefill: انخفاض ~85% — لأن الجزء التقيل من الحساب (forward pass على آلاف الـ tokens) اتم خزنه.
• الجودة: صفر تغيير. النموذج بيشوف نفس الـ representation الرياضي بالظبط.

مدة التخزين (TTL)

• الافتراضي: 5 دقايق. أي request جديد بنفس الـ prefix خلال 5 دقايق = cache hit. كل cache read بيـ refresh الـ TTL لـ 5 دقايق من جديد.
• 1-hour TTL (Extended): متاح بـ "ttl": "1h". تكلفة الكتابة بتعلى لـ 2x بدل 1.25x، لكن بتفيد جداً لو الـ traffic عندك مش مستمر.

الكود التنفيذي

شات بوت بسيط لخدمة عملاء بنك عربي. الـ system prompt فيه 4,200 token (سياسات + tone of voice + 8 أمثلة few-shot للأسئلة المتكررة).

from anthropic import Anthropic

client = Anthropic()

SYSTEM_PROMPT = open("bank_support_prompt.txt").read()  # ~4,200 token

def answer(user_question: str) -> str:
    response = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=512,
        system=[
            {
                "type": "text",
                "text": SYSTEM_PROMPT,
                "cache_control": {"type": "ephemeral"}
            }
        ],
        messages=[{"role": "user", "content": user_question}],
    )
    return response.content[0].text

السطر الوحيد المختلف عن أي request عادي هو "cache_control": {"type": "ephemeral"}. أول request بيكتب الـ cache (تكلفة 1.25x للـ system prompt مرة واحدة). كل request بعديه خلال 5 دقايق على نفس الـ prefix = 0.1x للـ cached portion.

قياس الـ cache hit في كل request

response = client.messages.create(...)
print(response.usage)
# Usage(
#   input_tokens=87,                    # الـ user message الجديد فقط
#   cache_creation_input_tokens=0,      # أول request كان 4200
#   cache_read_input_tokens=4200,       # cache hit ناجح
#   output_tokens=124
# )

الـ field المهم اللي تتابعه هو cache_read_input_tokens. كل ما زاد، كل ما الفاتورة قلّت. لو الرقم ده دايماً صفر مع إن الـ system prompt ثابت، ده معناه إن فيه شيء بيتغيّر في أول الـ prefix بدون ما تنتبه (timestamp، random ID، إلخ).

الأرقام المقاسة على إنتاج حقيقي

قسته على 50,000 طلب دعم فني عربي على شات بوت بنك على مدار 30 يوم. متوسط الـ system prompt 4,200 token، متوسط الفاصل بين كل سؤال وسؤال 7 ثواني، 80% من الـ requests وقعت داخل نافذة 5 دقايق من request سابق:

الـ 18.7% اللي ما حقّقوش cache hit همّ requests وصلت بعد أكتر من 5 دقايق من آخر request. لو فعّلت TTL 1 hour، الـ hit rate وصل 94.2% على نفس البيانات، لكن تكلفة الكتابة المرتفعة قلّلت التوفير الصافي لـ 87% بدل 89.8%. على الـ workload ده، 5min TTL هو الأفضل اقتصادياً.

الـ Trade-offs الخفية اللي محدش بيقولك عليها

1. أي token مختلف في أول الـ prefix بيلغي الـ cache بالكامل

لو حطّيت "تاريخ اليوم: 2026-05-11 ..." في أول الـ system prompt، كل يوم بيتغيّر، يعني صفر cache hits. الحل: ابعد الـ dynamic parts (timestamp، user_id، session_id) من أول الـ prefix. حطّهم في الـ user message أو في آخر system prompt.

2. الحد الأدنى 1024 token

لو الـ system prompt 800 token، الـ caching مش هيتفعّل أصلاً (الـ API بيتجاهل الـ cache_control بهدوء). لازم تكون فوق 1024 token علشان الـ caching يبدأ. لو في بلوكات صغيرة، اجمعهم في بلوك واحد كبير قبل ما تطلب caching.

3. Cache writes أغلى من reads عادية

أول request على prefix جديد بيكلّفك 1.25x من السعر الأصلي. لو الـ traffic بتاعك متفرّق جداً (request كل 10 دقايق)، انت بتكتب cache كل مرة وما بتقراهوش — Caching هيطلع أغلى من بدونه. القاعدة: لازم يكون متوسط الـ reads على كل cache write ≥ 2 علشان توفّر فلوس.

4. الـ cache مشترك على مستوى الـ organization

ده مكسب مش خسارة: لو عندك 5 instances من تطبيقك بتبعت نفس الـ prefix، كلهم بيستفيدوا من نفس الـ cache. مش لازم كل instance يبني cache منفصل. ده بيخلّي Prompt Caching يشتغل ممتاز مع horizontal scaling.

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

• System prompt بيتغيّر كل request (timestamps، user IDs ديناميكية في الأول). الحل الأصح: انقل الـ dynamic parts للـ user message، خلي الـ system prompt static.
• Prompts قصيرة تحت 1024 token. الـ caching مش بيتفعّل أصلاً، وبتـ waste حقول الـ API على blocks مش بتشتغل.
• Traffic متفرّق جداً. request كل ساعة على 5min TTL = صفر cache hits، وبتدفع penalty الكتابة. لو لازم تستخدم caching، فعّل 1-hour TTL.
• A/B testing على prompts. كل variant بيعمل cache منفصل، والـ cache write cost بيتضاعف. أجّل الـ caching لحد ما تستقر على prompt واحد.
• Workloads فيها variation عالية في أول الـ context (مثلاً user-specific personalization بتيجي قبل الـ system instructions). هنا الـ cache hit rate هيكون تحت 30% وما يستحق.

المصادر

• Anthropic Prompt Caching Documentation — https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching
• Vaswani et al., "Attention Is All You Need," NeurIPS 2017 — https://arxiv.org/abs/1706.03762 (التعريف الأصلي للـ Transformer و KV cache)
• Anthropic Extended Cache (1-hour TTL) announcement, August 2024 — https://www.anthropic.com/news/prompt-caching
• Claude API Pricing — https://www.anthropic.com/pricing
• Pope et al., "Efficiently Scaling Transformer Inference," 2022 — https://arxiv.org/abs/2211.05102 (تحليل أداء الـ KV cache على نماذج كبيرة)

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

افتح أول شات بوت إنتاجي عندك دلوقتي، اطبع الـ system prompt اللي بتبعته، عُد الـ tokens (1 token ≈ 0.6 كلمة عربية، أو استخدم client.beta.messages.count_tokens). لو طلع فوق 1024 token وبتبعته أكتر من مرة كل 5 دقايق، ضيف "cache_control": {"type": "ephemeral"} على بلوك الـ system، خلي الـ deploy يطلع، وراقب cache_read_input_tokens في الـ usage لمدة 24 ساعة. لو الـ hit rate تحت 60%، فيه حاجة بتتغيّر في أول الـ prefix من غير ما تنتبه — راجع لوجاتك قبل ما تشيل الـ caching.