المستوى المطلوب: متوسط — تحتاج تعرف الفرق بين system prompt و user message وبتشتغل على Anthropic SDK أو REST API.

لو عندك Claude Agent بيقرا 50 صفحة PDF كـ context قبل كل سؤال جديد، كل request بيكلّفك حوالي 0.45 دولار. مع Prompt Caching الرقم بينزل لـ 0.045 دولار بـ 9 سطور تعديل بس. اللي هتشوفه هنا مش "تحسين بسيط"، ده تخفيض عشري في الفاتورة على الـ workloads اللي بتعيد نفس الـ prefix.

Prompt Caching: السلاح اللي بيخلّي Agents الإنتاج اقتصادية

المشكلة باختصار: ليه فاتورة Claude بتنفجر مع Agents

في كل request للـ API، الـ SDK بيبعت system prompt كبير + tool definitions + غالبًا documents مرجعية. Claude بيدفع compute لإعادة معالجة كل توكن من الصفر، حتى لو الـ context نفسه كان موجود في الطلب اللي قبله بثانيتين.

الحساب البسيط: 200 طلب يوميًا × 50,000 input tokens × 30 يوم × $3 لكل مليون توكن = $900 شهريًا. والمؤلم إن 95% من الـ context ده ثابت ومش بيتغيّر أصلاً.

مثال للمبتدئ: مكتبة جامعية وأمين الاستعارة

تخيّل مكتبة جامعية فيها أمين بيقدّم خدمة "تحليل بحثي". لما طالب يجيله بسؤال:

• بدون cache: الأمين يقرا الـ 300 صفحة من الكتاب المرجعي كل مرة قبل ما يجاوب — حتى لو نفس السؤال جاي من 5 طلاب متتاليين.
• مع cache: الأمين يقرا الكتاب مرة واحدة، يلخّص ملاحظاته على ورقة على المكتب، وبعدها كل سؤال جديد يستخدم نفس الورقة.

الفرق العملي: القراءة الأولى تاخد ساعة. الإجابة على كل سؤال جديد بعدها = 30 ثانية. ده بالظبط اللي بيحصل في GPU عند تفعيل Prompt Caching.

التعريف العلمي: ايه هو KV-Cache فعلاً

Prompt Caching عند Anthropic = إعادة استخدام attention KV-cache المحسوب من توكنات الـ prefix. الـ KV-cache هو زوج من المصفوفات (Key و Value) اللي transformer بيخزّنها لكل توكن خلال الـ forward pass، علشان لمّا التوكن التالي يحتاج يحسب attention مع التوكنز السابقة، النموذج يلوّد القيم من ذاكرة GPU بدل ما يعيد ضرب المصفوفات تاني.

اللي بيعمله Anthropic:

1. بيحدد أطول prefix مشترك بين الطلبات في window زمني.
2. بيخزّن الـ KV tensors في ذاكرة سريعة (HBM أو tier تاني حسب الحجم).
3. الطلب اللي يجي بعده على نفس الـ prefix بيتجاوز ال prefill phase ويبدأ من توكن أول جديد.

الأرقام الفنية المهمة (مايو 2026):

• الـ TTL الافتراضي = 5 دقايق من آخر استخدام (يتجدّد مع كل hit).
• 1h cache TTL متاح كـ beta بسعر كتابة أعلى.
• الحد الأدنى لحجم الـ prefix القابل للـ cache = 1024 توكن لـ Sonnet/Opus، و 2048 توكن لـ Haiku.
• سعر الكتابة (cache write) = +25% فوق سعر الـ input العادي.
• سعر القراءة (cache read) = 10% فقط من سعر الـ input، أي خصم 90% على الجزء المخبّأ.

كود Python شغّال (anthropic SDK 0.45+)

from anthropic import Anthropic

client = Anthropic()

LONG_DOC = open("research_paper.md").read()  # حجم تقديري 40,000 توكن

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": "أنت مساعد بحثي بيرد بالعربية الفصحى وبيقتبس من الوثيقة فقط."
        },
        {
            "type": "text",
            "text": LONG_DOC,
            "cache_control": {"type": "ephemeral"}
        }
    ],
    messages=[
        {"role": "user", "content": "لخّص النتائج الرئيسية في الفصل الرابع"}
    ]
)

print(response.usage)
# الطلب الأول:
#   cache_creation_input_tokens=40000, cache_read_input_tokens=0
# الطلب الثاني خلال 5 دقايق:
#   cache_creation_input_tokens=0,    cache_read_input_tokens=40000

الـ cache_control بيتحط على الـ block اللي عاوز تخبّيه. كل الـ content قبله بيدخل في نفس الـ prefix تلقائيًا. ممكن تحط حد أقصى 4 cache breakpoints في الـ request الواحد.

أرقام مقاسة على Workload إنتاج حقيقي

شركة دعم فني عربية بتشغّل Claude Agent على manual منتج طوله 38,000 توكن، بمعدل 1,200 طلب يوميًا:

• بدون caching: 1,200 × 38,000 × $3/M = $136.80/يوم ≈ $4,104/شهر.
• مع caching (نسبة hit مقاسة 95%):
  • 5% طلبات تكتب cache: 60 × 38,000 × $3.75/M = $8.55/يوم
  • 95% طلبات تقرا cache: 1,140 × 38,000 × $0.30/M = $13/يوم
  • الإجمالي: $21.55/يوم ≈ $647/شهر
• التوفير الشهري: $3,457 ≈ 84% خصم على الفاتورة.

الافتراض هنا إن الـ traffic موزّع نهارًا بشكل يخلّي الـ TTL 5 دقايق كافي. لو الـ traffic spiky جدًا الرقم بيختلف.

أربع Trade-offs لازم تعرفهم قبل ما تشغّل caching في الإنتاج

1. الـ TTL محدود وممكن يقتل توفيرك

الـ cache بيعيش 5 دقايق فقط بعد آخر hit. لو الـ traffic بتاعك متفرّق (مثلاً 10 طلبات في الساعة موزّعين عشوائيًا)، نسبة الـ hit ممكن تنزل تحت 50% والمكسب بيتآكل بسبب غرامة الكتابة 25%.

الحل: فعّل 1h cache بـ header anthropic-beta: extended-cache-ttl-2025-04-11. التكلفة: $6.00 لكل مليون توكن للكتابة بدل $3.75، لكن الـ break-even بيبقى 1.5 hit بدل 5 hits تقريبًا.

2. ترتيب الـ Blocks بيحدد فعالية الـ cache

أي تغيير في توكن واحد داخل الـ prefix المخبّأ = invalidation كاملة. لو حطّيت timestamp ديناميكي في system prompt قبل المستند الكبير، كل request هيخلق cache جديد ومش هتستفيد بحاجة.

القاعدة: الجزء الـ static الأطول يتحط الأول، والديناميكي بعده. tool definitions غالبًا تيجي قبل الـ knowledge base.

3. الحد الأدنى 1024 توكن صارم

أي prefix أقل من 1024 توكن مش هيتـ cache أصلاً، الـ API بيتجاهل الـ cache_control بدون error واضح. cache على system prompt صغير = صفر فايدة + احتمال bug صامت.

الحل: اطبع response.usage.cache_creation_input_tokens بعد أول طلب. لو الرقم = 0، يبقى الـ prefix أقصر من المسموح.

4. Cache Hit مش مضمون 100%

Anthropic بيوصف الميزة بـ "best effort". في حالات نادرة (load spikes، routing لـ shard مختلف، cluster maintenance) ممكن الطلب يعمل cache write بدلاً من read حتى لو الـ prefix مطابق.

الموقف الصحي: متبنيش SLA على الفاتورة بناءً على hit rate ≥ 99%. اعتبر 92-95% هو السقف الواقعي.

مثال متقدم: Caching مع Tool Use

TOOLS = [...]  # 12 tool definition بحجم إجمالي 8,000 توكن

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=2048,
    tools=TOOLS,
    system=[
        {"type": "text", "text": SYSTEM_PROMPT},
        {
            "type": "text",
            "text": KNOWLEDGE_BASE,  # 25,000 توكن
            "cache_control": {"type": "ephemeral"}
        }
    ],
    messages=conversation_history
)

ملحوظة دقيقة: الـ tool definitions بتدخل تلقائيًا ضمن الـ cacheable prefix طالما الـ cache_control اتحط على block بعدهم. ده بيخلّي Agents كتيرة تستفيد من cache على الـ tools نفسها بدون تعديل.

متى لا تستخدم هذه الطريقة

• System prompt قصير (<1024 توكن): الـ API هيتجاهل الـ flag.
• كل request بـ context مختلف 100%: هتدفع غرامة 25% كتابة بدون قراءة، الفاتورة بترتفع مش تنزل.
• Workload متفرّق جدًا (طلب كل ساعتين): TTL هيخلص قبل الـ hit التاني.
• Dev/Testing بأقل من 50 طلب يوميًا: التوفير سنتات قليلة، التعقيد في الـ debugging مش مستاهل.
• Streaming لطلب وحيد طويل: الـ caching بيفيد بين الطلبات، مش داخل نفس الطلب.

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

افتح dashboard الـ usage في Anthropic console، رتّب الـ Agents بحجم الفاتورة، وخد أول واحد. لو الـ system prompt + tool defs أكبر من 5,000 توكن وبتتكرر في ≥ 30% من الطلبات، ضيف cache_control على الـ block الأخير الثابت في الـ system array. شغّل لمدة 24 ساعة، وراقب cache_read_input_tokens في كل response. لو الـ hit rate نزل تحت 70%، فكّر في 1h cache TTL أو راجع ترتيب الـ blocks. لو فوق 90%، أنت كده خفّضت الفاتورة 80% على الأقل وتقدر تشتغل على الـ Agent اللي بعده.

المصادر

• Anthropic — Prompt Caching Documentation: docs.anthropic.com
• Anthropic — API Pricing (May 2026): anthropic.com/pricing
• Pope et al. 2022 — "Efficiently Scaling Transformer Inference" (KV-cache foundations), arXiv:2211.05102
• Kwon et al. 2023 — "Efficient Memory Management for Large Language Model Serving with PagedAttention" (vLLM paper), SOSP 2023
• Anthropic Engineering Blog — Extended Cache TTL Announcement (April 2025)