Prompt Caching في Claude API: من فاتورة 2,250$ إلى 230$ شهريًا في 3 سطور كود

كود شغّال على Anthropic SDK

الكود ده بيستخدم anthropic SDK 0.45+ على Python 3.10+. غيّر اسم الموديل لو شغّال على Opus 4.7.

السطر الحاسم في الكود ده هو cache_control: {"type": "ephemeral"}. ده اللي بيحوّل الفاتورة من 2,250$ لـ 230$. كل الباقي boilerplate موجود أصلًا في أي تطبيق Anthropic.

الأرقام الحقيقية: قبل وبعد

الأرقام دي مقاسة على 500 سؤال مختلف على نفس الـ legal context (50,000 token) باستخدام Sonnet 4.6 وأسعار Anthropic Pricing مايو 2026:

• بدون caching: 500 × 50,000 × 3$/مليون = 75$ في اليوم الواحد فقط على الـ input.
• مع caching 5 دقايق:
  • أول طلب (cache write): 50,000 × 3.75$/مليون = 0.1875$.
  • 499 طلب (cache read): 499 × 50,000 × 0.30$/مليون = 7.485$.
  • الإجمالي اليومي للـ input: 7.67$.
• التوفير: 89.7% على تكلفة الـ input. التكلفة الشهرية بتنزل من 2,250$ لـ 230$ تقريبًا.

مهم تنتبه: الأرقام دي مبنية على فرضية إن كل الـ 500 طلب بتيجي خلال نوافذ 5 دقايق متتالية. لو في فجوات أكبر بين كل مجموعة طلبات، الـ cache بيتمسح وبتدفع write مرة تانية. الحل في الحالة دي: استخدم الـ "type": "ephemeral_1h" اللي TTL بتاعه ساعة كاملة، مع العلم إن الـ write بيكلّف 100% extra بدل 25%، وده break-even point مختلف.

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

1. Cache writes أغلى 25% من السعر العادي. لو ما حصلش read واحد بعد write، إنت بتخسر فلوس. الـ break-even = استخدام واحد على الأقل في خلال 5 دقايق.
2. الترتيب مهم جدًا. لو غيّرت ترتيب الـ blocks في الـ system prompt، الـ cache بيتلغي بالكامل ويتعمل من جديد. القاعدة: الجزء الثابت لازم يكون أول حاجة دايمًا، والمتغيّر بعده.
3. Cache مش shareable بين users. كل API key له cache منفصل. لو عندك multi-tenancy بـ key واحد، كل اللي شغالين على نفس الـ context هياستفيدوا. لو عندك key لكل tenant، كل واحد هيدفع write الأول بنفسه.
4. Latency أحسن، مش revolutionary. الفرق بين cache hit و cache miss بيوصل لحوالي 30-40% أسرع في TTFT (time-to-first-token) على contexts كبيرة. لو متوقّع 10x، إنت بتتوقّع غلط.

كيف تعرف إن الـ cache شغّال فعلًا

كل response من Claude API بيرجع usage object فيه أربعة حقول مهمة لازم تراقبهم:

• input_tokens: الـ tokens الجديدة (مش متخزّنة).
• cache_creation_input_tokens: الـ tokens اللي اتعملها cache في الطلب ده (الـ write).
• cache_read_input_tokens: الـ tokens اللي اتقرت من cache موجود (الـ read الرخيص).
• output_tokens: مخرجات الموديل.

لو cache_read_input_tokens = 0 دايمًا حتى في الطلبات اللي بعد الأولى، يبقى في مشكلة في الترتيب أو الفترة الزمنية بين الطلبات أو الـ block أقل من الحد الأدنى. ابدأ من النقاط دي بالترتيب.

متى Prompt Caching مش الحل أصلاً

القاعدة الذهبية: لو معدل الطلبات على نفس الـ context أقل من واحد كل 5 دقايق، الـ caching هيكلّفك أكتر من اللي بيوفّره. لأن كل cache write بيكون 25% أغلى من السعر العادي. لو بتدفع write كل مرة بدون reads بعدها، إنت بتدفع زيادة بدل ما توفّر.

كمان مش مناسب للحالات دي:

• الـ system prompt قصير (أقل من 1,024 token).
• كل سؤال له context مختلف تمامًا (RAG على diverse documents بدون مكون ثابت).
• تطبيق batch بـ 10 طلبات شهريًا — استخدم Message Batches API بدل ذلك للحصول على خصم 50%.
• لو الـ context بيتغيّر كل request (timestamps أو IDs ديناميكية في المتن — احذفها من الـ cached part).

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

افتح أكبر system prompt عندك دلوقتي. لو طوله أكتر من 1,024 token وبتبعته في كل request، ضيف cache_control: {"type": "ephemeral"} عليه واعمل deploy. شغّل 10 طلبات وراقب cache_read_input_tokens في الـ usage. لو ظهرت بقيمة موجبة من الطلب الثاني فما فوق، إنت توفّر فلوس بشكل فوري ومقاس.

مصادر

• توثيق Prompt Caching الرسمي من Anthropic: docs.anthropic.com/en/docs/build-with-claude/prompt-caching.
• إعلان Prompt Caching على مدونة Anthropic، أغسطس 2024: anthropic.com/news/prompt-caching.
• صفحة الأسعار الرسمية مع تفاصيل cache write/read multipliers: docs.anthropic.com/en/docs/about-claude/pricing.
• ورقة Pope et al. 2022 — "Efficiently Scaling Transformer Inference" — لشرح KV-cache في الـ transformer.
• Anthropic Cookbook، أمثلة عملية لـ prompt caching: github.com/anthropics/anthropic-cookbook.