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

لو chatbot عندك بيبعت نفس الـ system prompt الطويل مع كل سؤال، إنت بتدفع تكلفة معالجة نفس الـ 8000 token من أول وجديد كل مرة. سطر واحد اسمه cache_control بينزّل تكلفة الجزء المتكرر دا بنسبة 90%، ويقطع زمن أول token بنسبة تتراوح بين 60% و 85% حسب حجم السياق.

Prompt Caching في Claude API: ليه ودلوقتي بالظبط

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

تخيّل تطبيق بيرد على أسئلة الموظفين عن سياسة الشركة. السياسة 30 صفحة (حوالي 12K token). كل سؤال بيتبعت لـ Claude مع نفس الـ 12K token دول كـ system prompt. لو في 5000 سؤال يومي، إنت بتدفع تكلفة معالجة 60 مليون token مكرر يومياً بدون فايدة. الـ Prompt Caching بيخلّي Claude يحفظ الـ prefix دا في ذاكرة جانبية لمدة 5 دقايق (افتراضياً) أو ساعة، وبيرجّعه في الطلبات اللي بعد كده بـ 10% من السعر فقط.

المثال البسيط: طلبة الكلية وملخص المنهج

تخيّل دكتور بيشرح لطلبة كلية مادة كاملة. بدل ما الدكتور يقرأ كل المقدمة من البداية لكل طالب يدخل المحاضرة، هو بيكتبها على السبورة مرة واحدة. الطلبة الجداد لما يدخلوا، بيقروا اللي على السبورة في ثانيتين بدل ما الدكتور يعيد الشرح في 20 دقيقة. السبورة دي هي الـ Cache. أول طالب دفع للدكتور تكلفة الكتابة، الباقي بياخدوا نفس المعلومة بتكلفة قراءة بسيطة.

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

الـ Prompt Caching في Claude API بيعتمد على آلية اسمها ephemeral cache. لما تحط cache_control: {"type": "ephemeral"} على block معين في الرسالة، Claude بيخزّن نتيجة معالجة الـ tokens اللي قبل الـ breakpoint دا في key-value store داخلي. أي طلب لاحق بنفس الـ prefix الحرفي (نفس الـ tokens بنفس الترتيب) بيعمل "cache hit" خلال نافذة الـ TTL. الحد الأدنى لتفعيل الـ cache هو 1024 token للـ Sonnet/Haiku و 2048 token لـ Opus. أقل من كده، الطلب بيشتغل لكن الـ cache مش بيتفعّل.

الكود الشغّال (Anthropic SDK 0.45+)

import anthropic

client = anthropic.Anthropic()

POLICY_DOC = open("company_policy.txt").read()  # 30 صفحة، ~12K token

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

print(response.usage)
# cache_creation_input_tokens=12048
# cache_read_input_tokens=0
# input_tokens=22 (السؤال فقط)

أول طلب بيعمل cache write بتكلفة 1.25× من سعر الـ input العادي. أي طلب بنفس الوثيقة خلال 5 دقايق بيرجّع cache_read_input_tokens=12048 بتكلفة 0.1× فقط.

الأرقام الفعلية: 5000 سؤال يومي على Sonnet 4.6

• سعر input عادي: $3 لكل مليون token.
• سعر cache write (5 دقايق): $3.75 لكل مليون token.
• سعر cache read: $0.30 لكل مليون token.

بدون caching: 5000 طلب × 12,048 token × $3/M = $180.72 يومياً = ~$5,420 شهرياً.

مع caching: لنفترض 1 cache write كل 5 دقايق (288 write يومياً) و 4712 cache read. الحساب: (288 × 12,048 × $3.75/M) + (4712 × 12,048 × $0.30/M) = $13.01 + $17.03 = $30.04 يومياً = ~$901 شهرياً. توفير 83%.

4 trade-offs لازم تعرفها قبل ما تشغّلها

1. الكتابة الأولى أغلى: أول طلب بيدفع 1.25× السعر العادي. لو الـ cache مش هيتقرى مرة تانية على الأقل خلال 5 دقايق، إنت خسرت فلوس بدل ما توفّر.
2. الترتيب لازم ثابت: أي تعديل بايت واحد في الـ prefix بيلغي الـ cache كله. حط الجزء المتغير (سؤال المستخدم) في الآخر دايماً، والثابت (الوثائق، التعليمات) في الأول.
3. عزل على مستوى workspace: من 5 فبراير 2026، الـ cache بيتعزل لكل workspace لوحده. لو تطبيقك على workspaces متعددة، كل واحد ليه cache منفصل.
4. حد أقصى 4 breakpoints: ممكن تحط cache_control على 4 نقاط مختلفة في الطلب فقط. لو محتاج تكييش طبقات أكتر، هتدمج بعضها.

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

الـ caching بيكلّفك أكتر مما يوفّر في 3 حالات:

• الـ system prompt قصير (أقل من 1024 token). الـ cache مش بيتفعّل أصلاً، وممكن تكون دفعت overhead بدون فايدة.
• كل طلب من مستخدم مختلف بسياق مختلف تماماً. مفيش prefix مشترك يستحق الكتابة.
• تطبيق batch جالك مرة في اليوم بـ 100 طلب. الفجوة بين الطلبات أكبر من 5 دقايق، فالـ cache بيموت قبل ما يتقري.

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

افتح كود تطبيقك دلوقتي. لو الـ system prompt بتاعك أكبر من 2KB واتبعت أكتر من 10 مرة في الساعة، ضيف cache_control: {"type": "ephemeral"} على آخر block ثابت قبل الجزء المتغير. شغّله على staging ساعة واحدة، اطبع response.usage.cache_read_input_tokens في الـ logs، وقارن الفاتورة قبل وبعد. لو cache_read بقى أكبر من cache_creation بنسبة 4:1 على الأقل، إنت كسبت. غير كده، الـ TTL بتاعك قصير على نمط استخدامك.

المصادر

• توثيق Anthropic الرسمي للـ Prompt Caching: docs.anthropic.com/en/docs/build-with-claude/prompt-caching
• صفحة التسعير الرسمية لـ Claude API: platform.claude.com/docs/en/about-claude/pricing
• إعلان Anthropic عن العزل على مستوى workspace (فبراير 2026).
• توثيق المعلمة cache_control ومعاملات الـ TTL في Anthropic Python SDK 0.45+.