مستوى المقال: مبتدئ — هذا الشرح موجّه للمطور اللي بدأ يستخدم Claude API ولاحظ إن الفاتورة بتكبر أسرع من المتوقّع. هتعرف ليه بتدفع زيادة، وإزاي تخفّض 90% من الجزء المتكرّر بإضافة حقل واحد في الـ request.

لو بتبعت نفس الـ system prompt الطويل (3,000 token مثلاً) مع كل استدعاء لـ Claude، انت بتدفع تمنه كامل في كل request. Prompt Caching بيخلّي Anthropic تحتفظ بالجزء المتكرّر على خوادمها لمدة 5 دقايق، وبيحاسبك على قراءته بـ 10% من سعره الأصلي فقط.

Prompt Caching: ليه فاتورة Claude بتكبر بدون سبب واضح

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

لو بنيت شات بوت بيستخدم Claude Sonnet 4.6، وحاطط في الـ system prompt تعليمات الـ persona + قواعد العمل + 5 أمثلة few-shot، الـ prompt ده ممكن يطلع 4,000 token. كل سؤال بيسأله المستخدم بيبعت الـ 4,000 token دول من الأول كأنهم جداد.

على Claude Sonnet 4.6 السعر $3 لكل مليون input token. لو الشات بوت بيرد على 10,000 سؤال شهرياً، الجزء المتكرّر لوحده بيكلّفك: 4,000 × 10,000 = 40 مليون token = $120 شهرياً على نفس الـ context اللي مش بيتغيّر. مع Prompt Caching، نفس الجزء بيكلّف $12 شهرياً فقط.

مثال أمين المخزن (شرح للمبتدئ)

تخيّل إنك ماسك مخزن قطع غيار، وكل يوم بيجي 50 ميكانيكي يسألوك "فين القطعة رقم XYZ؟". أمامك خياران:

1. الطريقة الغلط: كل ميكانيكي يطلب قطعة، انت تفتح الكتالوج من الصفحة 1 وتقرا الـ 800 صفحة لحد ما تلاقي القطعة. ده اللي بيحصل بدون Caching — Claude بيقرأ الـ system prompt كامل في كل مرة.
2. الطريقة الصح: أول مرة تقرا الكتالوج وتحفظ في دماغك فهرس سريع للقطع. كل سؤال بعد كده بترد في ثواني. ده الـ Prompt Caching — Claude بيحتفظ بفهرس داخلي للجزء المتكرّر لمدة 5 دقايق، وبيستخدمه على طول.

الفرق إن "حفظ الفهرس" مرة واحدة بيكلّف شوية زيادة (cache write)، بس استخدامه بعد كده بيكون رخيص جداً (cache read).

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

حسب توثيق Anthropic الرسمي، Prompt Caching بيشتغل بإنك بتحدّد جزء من الـ messages أو الـ system prompt بحقل cache_control: {"type": "ephemeral"}. أول استدعاء بيـ "كتب" المحتوى ده في cache على خوادم Anthropic بتكلفة +25% من السعر الأصلي للـ tokens. أي استدعاء بعد كده خلال 5 دقايق بيقرأ من الـ cache بتكلفة 10% من السعر الأصلي (يعني خصم 90% على cache hit).

الحد الأدنى لجزء قابل للـ caching على Sonnet 4.6 هو 1,024 token. أقل من كده، Anthropic بترفض الـ caching بصمت وبتحاسبك على الأسعار العادية.

الكود الفعلي (Python — anthropic SDK 0.45+)

from anthropic import Anthropic

client = Anthropic()

LONG_SYSTEM = open("system_prompt.md").read()  # 4,000 token مثلا

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": "ابحث عن القطعة رقم A-2218"}]
)

print(response.usage)
# cache_creation_input_tokens: 4012  (أول مرة فقط)
# cache_read_input_tokens: 0
# input_tokens: 14

في الاستدعاء التاني خلال 5 دقايق، الـ usage هيرجع:

# cache_creation_input_tokens: 0
# cache_read_input_tokens: 4012   ← دول بتكلفة 10% بس
# input_tokens: 11

الأرقام الحقيقية على Claude Sonnet 4.6

• Input عادي: $3.00 لكل مليون token
• Cache write (5-min): $3.75 لكل مليون token (+25%)
• Cache read: $0.30 لكل مليون token (−90%)
• نقطة التعادل: الـ cache بيوفّر فلوس من أول استخدامين فقط للجزء المخزّن.

سيناريو واقعي: شات بوت دعم فني بـ system prompt = 5,200 token، بيستقبل 8,000 سؤال شهرياً. بدون cache: $124.8. مع cache (افتراض 92% hit rate): $13.2. التوفير: $111.6 شهرياً — وده على شات بوت متوسط.

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

1. الـ TTL 5 دقايق فقط. لو الـ traffic ضعيف وبييجي طلب كل 10 دقايق، الـ cache بيموت قبل ما تستفيد منه. الحل: استخدم الـ 1-hour cache بتكلفة كتابة +100% بدل +25%.
2. أي حرف بيتغيّر في الـ cached block بيلغي الـ cache. لو بتحط timestamp في الـ system prompt، الـ cache مش هيشتغل أبداً. اعزل المتغيّرات في الـ messages.
3. الـ cache مش shared بين الـ API keys. لو فريقك بيستخدم keys مختلفة، كل واحد بيدفع cache write لوحده.
4. Anthropic مش بتضمن الـ cache hit. لو الخوادم تحت ضغط، ممكن الـ cache يتلغي قبل الـ 5 دقايق وانت تدفع cache write تاني.

متى Prompt Caching بيكون مضيعة وقت

ما تستخدموش لو:

• الـ system prompt أقل من 1,024 token (Anthropic بترفض الـ caching).
• الـ traffic أقل من استدعاءين كل 5 دقايق على نفس الـ context.
• كل request بيغيّر في الـ system prompt (مثلاً بيحط اسم المستخدم في أوله).
• بتستخدم نموذج Haiku 4.5 على prompts قصيرة — التوفير المطلق بيكون أقل من $5 شهرياً.

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

افتح آخر استدعاء بعتّه لـ Claude، احسب طول الـ system prompt بـ client.messages.count_tokens(). لو طلع أكثر من 1,024 token وبتبعته أكثر من مرتين كل 5 دقايق، ضيف "cache_control": {"type": "ephemeral"} عليه دلوقتي وراجع حقل cache_read_input_tokens في الـ response بعد ساعة. لو الرقم أكبر من صفر، انت دخلت دائرة التوفير الفعلي.

المصادر

• Anthropic Official Documentation — Prompt Caching (docs.anthropic.com/en/docs/build-with-claude/prompt-caching)
• Anthropic Pricing Page — Claude Sonnet 4.6 input/output rates (anthropic.com/pricing)
• Anthropic Engineering Blog — "Introducing Prompt Caching" (2024)
• anthropic-sdk-python ≥ 0.45 release notes — cache_control parameter