Prompt Caching مع Claude: إزاي توفر 90% من تكلفة الـ AI بسطر واحد

لو بتبني تطبيق على Claude API وفاتورتك الشهرية بقت توجع، Prompt Caching ممكن يقلّلها لحد 90% ويخفّض زمن أول توكن بـ 50–80%، وكل ده بإضافة سطر واحد في الـ request بتاعك. المقال ده هيوريك إزاي تعمل ده بالظبط، إمتى يشتغل، وإمتى ميشتغلش.

المشكلة باختصار

لما بتبعت برومبت طويل (تعليمات نظام + وثائق مرجعية + سجل المحادثة) لـ Claude في كل request، أنت بتدفع تكلفة معالجة كاملة كل مرة. لو نفس الـ context بيتكرر في 1000 طلب يوميًا، أنت بالظبط بتدفع 1000 ضعف من غير أي قيمة مضافة. ده بيحصل بشكل صامت في معظم تطبيقات الـ chatbots و agents اللي شفتها.

الفكرة بمثال للمبتدئ جدًا

تخيّل إنك بتروح لنفس المطعم كل يوم. الويتر بيسألك في كل زيارة: "حضرتك مين؟ بتفضل المنيو إيه؟ عندك حساسية من إيه؟ بتدفع كاش ولا فيزا؟". الكلام ده بياخد منه 5 دقايق قبل ما يبدأ ياخد طلبك الفعلي.

Prompt Caching هو إن الويتر يعمل لك "كرت زبون دائم" ويحفظ كل البيانات دي. تاني مرة تدخل، يفتح الكرت في ثانية واحدة، وأنت بس بتقول "نفس طلب امبارح + كمان سلطة". فرّقت في الوقت؟ ده بالظبط اللي بيحصل في الـ API بتاع Claude.

التعريف العلمي الدقيق

Prompt Caching تقنية بتسمح لطبقة الـ inference إنها تخزّن نتيجة معالجة جزء من البرومبت، وبالتحديد الـ KV cache الخاص بطبقات الـ attention في الترانسفورمر. في الطلبات اللاحقة اللي بتشترك في نفس الـ prefix بايت-بايت، الموديل بيتجاوز خطوة إعادة المعالجة ويستخدم الحالة المخزّنة مباشرةً.

اقتصاديات الكاش بسيطة: الكتابة الأولى في الكاش بتكلّف 25% أكتر من الـ input العادي. القراءة من الكاش بتكلّف 10% فقط من تكلفة الـ input. مدة الصلاحية الافتراضية 5 دقايق من آخر استخدام (ephemeral)، وفيه خيار ساعة كاملة في خطط معيّنة.

إزاي تشغّلها فعليًا — كود يشتغل دلوقتي

ركّز في 3 خطوات: حدّد الجزء الثابت، حطّه في البداية، وعلّم عليه cache_control. الجزء المتغيّر (سؤال المستخدم) يتحط بعدين بدون أي علامة.

1. قسّم البرومبت لـ "ثابت طويل" (system + docs + tools) و"متغيّر قصير" (سؤال المستخدم).
2. الجزء الثابت لازم يكون ≥ 1024 توكن لـ Sonnet/Opus، أو ≥ 2048 توكن لـ Haiku. أقل من كده الكاش مش هيتفعّل أصلًا.
3. تأكد إن الـ prefix ما بيتغيّرش ولا بحرف واحد بين الطلبات (حتى الـ timestamp في system prompt هيلغي الكاش).

import anthropic

client = anthropic.Anthropic()

LONG_LEGAL_DOCS = open("contracts.txt").read()  # حوالي 50K توكن

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

print(response.usage)
# أول طلب:
#   cache_creation_input_tokens: 50000
#   cache_read_input_tokens: 0
# الطلبات اللي بعدها (خلال 5 دقايق):
#   cache_creation_input_tokens: 0
#   cache_read_input_tokens: 50000

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

سيناريو واقعي: تطبيق دعم فني داخلي في شركة، بيستخدم Claude Sonnet مع 30 ألف توكن وثائق منتج ثابتة، ومعدّل الاستخدام 1000 طلب يوميًا (طلب كل دقيقة ونص تقريبًا، يعني الكاش هيفضل حي).

• بدون caching: 30,000 × 1000 = 30 مليون توكن input يوميًا. بسعر $3 لكل مليون = $90/يوم.
• مع caching: 30,000 × 1.25 (الكتابة الأولى) + 30,000 × 999 × 0.10 = 37.5 ألف + 3 مليون توكن مكافئ. التكلفة ≈ $9/يوم.
• الوفر الصافي: $81/يوم = $2,430/شهر = حوالي $29,500/سنة من سطر واحد.

الـ trade-offs اللي لازم تعرفها

المكسب: تكلفة input أقل بـ 90% على الـ prefix المكرّر، وزمن أول توكن (TTFT) أسرع بـ 50–80% للبرومبتات الطويلة لأن الموديل مش بيعيد حساب الـ attention على الجزء المخزّن.

التكلفة: أول طلب على الكاش بيكون أغلى بـ 25%. أي تعديل ولو حرف واحد في الـ prefix بيلغي الكاش بالكامل ويعيد الفوترة من الصفر. الكاش بيموت بعد 5 دقايق من عدم الاستخدام.

الافتراض الأساسي: الكلام ده مبني على إن عندك prefix ثابت ≥ 1024 توكن، ومعدّل طلبات أعلى من واحد كل 5 دقايق. لو الاتنين دول مش متحققين، وفّر مجهودك.

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

متستخدمهاش لو الـ system prompt قصير (أقل من 1024 توكن). متستخدمهاش لو كل request في تطبيقك بيجي بـ context مختلف تمامًا (مثلاً بحث في وثائق مختلفة كل مرة). متستخدمهاش لو معدّل الطلبات بطيء (طلب كل ساعة مثلاً) — الكاش هيموت قبل ما تستخدمه ثاني وهتدفع زيادة 25% على الفاضي. وأخيرًا، متحطّش حاجات متغيّرة (تاريخ اليوم، اسم المستخدم) جوا الـ cached prefix لأنها هتلغي الكاش في كل طلب.

المصادر

• وثائق Anthropic الرسمية لـ Prompt Caching: docs.anthropic.com/en/docs/build-with-claude/prompt-caching
• صفحة الأسعار الرسمية على anthropic.com/pricing (أسعار 2026 للـ Claude Sonnet 4.6 و Opus 4.7).
• Anthropic Engineering Blog — "Introducing Extended Cache TTL" (2025).
• OpenAI Cookbook — مقارنة Prompt Caching بين الموفّرين (2025).

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

افتح أكبر endpoint عندك على Claude API. احسب طول الـ system prompt بالتوكنات (استخدم client.messages.count_tokens). لو الطول ≥ 1024 توكن وبيتكرر في أكتر من طلب كل 5 دقايق، ضيف cache_control النهارده وراقب cache_read_input_tokens في أول 24 ساعة. لو الوفر طلع أقل من 50%، الـ prefix بيتغيّر بين الطلبات بدون ما تحس — دوّر على الـ timestamps أو الـ user IDs اللي مدسوسة جواه.