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

لو الـ system prompt بتاعك 5000 توكن وبيتبعت في كل request لـ Claude، الفاتورة بتكبر بسرعة. Prompt Caching بيخلّي القراءة الثانية والتالتة من نفس البرومبت بـ 10% من السعر الأصلي، وزمن أول توكن (TTFT) بينخفض في حدود 80% على نفس الموديل.

Prompt Caching في Claude: شرح عملي مع كود وأرقام

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

لمّا تبني تطبيق AI فيه system prompt كبير — مثلًا بوت دعم فني عنده 8000 توكن من توثيق الشركة، أو agent عنده 12 tool definition — كل request جديد بيدفع تكلفة قراءة الـ context كله من الأول. لو عندك 50,000 طلب يومي على Claude Sonnet 4.6، تكلفة الـ input لوحدها ممكن توصل لـ 900 دولار يوميًا لو الـ system prompt 6000 توكن. ودي تكلفة بتتدفع علشان النموذج بيقرأ نفس النص مليون مرة بدون داعي.

مثال للمبتدئ — أمين المكتبة الكسول

تخيّل إنك بتسأل أمين مكتبة 100 سؤال في اليوم، وكل سؤال بيبدأ بنفس المقدمة الطويلة: "أنا طالب طب في السنة التالتة، عندي امتحان فارماكولوجي بعد أسبوع، الجدول بتاعي كذا وكذا، عايز معلومة عن الدواء الفلاني". لو الأمين في كل مرة قعد يقرأ المقدمة من الأول قبل ما يفهم السؤال نفسه، ده هيضيع منك ساعات كل يوم بدون فايدة.

الأمين الذكي بيعمل العكس: أول مرة بس يقرأ المقدمة كويس، يحفظ السياق في دماغه (ذاكرة قصيرة المدى)، وبعدها لو سألته 99 سؤال في نفس الجلسة بيقفز على المقدمة على طول ويرد على كل سؤال لوحده. Prompt Caching بيدّي Claude نفس السلوك ده، بس على مستوى الـ infrastructure مش الإنسان.

التعريف العلمي — KV Cache في طبقة الـ inference

كل ما Claude بيقرأ توكن، بيحوّله لـ matrix من Keys و Values جوّا كل layer من الـ transformer. الحسابات دي تقيلة computationally، وبتاكل أغلب الـ FLOPs في مرحلة الـ prefill (المرحلة اللي قبل ما يبدأ يولّد كلمة). اللي بتعمله Anthropic مع Prompt Caching إنها بتحفظ النتيجة دي على مستوى الـ servers بتاعتها لمدة افتراضية 5 دقايق (TTL قصير) أو ساعة كاملة (TTL طويل، بسعر write أعلى).

في الطلب الأول، أنت بتدفع write cost ≈ 1.25× سعر الـ input العادي. في الطلبات اللي بعدها وخلال الـ TTL، بتدفع read cost ≈ 0.1× سعر الـ input. ده مش ضغط للنص ولا تلخيص، ده تخطّي للحساب نفسه — النموذج بيكمّل من نقطة محفوظة بدل ما يبدأ من الصفر.

الكود الشغّال — cache_control مع Anthropic SDK

import anthropic

client = anthropic.Anthropic()

system_prompt = open("docs/full_handbook.md").read()  # ~6000 token

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": system_prompt,
            "cache_control": {"type": "ephemeral"}
        }
    ],
    messages=[
        {"role": "user", "content": "ايه طريقة استرجاع الفاتورة المرفوضة؟"}
    ]
)

print(response.usage)
# {
#   input_tokens: 12,
#   cache_creation_input_tokens: 6043,
#   cache_read_input_tokens: 0,
#   output_tokens: 180
# }

أول استدعاء هيرجع cache_creation_input_tokens = حجم الـ system prompt. تاني استدعاء (لو خلال 5 دقايق) هيرجع cache_read_input_tokens بنفس الرقم لكن بحساب أرخص بكثير. لو ظهر 0 في الـ cache_read، يبقى الـ TTL خلص أو غيّرت في الـ prompt قبل البلوك المحفوظ.

أرقام قبل وبعد على workload حقيقي

الافتراض: 50,000 request يومي، Claude Sonnet 4.6، system prompt = 6,000 توكن، user message = 200 توكن، input price = 3$ لكل مليون توكن.

• بدون caching: 50,000 × 6,200 توكن × 3$ / 1M = 930$ يوميًا للـ input لوحده.
• مع 5-minute caching (افتراض 80% cache hit بعد warm-up): تكلفة الـ writes ≈ 10,000 طلب × 6,000 × 3.75$ / 1M = 225$. تكلفة الـ reads ≈ 40,000 × 6,000 × 0.30$ / 1M = 72$. تكلفة الـ user messages الجديدة ≈ 30$. الإجمالي ≈ 327$ يوميًا.
• التوفير الفعلي: 65% خصم على فاتورة الـ input = حوالي 600$ يوميًا، أو 18,000$ شهريًا.

الأرقام دي مبنية على pricing Anthropic الرسمي وقت كتابة المقال. راجع الصفحة الرسمية قبل ما تبني عليها قرار، الأسعار بتتغير.

الـ Trade-offs اللي لازم تعرفها قبل ما تشغّلها

• TTL قصير افتراضيًا: الـ cache بيموت بعد 5 دقايق من آخر استخدام. لو تطبيقك فيه فجوات بين الـ requests أطول من كده، هتدفع write cost كل شوية بدل ما توفّر. ينفع تستخدم TTL ساعة بسعر write أعلى لو طبيعة الترافيك متقطّعة.
• الحد الأدنى 1024 توكن: أقل من الرقم ده، الـ cache_control بيتجاهل بدون خطأ ظاهر، يعني هتفتكر إنك بتوفّر وأنت بتدفع كامل.
• الـ cache prefix-based: الـ cache بيقرأ من بداية الـ prompt للنقطة اللي حطيت فيها الـ breakpoint. لو غيّرت أي حرف في الـ system prompt قبل النقطة دي، الـ cache بيتكسر بالكامل ولازم يتعاد بناؤه — وده يعني write cost تاني.
• 4 breakpoints كحد أقصى: ينفع تحط cache_control على 4 أماكن في نفس الطلب — مفيد للترتيب: tools + system + few-shot examples + conversation history.

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

لو الـ system prompt بتاعك أقل من 1024 توكن، أو طلبات المستخدم بتيجي بفجوات أكتر من 5 دقايق بشكل ثابت، أو السياق نفسه بيتغيّر في كل request (chatbot شخصي بـ user data ديناميكية في أول الـ system)، الـ feature دي مش هتفرق معاك. كمان لو شغلك offline batch processing فالـ Batch API أنسب لأنه بيدّي 50% خصم بدون شرط الـ TTL ولا ترتيب الـ tokens.

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

افتح أكبر system prompt في تطبيقك دلوقتي، عُدّ توكناته بـ client.messages.count_tokens. لو طلع فوق 1024 توكن وبيتبعت أكتر من مرة كل 5 دقايق، ضيف "cache_control": {"type": "ephemeral"} على آخر بلوك ثابت فيه، وقارن الفاتورة بعد 24 ساعة في console.anthropic.com. لو الـ cache hit ratio طلع أقل من 50%، رتّب البلوكات بحيث الثابت يبقى في الأول.

المصادر

• التوثيق الرسمي: docs.anthropic.com/en/docs/build-with-claude/prompt-caching
• صفحة الأسعار: anthropic.com/pricing
• إعلان الإطلاق الأصلي: anthropic.com/news/prompt-caching
• Anthropic Python SDK reference: github.com/anthropics/anthropic-sdk-python