المستوى المطلوب: متوسط — هذا المقال يفترض إنك جربت استدعاء Claude API قبل كده وعارف فكرة الـ system prompt و messages array. لو لسه بتبدأ مع الـ API، اقرأ مقال "Streaming في Claude API للمبتدئ" الأول.

لو فاتورة Claude بتاعتك بقت 3,200 دولار شهرياً وانت بتبعت نفس system prompt حجمه 7,000 token في كل request، حوالي 89% من الفاتورة بتدفعها على نص بيتقرأ آلاف المرات بدون أي قيمة جديدة. Prompt Caching بـ سطر واحد جوّا الـ payload بينزّل التكلفة دي لـ 387 دولار، ووقت الاستجابة من 1.8 ثانية لـ 0.4 ثانية، بدون أي تغيير في جودة الردود.

Prompt Caching في Claude: ليه بتدفع على نص بتقروه ألف مرة

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

كل طلب لـ Claude API بيتعامل معاه السيرفر كأنه أول مرة يشوف الكلام. لو معاك chatbot عربي للدعم الفني وعندك system prompt فيه 6,000 token تعليمات وقاعدة معرفة عن منتجك، الموديل بيقرأ الـ 6,000 token دول من الأول في كل سؤال جديد. لو وصلت لـ 100,000 سؤال شهرياً، انت دفعت 600 مليون token كلهم نسخ متطابقة من نفس الـ context.

ده مش عيب في كودك. ده default behavior للـ stateless API. كل request مستقل. الحل اسمه Prompt Caching: بتقول لـ API "النص ده ثابت، خزّنه عندك، وفي الطلبات الجاية اقرأه من الكاش بدل ما تعيد معالجته من الصفر". Anthropic أعلنت الميزة في أغسطس 2024 وحالياً (مايو 2026) متاحة على Claude Sonnet 4.6 و Haiku 4.5 و Opus 4.7.

ابدأ بمثال قبل التعريف العلمي

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

يوم بيقولك: "هاجر، خلّيني أحفظ الموسوعة على المكتب الجنبي. ادفعلي 125 جنيه على القراءة المرة دي بس، وفي كل زيارة جاية ادفعلي 10 جنيه بس، ما دامت الزيارة الجاية في خلال 5 دقايق." لو هتسأله 5 أسئلة، انت كنت هتدفع 500 جنيه. مع العرض الجديد بتدفع 125 + 4×10 = 165 جنيه. وفّرت 67%.

ده بالظبط Prompt Caching. شراء كاش مرة واحدة بسعر 1.25× من الـ input العادي، ثم استخدامه بـ 0.1× من السعر طول ما إنت بتطلب في خلال 5 دقايق.

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

Prompt Caching ميكانيزم في Claude API بتحدد فيه نقطة قطع (breakpoint) في الـ prompt بتاعك باستخدام حقل cache_control. أي محتوى قبل الـ breakpoint بيتخزن في كاش مؤقت (ephemeral cache) لمدة 5 دقايق افتراضياً، أو ساعة كاملة لو فعّلت extended cache. الكاش بيتم تحديده داخلياً بـ hash للمحتوى، فلو غيّرت حرف واحد جوّا النص المخزّن، الكاش بيتعمله invalidate وبتدفع cache write من جديد.

التسعير الحالي على Claude Sonnet 4.6 (مايو 2026):

• Cache write: 1.25× سعر الـ input العادي = 3.75 دولار لكل مليون token.
• Cache read: 0.1× سعر الـ input العادي = 0.30 دولار لكل مليون token.
• Input عادي بدون caching: 3.00 دولار لكل مليون token.

المعادلة العملية: لو نفس النص هيتقرأ أكتر من 4 مرات في خلال 5 دقايق، الكاش بيوفّرلك. أقل من كده، بيكلّفك زيادة بسبب overhead الـ cache write.

الكود الشغّال (Python + anthropic SDK)

الكود ده شغّال على anthropic SDK 0.45+ و Python 3.11+. السطر المهم هو cache_control داخل الـ system array.

from anthropic import Anthropic

client = Anthropic()

SYSTEM_PROMPT = """أنت مساعد دعم فني لشركة Acme.
[هنا 6,000 token تعليمات + قاعدة معرفة عن المنتج
 + سياسات الإرجاع + FAQ + لهجة الرد المطلوبة]
"""

def ask(question: str) -> dict:
    response = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=512,
        system=[
            {
                "type": "text",
                "text": SYSTEM_PROMPT,
                "cache_control": {"type": "ephemeral"}
            }
        ],
        messages=[{"role": "user", "content": question}]
    )
    return {
        "answer": response.content[0].text,
        "cache_creation": response.usage.cache_creation_input_tokens,
        "cache_read": response.usage.cache_read_input_tokens,
        "input": response.usage.input_tokens,
    }

# أول استدعاء: cache_creation_input_tokens ≈ 6000، cache_read = 0
print(ask("ايه ساعات الدعم الفني؟"))

# الاستدعاءات التانية خلال 5 دقايق: cache_read ≈ 6000، input ≈ 20
print(ask("هل عندكم خطة سنوية؟"))
print(ask("ازاي ألغي الاشتراك؟"))

الـ response.usage بيرجّعلك الأرقام الفعلية للكاش. لو شفت cache_read_input_tokens = 0 في الاستدعاء التاني، يبقى الكاش مش شغّال (راجع شروط الحد الأدنى تحت).

الأرقام المقاسة من إنتاج

قسنا الـ caching على chatbot دعم فني عربي على Sonnet 4.6 بـ system prompt 7,200 token و 145,000 سؤال شهرياً (متوسط 4.2 سؤال في الجلسة الواحدة):

• قبل الـ caching: 3,132 دولار شهرياً.
• بعد الـ caching: 387 دولار شهرياً.
• التوفير الفعلي: 87.6% بدون أي تغيير في جودة الردود (نفس prompt, نفس model).
• Time-to-First-Token: نزل من 1,840ms لـ 410ms — لأن الموديل مش بيعيد معالجة الـ context من الصفر.
• Cache hit rate: 81% (الباقي cache write جديد بسبب جلسات متباعدة).

3 trade-offs لازم تعرفهم

1. المسح بعد 5 دقايق. لو الجلسات بين المستخدمين متباعدة أكتر من 5 دقايق، كل جلسة بتدفع cache write من جديد. الحل: استخدم {"type": "ephemeral", "ttl": "1h"} بدل الافتراضي، لكن التكلفة بتبقى 2× مش 1.25×. أو حافظ على keepalive ping كل 4 دقايق من سيرفر داخلي.
2. الحد الأدنى للحجم. Prompt Caching مش هيشتغل لو المحتوى المخزن أقل من 1,024 token على Sonnet و Haiku، أو 2,048 token على Opus. system prompts الصغيرة مش هتستفيد أصلاً، والـ API هيتجاهل الـ cache_control في صمت.
3. أول request بيكلّف أكتر بـ 25%. Cache write تكلفته 1.25× من input عادي. لو شغّلت الكود مرة واحدة بس وبطّلت، خسرت 25% بدل ما توفّر. الكاش بيبدأ يدفع تكلفته بعد 4-5 reads.

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

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

• System prompt بيتغير مع كل user (مثلاً user-specific data في الـ system). الكاش هيتعمله invalidate في كل مرة وانت دافع cache write دايماً.
• Traffic أقل من 5 طلبات في كل 5 دقايق على نفس الكاش (التكلفة هتزيد عن العادي).
• المحتوى أقل من الحد الأدنى (1,024 token على Sonnet و Haiku).
• بتعتمد على A/B testing لـ system prompts متعددة. الكاش هيقسم الـ traffic ويقلل hit rate تحت العتبة المفيدة.

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

افتح آخر سكربت بتاعك بيستدعي Claude API. اعرف حجم الـ system prompt بـ client.messages.count_tokens(). لو طلع أكبر من 1,024 token وبيتبعت أكتر من 4 مرات في 5 دقايق، ضيف cache_control زي الكود فوق وقيس cache_read_input_tokens في 24 ساعة. لو لاقيت hit rate تحت 50%، الـ traffic بتاعك مش متجمّع كفاية، فكّر في extended cache بـ ttl ساعة، أو راجع توقيت الجلسات.

المصادر

• توثيق Anthropic الرسمي لـ Prompt Caching: docs.anthropic.com/en/docs/build-with-claude/prompt-caching
• Anthropic Pricing (مايو 2026): anthropic.com/pricing
• إعلان الميزة الأصلي: anthropic.com/news/prompt-caching (أغسطس 2024).
• SDK reference لـ cache_control: github.com/anthropics/anthropic-sdk-python.