Prompt Caching للمبتدئ: وفّر 90% من فاتورة Claude API بسطر واحد

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 هيرجع:

الأرقام الحقيقية على 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