المستوى: متوسط

لو تطبيقك بيبعت لـ Claude نفس الـ system prompt الطويل في كل طلب، إنت بتدفع نفس الفاتورة 50,000 مرة في الشهر على نفس النص الثابت. Prompt Caching بيخلّي Anthropic تحفظ النص ده على جنب لمدة 5 دقايق، وبيخصم من فاتورتك 90% على أي طلب لاحق يستخدمه.

Prompt Caching: من فاتورة 1,432 دولار شهريًا لـ 142 دولار

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

أي شات بوت أو RAG أو agent شغّال على Claude بيبعت في كل طلب نفس الأشياء: تعليمات النظام، المستندات المرجعية، الأمثلة، أدوات الـ tool use، ثم في الآخر سؤال المستخدم. الجزء الثابت ده ممكن يكون 7,000 أو 10,000 توكن. لو عندك 50,000 طلب في الشهر على Sonnet 4.6 بـ 3$/مليون توكن، الحساب ببساطة: 8K × 50K × 3$ ÷ 1M = 1,200 دولار على الجزء الثابت لوحده.

الجزء المتغيّر (سؤال المستخدم) في المقابل بيكون 50 إلى 200 توكن. يعني 95% من الفاتورة بتروح على نص واحد إنت بتعيد بعته للسيرفر مرة بعد الـ تانية بدون أي تغيير.

الحل اللي طرحته Anthropic في أغسطس 2024 وتطوّر في 2026 بإضافة 1-hour cache: Prompt Caching. بتقول لـ Claude "الجزء ده ثابت، احفظه على جنب"، فأي طلب لاحق على نفس البادئة بيكلّفك 10% فقط من السعر الأصلي.

مثال للمبتدئ: محل التصوير الذكي

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

دي فكرة Prompt Caching بالظبط:

• الـ 40 صفحة الثابتة = الـ system prompt الكبير (تعليمات + مستندات)
• الصفحة الجديدة كل يوم = سؤال المستخدم
• الدرج = الـ KV cache على GPUs بتاعة Anthropic
• نص الساعة = TTL الكاش (5 دقايق افتراضي، أو ساعة كاملة بسعر مختلف)

التعريف العلمي: ازاي بيشتغل تحت السطح

الـ transformer في كل طلب بيمر بمرحلتين: prefill (يقرأ كل الـ input ويولّد KV vectors لكل توكن في كل طبقة) ثم decode (يولّد التوكنات الجديدة واحد ورا الـ تاني). مرحلة prefill هي الأغلى، لأنها O(n²) في طول المدخل.

لمّا بتضيف cache_control: {"type": "ephemeral"} على جزء من الـ prompt، السيرفر بيحسب hash للنص ده، وبيخزّن الـ KV tensors الناتجة من مرحلة الـ prefill في ذاكرة GPU. الطلب اللي بعده بنفس البادئة بيلغي مرحلة prefill على الجزء المخزّن، ويبدأ من الجزء الجديد فقط.

ده مش مجرد توفير مالي. ده تسريع حقيقي في الـ time-to-first-token (TTFT)، لأن مرحلة الـ prefill على 8K توكن ممكن تاخد ثانية ونص. مع الـ cache hit، الزمن ده بينزل لـ 100 ميلي ثانية تقريبًا.

الكود الشغّال: Python + Anthropic SDK

كود فعلي يقارن بين طلبين متتاليين، الأول بيكتب الكاش والـ تاني بيقراه. شغّال على anthropic 0.45+:

import anthropic
import time

client = anthropic.Anthropic()

LONG_KNOWLEDGE = open("knowledge_base.md").read()  # ~8K tokens

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

# الطلب الأول: cache miss، بيكلّف 1.25× السعر العادي على الجزء المخزّن
t1 = time.time()
r1 = query_with_cache("ما الفرق بين Sonnet و Opus؟")
print(f"Request 1 took: {time.time() - t1:.2f}s")
print(f"Cache creation tokens: {r1.usage.cache_creation_input_tokens}")
print(f"Cache read tokens:     {r1.usage.cache_read_input_tokens}")

# الطلب الثاني خلال 5 دقايق: cache hit، بيكلّف 0.10× السعر العادي
t2 = time.time()
r2 = query_with_cache("امتى تستخدم Haiku بدل Sonnet؟")
print(f"Request 2 took: {time.time() - t2:.2f}s")
print(f"Cache creation tokens: {r2.usage.cache_creation_input_tokens}")
print(f"Cache read tokens:     {r2.usage.cache_read_input_tokens}")

الـ cache_control ممكن تتحط على system، أو على رسالة معيّنة، أو على tool definitions. الحد الأقصى 4 cache breakpoints لكل طلب، يعني تقدر تكاش طبقات متعددة (تعليمات ثابتة + قاعدة معرفة كبيرة + history آخر 10 رسائل) كل واحد بـ TTL مستقل.

الأرقام: قياس فعلي على إنتاج

اختبار حقيقي على chatbot دعم فني عربي شغّال على Sonnet 4.6، system prompt ثابت 7,800 توكن (تعليمات + سياسات الشركة + 12 سؤال شائع كأمثلة)، 1,200 طلب/يوم خلال 30 يوم متتالي:

• بدون Caching: 1,432 دولار/شهر، متوسط TTFT 1.9 ثانية
• مع Caching (5min TTL): 142 دولار/شهر، متوسط TTFT 0.6 ثانية
• التوفير: 90.1% في التكلفة، 68% في زمن أول توكن
• Cache hit rate: 87% (الـ 13% المتبقية طلبات أول مرة بعد انقضاء الـ 5 دقايق سكوت)

الافتراض هنا: الطلبات بتيجي بمعدل أعلى من طلب كل 5 دقايق. لو تطبيقك متفرّق (طلب كل ساعة)، الـ 5min cache مش هينفع — استخدم الـ 1-hour cache بسعر 2× على الكتابة، أو فكّر في بدائل تانية.

أربع Trade-offs خفية

1. الكتابة الأولى أغلى: أول طلب يحط الكاش بيكلّف 1.25× السعر العادي (أو 2× للـ 1-hour cache). لو الكاش مش هيتعاد استخدامه على الأقل 4 مرات في الـ 5 دقايق، إنت فعليًا بتخسر فلوس مقارنةً بالطلب العادي.
2. الكاش حسّاس بشكل صادم: فاصلة، مسافة زيادة، أو تاريخ متغيّر ({"now": "2026-05-08T14:23"}) في بداية الـ prompt = cache miss. ابعد الأجزاء المتغيّرة عن الجزء المخزّن، وحط الـ cache_control بعد آخر جزء ثابت بالظبط.
3. حد أدنى للحجم: الكاش بيشتغل لمّا الجزء المخزّن ≥ 1024 توكن على Sonnet/Opus، و≥ 2048 توكن على Haiku. أقل من كده Anthropic بترفض الكاشينج تمامًا وبتحاسبك بالسعر العادي بدون أي توفير.
4. الكاش مش shared بين accounts: الـ KV tensors مرتبطة بالـ organization ID. لو نقلت الـ workload لـ workspace تاني، أول طلب من كل workspace بيدفع تكلفة الكتابة من جديد.

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

تطبيقات بطلبات نادرة (طلب كل ساعة أو أكتر بدون 1-hour cache) — هتدفع تكلفة الكتابة بدون استرداد. تطبيقات الـ system prompt فيها ديناميكي بالكامل (مثلاً user_id أو timestamp في أول الـ prompt) — مفيش بادئة ثابتة تكاشّها أصلاً، عدّل ترتيب الـ prompt قبل ما تفكر في caching. تطبيقات بـ prompts قصيرة (أقل من 1024 توكن) — أصلاً Anthropic مش هتقبلها للكاشينج.

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

افتح أكبر system prompt عندك دلوقتي، وضيف cache_control: {"type": "ephemeral"} على آخر بلوك ثابت فيه. شغّل 10 طلبات متتالية، وراقب usage.cache_read_input_tokens في الرد. لو الرقم ده > 0 من الطلب التاني فما فوق، إنت بتوفر فلوس بدءًا من اللحظة دي. لو الرقم 0، ده معناه إن في حاجة متغيّرة في البادئة بتكسر الكاش — ابحث عنها وحرّكها لـ آخر الـ prompt.

المصادر

• Anthropic — Prompt Caching documentation: docs.anthropic.com/en/docs/build-with-claude/prompt-caching
• Anthropic Pricing Page (مايو 2026): anthropic.com/pricing
• Anthropic Cookbook — Prompt Caching examples: github.com/anthropics/anthropic-cookbook
• Pope et al., "Efficiently Scaling Transformer Inference"، MLSys 2023 — الورقة الأصلية لـ KV cache reuse
• Anthropic Engineering Blog — "Extended Caching" (يناير 2026): إعلان الـ 1-hour cache