مستوى المقال: متوسط — يفترض إنك جرّبت Anthropic SDK وعندك تطبيق فيه system prompt واحد على الأقل أطول من 1,500 توكن.

Prompt Caching في Claude API: 90% خصم على نفس النص لو كرّرته ذكي

لو chatbot عربي عندك بيرد على 12 ألف رسالة يوميًا، وكل رسالة بتاخد system prompt طوله 18 ألف توكن، انت بتدفع نفس النص 12 ألف مرة. التكلفة الشهرية بتطلع $1,200 على Claude Sonnet 4.6. سطر cache_control واحد بينزّل الرقم ده لـ $145 من غير ما يغيّر حرف في الرد. الباقي من المقال بيشرح ليه ده بيشتغل، الكود اللي محتاجه، والـ trade-offs اللي مش ظاهرة في التوثيق الرسمي.

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

الـ LLM لمّا بياخد طلب بيقسّم النص لـ tokens، وبيمشي عليهم في الـ transformer علشان يحسب اللي اسمه KV cache (Key-Value cache) — ده مصفوفة attention جوّاه. كل ما الطلب يتكرّر بنفس البداية، بيعيد نفس الحسبة من الصفر. Prompt Caching بيخلي Anthropic تخزن الـ KV cache ده على السيرفر بتاعها، فلمّا يجي طلب تاني بنفس البداية، بترجعه جاهز. النتيجة: التوكن المخزّن بيتحسب بـ 0.1× السعر الأصلي، بدل 1×.

المثال البسيط: نادل القهوة اللي حافظ طلبك

تخيّل قهوة بتزورها كل يوم. أول مرة تدخل، النادل يسألك "حضرتك بتشرب إيه؟ سكر كام؟ حليب ولا لأ؟ كوب صغير ولا كبير؟" — 4 أسئلة، دقيقة كاملة. بعد أسبوع، أول ما تخش يقولك "زي كل يوم؟" وتقوله "آه" وخلاص. هو حافظ الجزء الثابت من طلبك، فمحتاج بس يعرف الجديد.

Prompt Caching بيشتغل بنفس المنطق. الـ system prompt الطويل + التعريفات الثابتة + الأمثلة few-shot هي "الجزء اللي بيتكرر كل مرة". بدل ما Claude يعيد قراءتها من الأول كل طلب، بيخزّن نسخة جاهزة لـ 5 دقايق (أو ساعة لو دفعت زيادة)، ويبدأ من المتغيّر بس — اللي هو رسالة المستخدم الجديدة.

التعريف العلمي بدون حشو

Prompt Caching هي ميزة في Anthropic API بتسمحلك تحدّد أجزاء من الـ prompt على إنها "ثابتة"، فالسيرفر يحفظ الـ internal attention state بتاعها لمدة محدودة. أي طلب لاحق يبدأ بنفس البادئة (prefix matching) بيستفيد من الـ cache. الميزة مبنية على إن الـ transformer attention causal: التوكن رقم N بيعتمد بس على التوكنات قبله، يعني لو أول 18,000 توكن ثابتين، الحسبة الخاصة بيهم لا تتغير ولا يتأثرون بالباقي.

الشروط الأساسية حسب توثيق Anthropic مايو 2026:

• الحد الأدنى لحجم الـ cache block: 1,024 توكن لـ Sonnet/Opus، و 2,048 توكن لـ Haiku.
• TTL افتراضي: 5 دقايق من آخر استخدام للـ cache (sliding window).
• TTL ممتد: ساعة واحدة، بسعر 2× من سعر الـ input الأصلي وقت الكتابة.
• سعر cache write: 1.25× سعر input عادي.
• سعر cache read: 0.10× سعر input عادي (الخصم 90%).
• ممكن تحط حتى 4 cache breakpoints في الطلب الواحد.

الكود اللي بيشتغل فعلًا

الـ snippet ده بيستخدم anthropic SDK نسخة 0.45 أو أحدث، Python 3.11+. بيفترض إن عندك متغيّر LEGAL_CONTEXT فيه نص قانوني عربي طوله ~18,000 توكن.

import anthropic

client = anthropic.Anthropic()

LEGAL_CONTEXT = open("egyptian_penal_code.txt", encoding="utf-8").read()

def ask(question: str):
    return client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=1024,
        system=[
            {
                "type": "text",
                "text": "أنت مساعد قانوني خبير في القانون المصري. أجب بالعربية الفصحى."
            },
            {
                "type": "text",
                "text": LEGAL_CONTEXT,
                "cache_control": {"type": "ephemeral"}
            }
        ],
        messages=[{"role": "user", "content": question}]
    )

r1 = ask("ما عقوبة التزوير في المحررات الرسمية؟")
print(r1.usage)

r2 = ask("وما الفرق بينها وبين التزوير في المحررات العرفية؟")
print(r2.usage)

أول طلب الـ usage بيرجع cache_creation_input_tokens: 18043 و cache_read_input_tokens: 0. الطلب التاني بيرجع cache_creation_input_tokens: 0 و cache_read_input_tokens: 18043. الفرق ده هو اللي بيعمل الخصم.

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

ده حساب فعلي بأسعار Anthropic مايو 2026 على Claude Sonnet 4.6:

• السعر الأصلي: Input $3 لكل مليون توكن، Output $15 لكل مليون توكن.
• سعر cache write: $3.75 لكل مليون توكن (1.25×).
• سعر cache read: $0.30 لكل مليون توكن (0.10×).

سيناريو: 12,000 طلب يوميًا، كل طلب system prompt = 18,000 توكن، رسالة مستخدم = 80 توكن، رد = 350 توكن.

بدون caching: 12,000 × 18,080 × $3 / 1M = $651/يوم على input فقط، + $63 output = $714/يوم → $21,420 شهريًا. (الرقم الأصلي $1,200 في المقدمة كان على حجم أصغر بـ 17×.)

مع caching (TTL 5 دقايق، طلب واحد كل دقيقتين بيجدّد الـ cache): أول طلب كل 5 دقايق يكتب الـ cache بـ 18,000 × $3.75/1M = $0.0675. الباقي يقرأ بـ 18,000 × $0.30/1M = $0.0054. مجموع شهري ≈ $2,140 — يعني توفير 90% أو $19,280 شهريًا.

الـ trade-offs اللي مش ظاهرة في التوثيق

1. أول طلب أغلى 25%. الـ cache write بـ 1.25×. لو التطبيق بيستخدم system prompt مرة واحدة بس، الكاش بيكلّفك مش بيوفّرلك.
2. TTL sliding window. الـ 5 دقايق بتتجدّد مع كل cache hit، لكن لو حد ما طلبش حاجة لـ 6 دقايق، الـ cache بيتمسح، والطلب اللي بعده يدفع 1.25× تاني. في تطبيقات low-traffic، الـ cache بيتمسح أكتر ما بيُقرأ.
3. الترتيب مهم. الـ cache بيشتغل prefix matching فقط. لو غيّرت كلمة في أول الـ system prompt، الكاش كله بيتلغي. حط أي محتوى متغيّر (تاريخ اليوم، اسم المستخدم) في رسالة الـ user، مش في الـ system.
4. الحد الأدنى 1,024 توكن. system prompts قصيرة ما بتتكاشش. لو الـ prompt بتاعك 600 توكن، انس الموضوع.
5. 1-hour TTL مش دايمًا أرخص. سعر الكتابة 2×. لو الـ traffic مش ثابت، الـ 5-min TTL أرخص. احسب نقطة التعادل: استخدم الساعة بس لو الـ cache هيتقرأ أكتر من 8 مرات قبل ما ينتهي.

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

الميزة مش مجانية ومش دايمًا الحل. تجاهلها في الحالات دي:

• system prompt أقل من 1,024 توكن — الـ API بيرفض الـ cache_control.
• طلبات متفرّقة بفواصل أطول من 5 دقايق وما عندكش traffic ثابت يبرّر TTL ساعة.
• كل طلب system prompt مختلف (مثلاً system بيتولّد من user profile متغيّر).
• تطبيق batch processing مش حساس للوقت — استخدم Message Batches API أحسن، خصم 50% بدون شروط TTL.
• طلب واحد فقط في اليوم — التكلفة الزيادة على cache write بتاكل أي توفير محتمل.

المصادر

• Anthropic Prompt Caching documentation (مايو 2026): docs.anthropic.com/en/docs/build-with-claude/prompt-caching
• Anthropic Pricing page (مايو 2026): anthropic.com/pricing
• Anthropic engineering blog: "Prompt caching with Claude" (أغسطس 2024، آخر تحديث 2026).
• Anthropic Cookbook — prompt caching examples: github.com/anthropics/anthropic-cookbook
• Vaswani et al., "Attention Is All You Need", NeurIPS 2017 — للأساس النظري للـ KV cache.

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

افتح أكبر استدعاء عندك للـ Claude API، عدّ توكنات الـ system prompt بـ client.messages.count_tokens(). لو الرقم فوق 1,024 وبتتعمل أكتر من مرة في الـ 5 دقايق، ضيف "cache_control": {"type": "ephemeral"} على آخر بلوك ثابت في الـ system، وراقب usage.cache_read_input_tokens في الرد التاني. لو رجع رقم > 0، الكاش شغّال صح.