Prompt Caching في Claude للمتوسط: نزّل فاتورة الـ system prompt 90% بسطر JSON واحد

import anthropic

client = anthropic.Anthropic()

SYSTEM_PROMPT = """
أنت مساعد دعم فني لشركة برمجيات.
[... 4500 توكن من سياسات الشركة، few-shot examples، إرشادات صياغة ثابتة ...]
"""

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": SYSTEM_PROMPT,
            "cache_control": {"type": "ephemeral"}
        }
    ],
    messages=[{"role": "user", "content": "ازاي أعمل refund لاشتراك سنوي؟"}]
)

print(response.usage)

أول استدعاء، الـ usage بيرجّع:

الاستدعاء التاني (في نفس الـ 5 دقايق وبنفس الـ system بالحرف):

السطر الوحيد اللي اضافيناه هو "cache_control": {"type": "ephemeral"}. مفيش API منفصلة، مفيش endpoint جديد، مفيش management للـ cache من طرفك. Anthropic بتتولى التخزين والتعرّف على الـ hits.

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

الافتراض: شات بوت دعم بـ system prompt 5000 توكن، 2000 request يومياً، Claude Sonnet 4.6، متوسط الإجابة 200 توكن إخراج (للتبسيط هنركّز على فاتورة الإدخال).

أسعار Claude Sonnet 4.6 المرجعية (يرجى التأكد من الصفحة الرسمية لأن الأسعار قابلة للتعديل):

• Input عادي: $3 لكل مليون توكن.
• Cache write (5-min): $3.75 لكل مليون توكن — أي 25% زيادة عن العادي.
• Cache read: $0.30 لكل مليون توكن — أي 10% فقط من السعر العادي.

بدون cache: 5000 × 2000 = 10 مليون توكن إدخال يومياً × $3 = $30 يومياً.

مع cache (افتراض cache hit rate 95% لأن الـ system ثابت والـ traffic موزّع طول اليوم): 100 request منهم writes، 1900 reads.

• Writes: 5000 × 100 = 500K توكن × $3.75/M = $1.88
• Reads: 5000 × 1900 = 9.5M توكن × $0.30/M = $2.85
• المجموع: $4.73 يومياً

التوفير الفعلي: 84% على فاتورة الإدخال. شهرياً: من $900 لـ $142.

لزمن الاستجابة: حسب benchmarks Anthropic الرسمية، TTFT على prompts كبيرة بينزّل 80% تقريباً مع cache hit (من ~2.5 ثانية لـ ~0.5 ثانية على system بحجم 5K توكن).

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

أولاً، الـ writes بتكلّف 25% زيادة. لو الـ prompt بتاعك متغيّر في كل request (مثلاً فيه timestamp ديناميكي أو user_id مدمج في الـ system)، أنت بتدفع write زيادة وما بتستفدش بـ read واحد. لازم تضمن الـ prefix قبل الـ breakpoint ثابت بايت ببايت.

ثانياً، ترتيب البلوكات بيهم. الـ cache match تسلسلي من أول الـ prompt لحد الـ breakpoint. لو غيّرت توكن واحد في النص الثابت، الـ cache بطل وبتدفع write جديد. القاعدة العملية: حط كل المتغيرات في الـ user message أو في آخر system block بعد الـ breakpoint.

ثالثاً، الـ TTL 5 دقايق فقط افتراضياً. لو شات بوتك بياخد فترات هدوء طويلة (مثلاً مابين 3 الفجر و 7 الصبح)، الـ cache بيموت وأول request بعد الفترة دي بيدفع write جديد. الـ extended cache (1 ساعة) متاحة بسعر write مضاعف، فا فيها break-even calculation محتاج تعمله.

رابعاً، الـ caching معزول لكل organization و API key. مش هتشارك cache مع تطبيقات تانية حتى لو على نفس الـ Anthropic account.

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

الـ system prompt الكلي أقل من 1024 توكن (لـ Sonnet/Opus). الحد الأدنى مش هزل — تحت كده الـ API بترفض إنشاء breakpoint وبترجّع الـ request بدون cache. لو prompt صغير، الـ caching مش هيساعدك أصلاً.

الـ prompt بتاعك متفرد لكل user. مثلاً لو بتحقن history المستخدم أو preferences ديناميكية في أول الـ system، مفيش reuse ممكن. الحل: ابن الـ system من بلوكين — بلوك ثابت طويل مع cache_control، وبلوك متغير صغير من غيره.

traffic منخفض جداً. لو بتعمل أقل من 5 requests كل 5 دقايق على نفس الـ prompt، الـ writes بتكلفك زيادة من غير cache hits كافية تعوّض. اعمل الحسبة: لو الـ break-even أكبر من traffic بتاعك، شيل الـ caching.

تطوير وتجارب متغيّرة. لو لسه بتعدّل في الـ system prompt كل ساعة وانت بتـ iterate، كل تعديل بيبطل الـ cache. فعّل caching بعد ما تستقر على نسخة production.

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

افتح آخر استدعاء لـ Claude في الكود بتاعك دلوقتي. اعرف طول الـ system prompt بـ client.messages.count_tokens(). لو فوق 1024 توكن وبيتبعت نفسه أكتر من 5 مرات في الساعة، ضيف "cache_control": {"type": "ephemeral"} على آخر بلوك في الـ system، شغّل الكود مرتين متتاليتين، اطبع response.usage، وتأكد إن cache_read_input_tokens فيه قيمة في المرة التانية. لو فاتورة الشهر الجاي قلّت أقل من 50% عن الشهر اللي فات، انت طبّقتها صح.

المصادر

• Anthropic Docs — Prompt Caching
• Anthropic — Pricing for Claude Models
• Anthropic API Reference — Messages
• Anthropic Announcement — Prompt Caching Launch