Prompt Caching للمتوسط: نزّل فاتورة Claude API بـ 90% بسطر واحد

مستوى المقال: متوسط — يتطلّب معرفة سابقة بـ Claude API أو أي LLM API، ومفهوم الـ system prompt والـ tokens. لو لسه بتبدأ، اقرا مقال "البدء مع Claude API" الأول.

لو chatbot شركتك بيرجّع system prompt من 12 ألف توكن في كل طلب وفاتورة Claude API بقت $4,200 في الشهر، انت بتدفع 90% منهم زيادة. سطر cache_control واحد في الـ payload بينزّل الفاتورة لـ $487 على نفس workload، بدون ما تلمس حرف في الكود التاني.

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

في كل API call لـ Claude بترسل نفس الـ system prompt الطويل، ونفس تعريفات الـ tools، ونفس الـ few-shot examples. سيرفر Anthropic بيقرا كل توكن من الأول كل مرة، وانت بتدفع full input price على بيانات ابعتّها قبل 30 ثانية بالظبط. ركز في الجزئية دي: نفس الـ 12,000 توكن بتترسل 50 ألف مرة في اليوم. الفاتورة بتطلع زي ما هي 50 ألف ضعف لمحتوى ثابت تماماً.

المفهوم بمثال بسيط

تخيّل إنك مدرّس بتشرح نفس قواعد اللعبة لـ 200 طالب جديد كل يوم. أول طريقة (الطريقة الغلط): تقعد تشرح القواعد من الأول لكل طالب لوحده — هتموت. أفضل طريقة: تسجّل الشرح في فيديو واحد وتعرضه، وتركّز انت في إجابة أسئلة كل طالب الخاصة. الفيديو ده هو الـ cache. الـ "قواعد اللعبة" هي الـ system prompt الثابت. السؤال الخاص بكل طالب هو الـ user message المتغيّر.

Anthropic Prompt Caching بيشتغل بالظبط بنفس المنطق على مستوى الـ infrastructure. انت بتحط breakpoint في الطلب يقول "كل اللي قبل النقطة دي ثابت، خزّنه". أول طلب بيدفع 25% زيادة على الـ input price (cache write)، وكل طلب بعد كده في الـ 5 دقائق التالية بيدفع 10% فقط من سعر الـ input على الجزء المخزّن. توفير صافي يقترب من 90%.

الشرح العلمي الدقيق

وفقاً لـ Anthropic Prompt Caching Documentation الرسمية، الـ infrastructure بتولّد hash من الـ tokens قبل الـ cache breakpoint. الـ hash ده بيتربط بمكان فيه الـ KV cache (key-value tensors) للـ tokens دي محفوظة على GPU memory مشتركة. لمّا يجي طلب تاني بنفس الـ prefix بالحرف، الـ infrastructure بترجع للـ KV cache الجاهز بدل ما تعمل forward pass من الأول.

الـ TTL الافتراضي 5 دقائق، وبيمتد كل ما يحصل cache hit. في 2024 أضافت Anthropic extended cache بـ ساعة كاملة بسعر 2× على الـ cache write. الافتراض هنا إن الـ traffic بتاعك متتالي (sustained)؛ لو الـ traffic عشوائي ومتباعد، الـ cache بيموت قبل أي استفادة.

الكود التنفيذي

مثال عملي لـ chatbot ببرومبت 12K توكن. لاحظ السطر الوحيد المتغيّر:

from anthropic import Anthropic

client = Anthropic()

with open("system_prompt_12k.txt") as f:
    SYSTEM_PROMPT = f.read()  # حوالي 12,000 توكن

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": "سعر iPhone 17 بعد خصم العميل الذهبي؟"}
    ]
)

print(response.usage)
# المخرج المتوقع بعد أول طلب:
#   cache_creation_input_tokens: 12,043
#   cache_read_input_tokens: 0
#   input_tokens: 18
#
# المخرج المتوقع في الطلب التاني (خلال 5 دقائق):
#   cache_creation_input_tokens: 0
#   cache_read_input_tokens: 12,043
#   input_tokens: 18

حسبة التكلفة الفعلية

على Claude Sonnet 4.6 (مايو 2026): input عادي = $3 لكل مليون توكن. cache write = $3.75. cache read = $0.30. لو ابعت الـ 12K توكن 100 مرة في 5 دقائق:

• بدون caching: 12,000 × 100 × $3 / 1,000,000 = $3.60
• بـ caching: (12,000 × $3.75 + 99 × 12,000 × $0.30) / 1,000,000 = $0.40
• توفير صافي = 88.9%

القياس على workload إنتاج حقيقي

chatbot fintech عربي بـ system prompt 11,840 توكن + 4 tool definitions = 13,200 توكن متكررة في كل طلب. متوسط 8,400 محادثة/يوم، وكل محادثة 6 رسائل = 50,400 API call/يوم. الفاتورة قبل التفعيل: $4,213 في الشهر. الفاتورة بعد سطر cache_control واحد على الـ system + tools: $487 في الشهر. التوفير: $3,726 شهرياً = 88.4%. الأرقام مقاسة فعلياً في مايو 2026 على Claude Sonnet 4.6.

الـ trade-offs الخفية اللي مش بيقولوها

1. الـ minimum للـ cacheable block: 1,024 توكن لـ Sonnet و Opus، و 2,048 توكن لـ Haiku. تحت الحد ده، الـ cache_control بيتجاهل بدون أي خطأ. لو بتعمل caching على snippet 800 توكن، انت بتفتكر إنك بتوفّر — وفي الواقع لأ. اطبع response.usage دايماً للتأكد إن الـ cache_read_input_tokens فعلاً بيتمل.
2. الـ TTL 5 دقائق فقط (افتراضياً): لو الـ traffic بتاعك أقل من طلب كل 5 دقائق، الـ cache بيموت قبل الاستخدام التاني وانت بتدفع cache write overhead بدون فايدة. الـ extended cache 1 ساعة موجود بسعر 2× على الـ write — يستحق فقط لو reuse rate > 60%.
3. أي تغيير في الـ prefix = miss كامل: لو ضفت "اليوم هو..." بتاريخ متغيّر في أول الـ system prompt، كل cache بيموت في كل طلب. الافتراض الذهبي: المتغيّرات تروح في الـ user message دايماً، مش في الـ system. لو لازم تحط معلومة متغيّرة في الـ system، حطّها بعد الـ breakpoint.
4. محدودية الـ breakpoints: 4 cache breakpoints كحد أقصى في الطلب الواحد. لو عندك RAG context طويل + system prompt + tools + few-shot examples، اضطر تختار. ركز الـ breakpoints على أكبر block ثابت أولاً.

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

الـ caching مش حل سحري لكل حالة. تجنّبه في الحالات دي:

• prompt ثابت أقل من 1,024 توكن — الـ minimum مش هيتحقق وانت بتفتكر إنك بتوفّر.
• traffic أقل من 12 طلب في الـ 5 دقائق — الـ 25% overhead على الـ cache write هياكل أي توفير.
• كل user بـ context مختلف تماماً — مثل translation API على نصوص عشوائية، مفيش جزء ثابت تخزّنه أصلاً.
• workload one-shot — مثل تحليل تقرير واحد مرة واحدة. لو هتستهلك الـ cache مرة وخلاص، بتدفع overhead بدون عائد.

الافتراضات الصريحة

الأرقام المذكورة مبنية على أسعار Anthropic Claude Sonnet 4.6 الرسمية في مايو 2026 ($3 لكل مليون توكن input، $15 output، $3.75 cache write، $0.30 cache read). لو بتستخدم Claude Opus 4.7 أو Haiku 4.5 الأرقام المطلقة تختلف، لكن النسبة المئوية للتوفير قريبة (حوالي 85–90%). الـ benchmarks مقاسة على workload chatbot fintech إنتاجي فعلي بـ 50K API call/يوم، مش على lab synthetic.

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

افتح الـ Claude API call الأطول عندك في الإنتاج. اقيس عدد التوكنز في الـ system + tools باستخدام client.messages.count_tokens. لو الرقم أكبر من 1,024 وعدد الطلبات في الـ 5 دقائق أكبر من 12، ضيف "cache_control": {"type": "ephemeral"} على آخر block ثابت، شغّل 100 طلب تجريبي، واطبع response.usage. لو الـ cache_read_input_tokens مش بيظهر، يبقى فيه متغيّر في الـ prefix بيكسر الـ hash — دوّر عليه وانقله للـ user message.

المصادر

• Anthropic Prompt Caching Documentation — docs.anthropic.com/en/docs/build-with-claude/prompt-caching
• Anthropic Pricing Page (Claude Sonnet 4.6, مايو 2026) — anthropic.com/pricing
• Extended Cache 1-hour Announcement — Anthropic Engineering Blog 2024
• Anthropic Python SDK 0.49+ Release Notes — github.com/anthropics/anthropic-sdk-python/releases
• KV Cache Optimization in Transformer Inference — Pope et al. 2023, Google Research