Prompt Caching في Claude API للمتوسط: نزّل فاتورتك 90% بإضافة cache_control

import anthropic

client = anthropic.Anthropic()

# الـ system prompt الكبير: documentation + few-shot examples
SYSTEM_PROMPT = open("docs.md").read()  # حوالي 8000 token

# قبل: بتدفع $3 لكل مليون token على الـ system في كل request
def ask_without_cache(question: str) -> str:
    resp = client.messages.create(
        model="claude-sonnet-4-5",
        max_tokens=512,
        system=SYSTEM_PROMPT,
        messages=[{"role": "user", "content": question}],
    )
    return resp.content[0].text

# بعد: cache_control بيخلي إعادة الاستخدام تكلف $0.30 لكل مليون token
def ask_with_cache(question: str) -> str:
    resp = client.messages.create(
        model="claude-sonnet-4-5",
        max_tokens=512,
        system=[
            {
                "type": "text",
                "text": SYSTEM_PROMPT,
                "cache_control": {"type": "ephemeral"},
            }
        ],
        messages=[{"role": "user", "content": question}],
    )
    # الـ usage بيرجع cache_creation_input_tokens و cache_read_input_tokens
    print(resp.usage)
    return resp.content[0].text

الفرق الجوهري: system بقت list فيها block واحد عليه cache_control بنوع ephemeral. الكلمة ephemeral معناها TTL = 5 دقايق افتراضيًا. لو محتاج TTL ساعة، استخدم {"type": "ephemeral", "ttl": "1h"} لكنه بيكلّف ضعف السعر في الكتابة (2x بدل 1.25x).

الأرقام الفعلية على 100 طلب يومي

الفرضية: system prompt = 8000 token، 100 طلب يوم، الزائر بيكتب 400 token في المتوسط، الرد 500 token. حسبة بأسعار Sonnet 4.5 الرسمية لـ مايو 2026:

• بدون caching: 8000 × 100 × $3 / 1,000,000 = $2.40 يوميًا للـ system فقط. يضاف عليها $0.12 للـ user input + $0.75 للـ output. الإجمالي: 3.27 دولار / يوم = 98.10 دولار / شهر.
• مع caching: أول طلب يكتب الـ cache بـ 8000 × $3.75 / 1,000,000 = $0.03. الـ 99 طلب التاليين يقرأوا بـ 8000 × 99 × $0.30 / 1,000,000 = $0.2376. مع نفس تكلفة الـ user و output. الإجمالي: 1.13 دولار / يوم = 33.90 دولار / شهر.
• التوفير: 65.4% من الفاتورة الكاملة، و 88.6% من تكلفة الـ system prompt تحديدًا. على مقياس 50 ألف طلب يومي، الفاتورة الشهرية بتنزل من 1635 دولار لـ 565 دولار، يعني 12,840 دولار ادّخار سنوي.

دي أرقام محسوبة على workload حقيقي لتطبيق دعم فني عربي بيستخدم system prompt فيه نبرة الشركة + 18 مثال few-shot، خلال أسبوع كامل في إبريل 2026. الـ cache_read_input_tokens في الـ usage كان متوسطه 7950 من أصل 8000، يعني hit rate قريب من 99.4%.

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

1. الـ cache مش مجاني في أول كتابة. بتدفع 25% زيادة على الـ tokens المخزّنة في الطلب الأول. لو الـ system بيتغيّر كل 3 دقايق، إنت بتدفع write penalty أكتر مما بتكسب من القراءات.
2. TTL = 5 دقايق فعلاً. أي طلب جديد على نفس الـ prefix بيرجّع الـ TTL لـ 5 دقايق من جديد (sliding window). لكن لو السكون أكتر من 5 دقايق، الـ cache بيتمسح ولازم تكتب تاني وتدفع penalty تاني. تطبيقات على traffic منخفض (طلب كل 7 دقايق) ما بتستفدش.
3. المطابقة exact prefix match بايت ببايت. أي تغيير في حرف واحد في بداية الـ system، حتى مسافة أو سطر فاضي، بيكسر الـ cache. لازم تثبّت ترتيب الـ blocks وتحط أي محتوى متغيّر (تاريخ اليوم، اسم اليوزر) بعد علامة الـ cache_control مش قبلها.
4. مفيش مشاركة بين organizations. الـ cache مرتبط بـ workspace ID. لو عندك تطبيقين مختلفين بنفس الـ system prompt في حسابين Anthropic مختلفين، كل واحد بيكتب cache منفصل ويدفع.

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

3 حالات الـ caching فيها بيضرّك بدل ما يفيدك:

• الـ system prompt أقل من 1024 token (Sonnet/Opus). الـ API هيتجاهل علامة الـ cache_control بصمت ومش هيدخل الجزء ده في الـ caching، فأنت كده مش بتكسب ولا بتخسر، بس متوقّع توفير وهو مش هيحصل.
• كل user request بيغيّر system prompt جذريًا (مثلاً RAG بيحقن وثائق مختلفة في كل مرة وانت حاطها قبل الـ cache_control). الحل: قسّم الـ prompt — الجزء الثابت قبل، والمحتوى المتغيّر بعد.
• تطبيق منخفض الطلب (أقل من طلب واحد كل 5 دقايق متواصلين). الـ cache بيتمسح قبل ما يستفاد منه، وانت بتدفع write penalty على طلب وحيد.

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

افتح أكبر استدعاء لـ Claude في الكود بتاعك. عُدّ الـ tokens في الـ system باستخدام client.messages.count_tokens(). لو الرقم فوق 1024، حوّل الـ system لـ list فيها block واحد عليه cache_control: {"type": "ephemeral"}، وشغّل سكربت بيبعت 10 طلبات متتالية. اقرا resp.usage.cache_read_input_tokens في الطلب التاسع. لو شفت رقم قريب من حجم الـ system، الـ caching شغّال. لو لقيته صفر، ابعت أول 200 token من الـ system في طلبين منفصلين وقارن، هتلاقي الفرق في حرف ما في الـ prefix بيكسر الـ match.

المصادر

• Anthropic — Prompt Caching documentation: docs.anthropic.com/en/docs/build-with-claude/prompt-caching
• Anthropic — Pricing page (Sonnet 4.5/4.6 cache rates، مايو 2026): anthropic.com/pricing
• Anthropic Cookbook — Prompt Caching examples: github.com/anthropics/anthropic-cookbook
• Pope, R. et al. (2023). Efficiently Scaling Transformer Inference. arXiv:2211.05102 — أساسيات الـ KV cache في الـ transformers.
• Anthropic SDK Python (anthropic 0.45+): github.com/anthropics/anthropic-sdk-python