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

لو تطبيقك بيرسل system prompt حجمه 8000 token مع كل طلب، إنت بتدفع ثمن الـ 8000 token كاملة كل مرة، حتى لو نص الـ system نفسه ما اتغيّرش من 3 شهور. Prompt Caching بيخلّيك تدفع 10% بس من السعر بداية من الطلب الثاني، وبيرجّع التكلفة الشهرية من 98 دولار لـ 34 دولار على نفس الحجم.

Prompt Caching في Claude API: ليه بتدفع نفس الفلوس على كلام مكرر

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

أي تطبيق production فيه Claude بيشتغل بنفس الـ system prompt تقريبًا في كل request. تعليمات للنبرة، أمثلة few-shot، schema للـ tool use، أو توثيق المنتج. الكلام ده ممكن يكون 4000، 8000، أو حتى 30,000 token. والـ API بيحاسبك على إعادة معالجته في كل طلب من أول حرف لآخر حرف.

اللي بيحصل فعلاً إن الـ model محتاج يقرأ الـ tokens دي مرة واحدة، يطلّع منها internal state اسمه KV cache، وبعدين يجاوب على سؤال المستخدم. Prompt Caching بيخلّيك تدفع ثمن المعالجة الأولى مرة، وبعد كده الـ infrastructure بتاعة Anthropic بتحتفظ بالـ state ده لمدة 5 دقايق، وأي طلب تاني فيه نفس البداية بيستفيد منه.

المثال للمبتدئ: خزينة المكتبة

تخيّل مكتبة فيها أمين بيقرأ كتاب 800 صفحة قبل ما يجاوب على أي سؤال، حتى لو السؤال نفسه اختلف. لو 100 زبون سألوه في نفس اليوم، هيقرأ الـ 800 صفحة 100 مرة. ده هدر صريح في وقته ومجهوده.

Prompt Caching بيشبه إن الأمين قرأ الكتاب مرة واحدة وحط ملخّصه مفهرس على المكتب. الزبون رقم 2 لحد رقم 100 بيستفيدوا من الفهرس فورًا، والأمين بس بيقرأ السؤال الجديد ويجاوب. الفرق في الزمن وفي مجهود الأمين كبير، وده بالظبط اللي بيحصل جوّا الـ GPUs بتاعة Anthropic لمّا بتفعّل caching.

التعريف العلمي للـ Prompt Caching

Prompt Caching حسب توثيق Anthropic الرسمي هو آلية بتسمح بإعادة استخدام الـ internal computation state، وتحديدًا الـ Key/Value attention cache، عبر طلبات متعددة. لما بتحط علامة cache_control على جزء من الـ prompt، الـ infrastructure بتحفظ الـ state الناتج من معالجة هذا الجزء، وأي طلب تالي يبدأ بنفس المحتوى تمامًا (prefix match) بيقرأ من الـ cache بدل ما يعيد المعالجة من أول حرف.

التسعير الرسمي على Sonnet 4.5/4.6 (مايو 2026): الكتابة الأولى للـ cache بـ 5 دقايق تكلّف 1.25 ضعف السعر الأصلي ($3.75 لكل مليون token)، والقراءة من الـ cache تكلّف 0.1 ضعف السعر الأصلي ($0.30 لكل مليون token)، أي خصم 90% من ثمن الـ input للأجزاء المخزّنة. الحد الأدنى للجزء القابل للتخزين: 1024 token لـ Sonnet و Opus، و 2048 token لـ Haiku. الفرضية اللي الشرح ده مبني عليها إنك على tier 2 أو أعلى وعندك أكتر من طلب واحد كل 5 دقايق.

الكود الشغّال: قبل وبعد cache_control

الكود ده بيشتغل على anthropic SDK 0.45+ و Python 3.12. الفرق الجوهري بين النسختين سطر واحد بس.

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