المستوى المطلوب: متوسط — مناسب لمن يعمل على تطبيقات Claude API ويعرف أساسيات الـ system prompt واستدعاء الـ messages endpoint. لو لسه مبتدئ تمامًا، اقرأ أولًا أساسيات Anthropic SDK ثم ارجع.

Prompt Caching بالعربي: وفّر 90% من تكلفة Claude API على الـ system prompt المتكرر

لو الـ system prompt بتاع تطبيقك أطول من 1024 توكن وبتبعته في كل طلب، أنت بتدفع تكلفته كاملة كل مرة بدون داعي. Prompt Caching من Anthropic بياخد التكلفة دي وينزّلها 90% بسطر واحد في الـ payload، طول ما الجزء ده بيتكرّر خلال نافذة الـ 5 دقائق.

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

تطبيقات Claude الحقيقية مش بتبعت رسالة واحدة. الـ system prompt فيه تعليمات تفصيلية، مع 3 إلى 5 أمثلة few-shot، وأحيانًا سياق RAG كبير. الجزء ده ثابت بين كل طلب وطلب، لكن الـ API بيعدّ توكناته ويفوترها بالكامل في كل request.

افتراض إن system prompt عندك 8000 توكن، بتشتغل على Claude Sonnet 4.6 (سعر $3 لكل مليون توكن input)، وبتاخد 1000 طلب في اليوم: 24 دولار يوميًا على نص ما اتغيّرش حرف. الفاتورة الشهرية: 720 دولار من غير لزوم. ده الجزء اللي Prompt Caching بيهاجمه.

المثال البسيط: زي مدرّس بيعيد كل درس من البداية

تخيل مدرّس بيدخل الفصل كل ساعة، وفي كل مرة بيعيد شرح القواعد العامة للحصة من الصفر قبل ما يبدأ الدرس الجديد. الطلاب نفس الطلاب، القواعد نفس القواعد، الفرق بس في الدرس. الوقت اللي بيضيع في إعادة الشرح هو اللي ممكن يستثمر في درس جديد بدلًا منه.

Prompt Caching بيخلي المدرّس يكتب القواعد على السبورة مرة واحدة في أول حصة، ويبدأ كل حصة بعدها بالدرس مباشرة. لو القواعد اتغيّرت لأي سبب، السبورة بتتمسح ويُعاد كتابتها من جديد. ده بالظبط اللي بيحصل مع system prompt بتاعك.

تعريف Prompt Caching بدقة

Prompt Caching ميزة في Anthropic API بتسمح لك تعلّم على block معين في الـ input إنه قابل للتخزين على infrastructure Anthropic. التطبيق العملي بيتم بإضافة الحقل cache_control: { type: "ephemeral" } على content block واحد أو أكثر، سواء كان system prompt، documents، أو tool definitions.

أول طلب بيمر على الـ block ده بيعمل cache write بتكلفة 1.25× السعر الأصلي للـ input. كل طلب بعد كده طول ما الـ cache صالح بيعمل cache read بتكلفة 0.1× — يعني خصم 90% على الجزء المخزّن.

الشروط التشغيلية اللي لازم تعرفها

• الحد الأدنى: الـ block المراد تخزينه لازم يكون 1024 توكن أو أكثر لـ Claude Sonnet و Opus، و 2048 توكن لـ Haiku. أقل من كده الـ API بيتجاهل التخزين تمامًا بدون أي خطأ.
• المدة الافتراضية: 5 دقائق من آخر استخدام (sliding window). Anthropic بتدعم ساعة كاملة كـ option بتكلفة write أعلى (2× بدل 1.25×).
• الترتيب مهم: الجزء الثابت لازم يجي قبل الجزء المتغير. الـ cache بيبدأ من بداية الـ prompt وبيكسر عند أول اختلاف بايت ببايت.
• عزل المساحات: ابتداءً من فبراير 2026 بقى الـ cache معزول على مستوى الـ workspace، يعني تطبيق على workspace مش هيستفيد من cache تطبيق تاني حتى لو في نفس المؤسسة.

إزاي تشغّله — كود Python شغّال

import anthropic

client = anthropic.Anthropic()

# system prompt طويل: تعليمات + أمثلة few-shot + سياق RAG
LONG_SYSTEM = """أنت مساعد دعم فني لشركة برمجيات.
[... تعليمات تفصيلية حوالي 6000 توكن ...]
[... 5 أمثلة few-shot لمحادثات مرجعية ...]
[... سياق RAG من قاعدة المعرفة الداخلية ...]
"""

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": LONG_SYSTEM,
            "cache_control": {"type": "ephemeral"}
        }
    ],
    messages=[
        {"role": "user", "content": "إزاي أحدّث كلمة السر؟"}
    ]
)

usage = response.usage
print(f"cache_creation: {usage.cache_creation_input_tokens}")
print(f"cache_read:     {usage.cache_read_input_tokens}")
print(f"input_normal:   {usage.input_tokens}")

أول call هتلاقي cache_creation_input_tokens = 8000 و cache_read_input_tokens = 0. ثاني call على نفس الـ system خلال 5 دقايق هتلاقي cache_read_input_tokens = 8000 و cache_creation = 0. ده دليلك إن الـ caching فعّال.

الأرقام الفعلية — قبل وبعد

الافتراضات: Claude Sonnet 4.6 بسعر $3 لكل مليون توكن input، system prompt بحجم 8000 توكن، 1000 طلب في الساعة موزّعة بالتساوي خلال النافذة.

• بدون caching: 8000 × 1000 × 3 ÷ 1,000,000 = $24/ساعة على الـ system prompt لوحده.
• مع caching: request واحد write (8000 × $3.75/M = $0.030) + 999 reads (8000 × 999 × $0.30/M = $2.40). الإجمالي: $2.43/ساعة.
• الفرق: توفير 89.9% — يعني $21.57 في الساعة، أو حوالي $517 في اليوم، أو ~$15,500 شهريًا على نفس الـ workload.

الافتراض إن الطلبات متقاربة زمنيًا. لو الفجوات بين الطلبات بتعدي 5 دقايق بشكل متكرّر، الـ cache هيتكسر ويتعمل write جديد كل مرة، وفي الحالة دي الفايدة بتقل بشكل ملحوظ.

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

• بتكسب: 90% خصم على الجزء المتكرّر من الـ input، وده غالبًا 70 إلى 90% من إجمالي حجم الـ prompt في تطبيقات RAG ومحادثات الدعم.
• بتخسر 25% على الـ write الأولي. لو طلب واحد فقط في الـ 5 دقايق وميتكرّرش، الـ caching بيتكلّف 1.25× بدون ما تحصل على read واحد يستهلك الـ cache.
• بتخسر مرونة في التحديث. أي تغيير في الـ cached block — حتى مسافة واحدة أو فاصلة — بيكسر الـ cache ويفرض write جديد. لو بتولّد system prompts ديناميكيًا، خلّي الجزء الديناميكي خارج الـ cache breakpoint.
• تعقيد الـ debugging: الـ usage object فيه حقول جديدة لازم تتابعها. لو نسيت تطبعها، هتفتكر إنك بتدفع كامل من غير ما تكتشف إن الـ cache مش شغّال أصلاً.

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

• system prompt قصير (أقل من 1024 توكن): الـ API هيتجاهل الـ cache_control بصمت. مفيش فايدة ولا ضرر، لكن لا تتوقع توفير.
• طلبات متفرقة (rate أقل من واحد كل 5 دقايق): هتدفع write زيادة كل مرة بدون قراءات كافية. الـ break-even بيحصل بعد قراءة واحدة فقط في نفس النافذة، فلو مش متأكد من التكرار اعمل قياس قبل التفعيل.
• محتوى ديناميكي بالكامل: لو الـ system بيتغيّر كل request (مثلاً context محسوب per-user ومش بيتكرّر بين مستخدمين)، مفيش جزء ثابت يستحق التخزين أصلًا.
• تجارب A/B على system prompts متعددة: كل variant بيفرض cache write مستقل. خلّي التفعيل بعد ما تثبّت النسخة النهائية.

المصادر

• Anthropic — Prompt Caching Documentation
• Anthropic — API Pricing
• Finout — Anthropic API Pricing 2026 Guide
• MindStudio — How Prompt Caching Affects Claude Limits

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

افتح أكبر system prompt شغّال عندك في الإنتاج دلوقتي. عدّ توكناته بـ client.messages.count_tokens أو tokenizer مباشر. لو الناتج فوق 1024 توكن، ضيف cache_control: { type: "ephemeral" } على آخر content block ثابت في الـ system. شغّل 5 طلبات متتالية على API الإنتاج، واطبع usage.cache_read_input_tokens بعد كل طلب. لو الرقم طلع فوق صفر من ثاني طلب، أنت كسبت 90% من تكلفة الـ system prompt — والباقي هندسة طبيعية فوق ده.