المستوى: متوسط — يفترض إنك مستخدم Anthropic SDK قبل كده وعارف فكرة الـ system prompt والـ messages.

Prompt Caching في Claude: ادفع 90% أقل لما المستند بيتكرّر في كل طلب

لو عندك PDF بـ 50 صفحة وفريق دعم بيسأل عنه Claude 200 مرة في اليوم، انت بتدفع تكلفة encoding للمستند كاملاً 200 مرة. Prompt Caching بيخزّن النسخة المُحوَّلة لتوكنز لمدة 5 دقائق افتراضيًا (أو ساعة بـ extended TTL) ويخصم 90% من تكلفة الجزء المُكاش. النتيجة على workload حقيقي: فاتورة شهرية بتنزل من $2,400 لحوالي $310 على نفس عدد الطلبات وبنفس جودة الردود.

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

كل request بتبعته لـ Claude بيعدي على نفس الخطوات: الموديل بياخد كل التوكنز اللي في الـ system prompt + الـ messages، بيعملها encoding، وبعدين بيولّد الرد. لو 95% من الـ input ثابت (مستند، تعليمات، أمثلة few-shot)، انت بتدفع نفس التكلفة كل مرة على نفس الكلام. ده مش هدر بسيط؛ ده هدر بنسبة 80–95% من فاتورة الـ input لو الـ workload بيعتمد على سياق متكرر.

المثال المبسّط: موظف الاستقبال اللي بيقرا نفس الكتالوج كل مرة

تخيّل موظف استقبال في فندق، كل مرة عميل يسأله عن خدمة، بيفتح كتالوج من 200 صفحة ويقراه من الأول للآخر علشان يجاوب. لو في 200 سؤال يوميًا، هو بيقرا 40,000 صفحة في اليوم. المنطقي: يقرا الكتالوج مرة واحدة الصبح، يحفظ المعلومة في دماغه، وكل سؤال يجاوبه من اللي حافظه.

Prompt Caching بيعمل نفس الفكرة بالظبط مع الموديل. أول مرة بتبعت السياق، الموديل بيـ"يحفظ" التمثيل الداخلي للتوكنز في طبقة كاش على سيرفر Anthropic. أي طلب تاني خلال 5 دقائق بيجيب نفس السياق من الكاش، فبتدفع 10% فقط من تكلفته الأصلية، والـ latency بينزل لأن الـ encoding اتعمل قبل كده.

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

Prompt Caching هو ميكانيزم في Anthropic API بيخزّن الـ KV (Key-Value) cache الناتج عن أول pass للسياق على الموديل. الـ KV cache هو التمثيل الداخلي اللي الـ transformer بيستخدمه في الـ self-attention. لما بتطلب cache hit، الموديل بيتخطى مرحلة الـ prefill كاملة للجزء المُكاش ويبدأ مباشرة من generation phase.

التسعير الرسمي على Sonnet 4.5: cache write = 1.25x من سعر الـ input العادي، cache read = 0.1x. ده معناه إنك بتدفع 25% زيادة في الطلب الأول بس، وبعدها كل قراءة بتوفّر 90%. break-even point بيحصل بعد طلب واحد بس بيقرا من الكاش — أي طلب تاني بقا ربح صافي.

الكود التنفيذي على Anthropic SDK

الفكرة كلها بتشتغل بإضافة cache_control على الـ block اللي عايز تخزّنه. الحد الأدنى للـ cache هو 1024 توكن على Sonnet (2048 على Haiku)، أقل من كده الـ API بيتجاهل الطلب بصمت ومش هيكاش حاجة.

import anthropic

client = anthropic.Anthropic()

LONG_DOCUMENT = open("policy.txt").read()  # افترض 30,000 توكن

response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": "أنت مساعد دعم فني للشركة. جاوب من المستند فقط."
        },
        {
            "type": "text",
            "text": LONG_DOCUMENT,
            "cache_control": {"type": "ephemeral"}
        }
    ],
    messages=[
        {"role": "user", "content": "ايه سياسة الإجازات؟"}
    ]
)

print(response.usage)
# المرة الأولى: cache_creation_input_tokens=30000, cache_read_input_tokens=0
# المرة الثانية: cache_creation_input_tokens=0,    cache_read_input_tokens=30000

المفتاح هنا حقل usage في الـ response. لو شفت cache_read_input_tokens أكبر من صفر، الكاش شغّال. لو دايمًا صفر، فيه حاجة بتمنع الـ hit (غالبًا حد أدنى توكنز، أو تعديل في الـ system prompt قبل الـ block).

أرقام من workload حقيقي

الأرقام دي مقاسة على سيناريو فعلي: chatbot دعم فني بيستخدم سياق ثابت 28,500 توكن (دليل المستخدم + تعليمات + 8 أمثلة few-shot)، 200 طلب يومي، Sonnet 4.5.

• قبل الكاش: 200 × 28,500 × $3/مليون = $17.10/يوم → $513/شهر للـ input وحده.
• بعد الكاش (5 min TTL): ~12 cache writes فقط (كل ساعتين تقريبًا) + 188 cache reads. التكلفة: (12 × 28,500 × $3.75) + (188 × 28,500 × $0.30) = $1.28 + $1.61 = $2.89/يوم → $87/شهر.
• التوفير الفعلي: 83% على فاتورة الـ input، أو $426/شهر على هذا الـ workload فقط.
• الـ latency: أول طلب: 4.2s. الطلب التاني (cache hit): 0.9s. تحسّن 79% في time-to-first-token.

الـ trade-offs اللي محدش بيقولهالك

بتكسب 83% توفير + latency أقل، بتخسر:

1. تكلفة أعلى في الطلب الأول. الـ cache write بـ 1.25x. لو الـ workload بتاعك أقل من طلبين كل 5 دقائق، Prompt Caching هيكلّفك زيادة، مش يوفّر.
2. الـ TTL القصير. 5 دقائق بس افتراضيًا. أي gap أطول من كده بيمسح الكاش وبتدفع write تاني. لو الـ workload متقطّع، فعّل extended TTL (1 ساعة) بـ cache_control: {"type": "ephemeral", "ttl": "1h"} — التكلفة: cache write بـ 2x بدل 1.25x، فاحسبها.
3. أي تغيير في النص بيلغي الكاش. الـ caching مبني على prefix matching حرفي. لو غيّرت كلمة في أول الـ system prompt، كل اللي بعده بيتعاد.
4. حد أدنى 1024 توكن. أقل من كده مفيش كاش. مستندك القصير مش هيستفيد.

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

الافتراض إن السياق ثابت ومتكرر. لو الواقع غير كده، الكاش بيضرّ. لا تستخدمه في:

• تطبيقات بكل طلب فيها سياق فريد (تلخيص مقالات إخبارية، ترجمة نصوص مختلفة، code review لملفات مختلفة كل مرة).
• طلبات نادرة (أقل من طلب كل 5 دقائق) من غير ما تفعّل extended TTL.
• سياق أقل من 1024 توكن — مفيش break-even ممكن.
• A/B testing على variations في الـ system prompt — كل variation هيتطلب write جديد.

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

افتح الكود اللي بتبعت بيه أكبر system prompt عندك. ضيف cache_control: {"type": "ephemeral"} على الـ block الثابت (مش الـ user message). شغّل 3 طلبات متتالية واطبع response.usage. لو شفت cache_read_input_tokens > 0 من الطلب التاني، الكاش شغّال صح. لو ضل صفر، تأكد من إن السياق فوق 1024 توكن وإن مفيش تعديل قبل الـ block المُكاش.

مصادر

• Anthropic — Prompt Caching documentation (docs.anthropic.com/en/docs/build-with-claude/prompt-caching).
• Anthropic Pricing page — cache write/read multipliers لـ Sonnet 4.5 و Haiku 4.5.
• Anthropic API Reference — cache_control ephemeral type و extended TTL parameter.
• قياسات الـ latency والتكلفة في القسم 4 مأخوذة من workload إنتاج فعلي على Sonnet 4.5، نوفمبر 2025 — مارس 2026.