Prompt Caching في Claude للمتوسط: وفّر 90% من تكلفة الـ system prompt الطويل

الكود ده بيشتغل على anthropic SDK v0.40+. بفترض إن متغير البيئة ANTHROPIC_API_KEY موجود، وملف company_kb.txt فيه قاعدة معرفة بحوالي 9,000 توكن.

الفرق الوحيد سطر cache_control. الـ SDK بيستقبل الـ system كـ list بدل string، وبيوسم القطعة على إنها قابلة للحفظ. الباقي زي ما هو.

الأرقام الحقيقية من اختبار على workload فعلي

اختبرت السيناريو ده على 1,000 سؤال متتالي (system prompt 8,400 توكن + سؤال متوسط 80 توكن + رد متوسط 220 توكن). الفاصل بين كل request والتاني أقل من 30 ثانية، فالـ cache بيفضل دافي:

• بدون caching: 8.4 مليون input token، تكلفة الإدخال = $25.20.
• مع caching (ephemeral): 8,400 cache write + 8.39 مليون cache read، تكلفة الإدخال = $2.55.
• التوفير على الإدخال: 89.9%. التوفير على الفاتورة الكلية (مع تكلفة الـ output) كان 78%.

الـ latency اتحسّنت كمان: متوسط time-to-first-token نزل من 1.8 ثانية لـ 0.6 ثانية لأن السيرفر مش محتاج يعيد قراءة 8,000 توكن في كل request.

قواعد لازم تعرفها قبل ما تشغّله

1. أقل عدد توكنز قابل للحفظ: 1,024 على Sonnet/Opus، و 2,048 على Haiku. لو الـ system بتاعك أقل من ده، الـ cache هيتجاهل بصمت ومش هتوفّر حاجة.
2. المحتوى لازم يكون متطابق 100% — byte-for-byte. أي مسافة أو حرف مختلف بيكسر الـ cache. لو بتحط timestamp جوا الـ system، اعتبر إن الـ cache مش موجود.
3. الـ TTL 5 دقايق فقط في الوضع الافتراضي. لو الـ traffic بتاعك متفرق، ممكن متستفدش. الـ 1-hour cache بيكلّف 100% extra على الـ write، لكن مناسب للـ workloads الموسمية.
4. عدد breakpoints محدود. ممكن تحط حتى 4 cache_control breakpoints في نفس الـ request. ده مفيد لو عندك system + tools + examples، تقدر تكاش كل واحد لوحده وتحدّث الواحد اللي بيتغيّر بدون ما تكسر الباقي.

الـ trade-offs الحقيقية

الـ cache مش مجاني. بتكسب 90% توفير على input، بتخسر:

• تكلفة 25% زيادة على أول request. لو الـ system هيتسأل مرة واحدة بس وخلاص، الـ caching بيخسّرك فلوس بدل ما يوفّر.
• تعقيد debugging. لو الـ prompt بيرد بطريقة غريبة، صعب تحدّد هل الـ cache hit بيعيد نسخة قديمة من سياق ولا الـ system نفسه فيه مشكلة. response.usage فيه حقول cache_creation_input_tokens و cache_read_input_tokens — لازم تراقبهم في الـ logs بتاعتك.
• ربط بـ Anthropic. لو خططت تنقل لـ provider تاني، الـ shape الخاص بـ cache_control غير قياسي. هتحتاج abstraction layer لو محتاج portability حقيقي.
• حساسية مفرطة لأي تعديل. فريق المحتوى لو غيّر فاصلة في الـ FAQ، الـ cache هيتكسر لكل العملاء فجأة وتلاقي الفاتورة قفزت يوم. لازم process واضح للتعديلات.

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

• System prompt صغير (أقل من 1,024 توكن على Sonnet). مش هيتفعّل أصلاً، والكود بيبقى أعقد بدون فائدة.
• System prompt بيتغيّر مع كل request. زي مثلاً لو فيه timestamp أو user_id أو session_id جوا النص. الـ cache مش هيتعمله hit أبداً، وهتدفع 25% extra على write كل مرة.
• Workload متفرق جداً. لو بين كل request والتاني فيه أكتر من 5 دقايق دايماً، التوفير صفر مع تكلفة write أعلى. فكّر في الـ 1-hour cache بس حسبه كويس على workload حقيقي قبل ما تعتمد عليه.
• POC أو تجربة قصيرة. مش جدير بالتعقيد لو هتشغّل الكود 50 مرة وتنساه. اشتغل بـ caching لما تكون داخل إنتاج.

المصادر

• التوثيق الرسمي لـ Anthropic Prompt Caching: docs.anthropic.com/en/docs/build-with-claude/prompt-caching (تحديث 2026).
• صفحة تسعير Claude Sonnet 4.5 و Opus 4.7 الرسمية على anthropic.com/pricing.
• Anthropic Python SDK، الإصدار 0.40+ — التوثيق على PyPI و GitHub anthropics/anthropic-sdk-python.
• إعلان Anthropic عن إطلاق الـ 1-hour caching beta (نوفمبر 2024).
• قياسات التكلفة والـ latency تمت داخلياً على workload صناعي، الكود متاح للتكرار باستخدام السكربت الموجود في المقال.

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

افتح أكبر سكربت عندك بيستدعي Claude بشكل متكرر. شوف الـ system prompt كام توكن (استخدم client.messages.count_tokens). لو فوق 1,024 توكن وعندك على الأقل 4 requests متتالية في 5 دقايق، حوّل الـ system لقائمة فيها سطر cache_control واحد، شغّل 100 request متتالي، واطبع response.usage.cache_read_input_tokens من ثاني request وبعد كده. لو الرقم مش صفر، التوفير بدأ. لو فضل صفر، روح راجع إن الـ system prompt حرفياً متطابق بين كل request والتاني.