متى يحقق تخزين مطالبات Claude التعادل؟

تكلفة التخزين المؤقت للمطالبات قبل أن يحقق وفراً

يتيح تخزين المطالبات مؤقتاً لـ Claude إعادة استخدام بداية مطالبتك بدلاً من قراءتها في كل استدعاء، ويعتمد القرار كله على معاملين يُطبَّقان على سعر الإدخال الأساسي للنموذج. اعتباراً من August 2026، تكلّف كتابة البيانات في ذاكرة التخزين المؤقت 1.25x من سعر الإدخال الأساسي لمدة 5 minutes، أو 2x لمدة 1 hour. وتكلّف قراءة البيانات المخزنة مؤقتاً 0.1x. تنطبق هذه المعاملات على جميع النماذج، لذلك لا تتغير نقطة التعادل أدناه عند تغير السعر لكل رمز.

المقايضة هي رسم إضافي الآن مقابل خصم لاحق. تدفع تكلفة إضافية مرة واحدة لتخزين بادئة. ثم تدفع كل مطالبة لاحقة تبدأ بالبايتات نفسها تماماً عُشر سعر الإدخال العادي لذلك الجزء. إذا لم تُستخدم البادئة مجدداً خلال مدة صلاحيتها، فستدفع تكلفة إضافية قدرها 25 percent من دون فائدة.

نقطة التعادل، في سطر جبري واحد

لنسمِّ B تكلفة إدخال البادئة الأساسية إذا أرسلتها دون تخزين مؤقت. من دون التخزين المؤقت، تكلّف N من الطلبات مبلغاً يساوي N مضروباً في B. مع ذاكرة التخزين المؤقت لمدة 5 دقائق، يكتب الطلب الأول البادئة بتكلفة 1.25B، وتقرأ الطلبات N ناقص 1 المتبقية البادئة بتكلفة 0.1B لكل طلب. بمساواة التكلفتين، نحصل على 0.9N = 1.15، ومنه N = 1.28. يصبح الطلب الثاني أرخص بالفعل من عدم استخدام التخزين المؤقت إطلاقاً.

كرّر الحساب نفسه مع كتابة 2x لذاكرة التخزين المؤقت لمدة ساعة واحدة، فتحصل على 0.9N = 1.9، ومنه N = 2.11. تحتاج ذاكرة التخزين المؤقت طويلة المدة إلى قراءتين قبل الوصول إلى نقطة التعادل، ولذلك لا تكون الخيار الافتراضي.

يعرض المخطط أدناه تكلفة ذلك لبادئة تتكون من 20,000 رمز مميز على Claude Opus 5، إذ يبلغ سعر الإدخال الأساسي $5 لكل مليون رمز مميز اعتباراً من August 2026. اضرب كل قيمة في 0.6 لنموذج سعره $3 لكل مليون. ولا يتغير شكل المنحنى.

[
  {
    "requests": 1,
    "uncached_usd": "0.10",
    "cached_5m_usd": "0.125",
    "cached_1h_usd": "0.20"
  },
  {
    "requests": 2,
    "uncached_usd": "0.20",
    "cached_5m_usd": "0.135",
    "cached_1h_usd": "0.21"
  },
  {
    "requests": 3,
    "uncached_usd": "0.30",
    "cached_5m_usd": "0.145",
    "cached_1h_usd": "0.22"
  },
  {
    "requests": 5,
    "uncached_usd": "0.50",
    "cached_5m_usd": "0.165",
    "cached_1h_usd": "0.24"
  },
  {
    "requests": 10,
    "uncached_usd": "1.00",
    "cached_5m_usd": "0.215",
    "cached_1h_usd": "0.29"
  },
  {
    "requests": 20,
    "uncached_usd": "2.00",
    "cached_5m_usd": "0.315",
    "cached_1h_usd": "0.39"
  }
]

تكلّف معالجة طلب واحد $0.10 دون تخزين مؤقت، و$0.125 مع التخزين المؤقت، ولذلك فإن تخزين مطالبة تُستخدم مرة واحدة مؤقتاً يمثل خسارة صافية. عند الطلب الثاني، تبلغ تكلفة ذاكرة التخزين المؤقت لمدة 5 دقائق $0.135 مقابل $0.20. وتظل ذاكرة التخزين المؤقت لمدة ساعة واحدة أعلى تكلفة في تلك المرحلة، إذ تبلغ $0.21 مقابل $0.20 نفسه، ولا تتجاوز تكلفة المعالجة دون تخزين مؤقت إلا عند الطلب الثالث: $0.22 مقابل $0.30. وعند 20 طلباً، يصبح الفرق $2.00 مقابل $0.315.

تؤدي إصابة ذاكرة التخزين المؤقت أيضاً إلى تحديث الإدخال، ولذلك يسمّي جدول الأسعار المنشور ذلك العمود «إصابات ذاكرة التخزين المؤقت وتحديثاتها». وبناءً على ذلك، يحافظ endpoint المشغول على إدخال مدته 5 دقائق إلى أجل غير محدد بأسعار القراءة، ولا تتحمل مدة الساعة الواحدة تكلفة الكتابة 2x إلا عندما تتخلل حركة المرور فواصل فعلية.

تكلفة انخفاض معدل الإصابة

تحدث حالات عدم إصابة فعلية في حركة الشبكة. يُحاسَب الطلب الذي لا يصيب ذاكرة التخزين المؤقت لكنه لا يزال يحمل نقطة توقف على أنه عملية كتابة، لذلك فإن الطريقة الدقيقة للنمذجة هي حساب التكلفة بوصفها دالة في معدل الإصابة. يوضّح المخطط أدناه ذلك لـ1,000 طلب، يحمل كل منها البادئة نفسها المكوّنة من 20,000 رمز.

[
  {
    "hit_rate_percent": 0,
    "cost_5m_usd": "125.00",
    "cost_1h_usd": "200.00",
    "uncached_usd": "100.00"
  },
  {
    "hit_rate_percent": 25,
    "cost_5m_usd": "96.25",
    "cost_1h_usd": "152.50",
    "uncached_usd": "100.00"
  },
  {
    "hit_rate_percent": 50,
    "cost_5m_usd": "67.50",
    "cost_1h_usd": "105.00",
    "uncached_usd": "100.00"
  },
  {
    "hit_rate_percent": 75,
    "cost_5m_usd": "38.75",
    "cost_1h_usd": "57.50",
    "uncached_usd": "100.00"
  },
  {
    "hit_rate_percent": 90,
    "cost_5m_usd": "21.50",
    "cost_1h_usd": "29.00",
    "uncached_usd": "100.00"
  },
  {
    "hit_rate_percent": 95,
    "cost_5m_usd": "15.75",
    "cost_1h_usd": "19.50",
    "uncached_usd": "100.00"
  },
  {
    "hit_rate_percent": 99,
    "cost_5m_usd": "11.15",
    "cost_1h_usd": "11.90",
    "uncached_usd": "100.00"
  }
]

عند معدل إصابة قدره 0 بالمئة، تدفع $125.00 بدلاً من $100.00، وتضاعف ذاكرة التخزين المؤقت لمدة 1 hour الفاتورة إلى $200.00. بحل المعادلة 1.25 ناقص 1.15h = 1، يبدأ التخزين المؤقت لمدة 5 minutes في توفير المال عند معدل إصابة يبلغ نحو 22 بالمئة، ولهذا يعرض معدل 25 بالمئة بالفعل $96.25. ويعطي الحساب نفسه عند مضاعفة الكتابة نسبة تقارب 53 بالمئة لذاكرة التخزين المؤقت لمدة 1 hour، ولذلك يظل معدل إصابة قدره 50 بالمئة يكلّف $105.00، أي أعلى من خط عدم استخدام التخزين المؤقت. عند 90 بالمئة، تصل القيمتان إلى $21.50 و$29.00. وعند 99 بالمئة، تصل ذاكرة التخزين المؤقت القصيرة إلى $11.15، وهي قريبة من الحد الأدنى الذي يعادل عُشر السعر من دون تخزين مؤقت.

معدل الإصابة هو القيمة التي يجب قياسها، لأنه المدخل الوحيد الذي يمكنك التحكم فيه بعد تثبيت حجم البادئة.

ما البوادئ التي تستحق نقطة تخزين مؤقت

قد يحمل الطلب ما يصل إلى أربع نقاط لتخزين البادئة مؤقتاً، لذا فالسؤال هو: ما الكتل التي تستحق تخصيص نقطة لها؟ المرشحات هي الكتل المتطابقة بايتاً عبر الطلبات، والكبيرة بما يكفي لإحداث فرق. يوضح المخطط أدناه تكلفة أربعة أشكال شائعة عبر 1,000 طلب، مع معدل إصابة يبلغ 90 بالمئة في ذاكرة مؤقتة مدتها 5 دقائق.

[
  {
    "label": "System prompt",
    "prefix_size_tokens": "2,000",
    "uncached_usd": "10.00",
    "cached_usd": "2.15",
    "saved_usd": "7.85"
  },
  {
    "label": "System plus tools",
    "prefix_size_tokens": "8,000",
    "uncached_usd": "40.00",
    "cached_usd": "8.60",
    "saved_usd": "31.40"
  },
  {
    "label": "Policy document",
    "prefix_size_tokens": "25,000",
    "uncached_usd": "125.00",
    "cached_usd": "26.88",
    "saved_usd": "98.12"
  },
  {
    "label": "Codebase context",
    "prefix_size_tokens": "120,000",
    "uncached_usd": "600.00",
    "cached_usd": "129.00",
    "saved_usd": "471.00"
  }
]

يوفّر موجّه نظام عارٍ بحجم 2,000 token مقدار $7.85 لكل 1,000 طلب، مقارنةً بتكلفة $10.00 من دون تخزين مؤقت. هذا مبلغ فعلي عند التعامل مع حجم كبير من الطلبات، لكنه ليس ما يجعل التخزين المؤقت مهماً. عند إضافة تعريفات الأدوات، يصبح الحجم 8,000 token، ويبلغ الوفر $31.40. أما مستند السياسات الذي حجمه 25,000 token، والذي تطرح كل الطلبات أسئلة عنه، فيوفّر $98.12. أما الصف الأخير فهو الذي يغيّر البنية: إذ تبلغ تكلفة سياق قاعدة الشيفرة أو نص المحادثة بحجم 120,000 token $600.00 من دون تخزين مؤقت، و$129.00 عند تخزينه مؤقتاً، أي بوفر قدره $471.00.

يتناسب الوفر مع حجم البادئة ومعدل الإصابة، ولا يتأثر بأي عامل آخر. وهذا يغيّر ما يستحق إدراجه في الموجّه من الأساس: ما التكلفة الفعلية لمليون token من Claude ينخفض إلى عُشر السعر المعلن لأي محتوى ترسله أكثر من مرة.

كيف تبدو التكلفة في فاتورة شهرية

يعرض المخطط أدناه بادئة الرموز 8,000 من القسم السابق، مع موجه نظام وتعريفات الأدوات، بافتراض معدل إصابة قدره 90 بالمئة، ثم يوسّعها لتشمل أحجام الطلبات الشهرية.

[
  {
    "label": "10k requests",
    "uncached_usd": "400.00",
    "cached_usd": "86.00",
    "saved_usd": "314.00"
  },
  {
    "label": "100k requests",
    "uncached_usd": "4,000.00",
    "cached_usd": "860.00",
    "saved_usd": "3,140.00"
  },
  {
    "label": "1M requests",
    "uncached_usd": "40,000.00",
    "cached_usd": "8,600.00",
    "saved_usd": "31,400.00"
  }
]

عند 10,000 طلب شهرياً، يبلغ التوفير $314.00، وهو الفرق بين $400.00 و$86.00. وعند 100,000 طلب، يبلغ التوفير $3,140.00. وعند مليون طلب، تبلغ تكلفة رموز الإدخال من دون التخزين المؤقت $40,000.00، ويلغي التخزين المؤقت منها $31,400.00. هذه الأرقام تخص رموز الإدخال فقط. تُسعَّر المخرجات بشكل منفصل، ولا يغيّر التخزين المؤقت تكلفتها. تذكّر ذلك قبل أن تعد أي شخص بخفض الفاتورة بنسبة 90 بالمئة. يعمل التخزين المؤقت إلى جانب الممارسات الأوسع الواردة في إبقاء فاتورة وكيل ذكاء اصطناعي تحت السيطرة على VPS.

كيفية إثبات أن التخزين المؤقت يعمل

لا تعتمد على التصميم وحده. اقرأ قسم الاستخدام في الاستجابة. يوضّح كل رد من Messages API عدد الرموز التي كتبها في التخزين المؤقت، وعدد الرموز التي قرأها منه، وعدد الرموز الجديدة التي كان عليه معالجتها.

from anthropic import Anthropic

client = Anthropic()

resp = client.messages.create(
    model="claude-opus-5",
    max_tokens=512,
    system=[
        {
            "type": "text",
            "text": POLICY_DOCUMENT,
            "cache_control": {"type": "ephemeral"},
        }
    ],
    messages=[{"role": "user", "content": question}],
)

u = resp.usage
print("write:", u.cache_creation_input_tokens)
print("read: ", u.cache_read_input_tokens)
print("fresh:", u.input_tokens)

شغّل الطلب مرتين باستخدام المستند نفسه وسؤال مختلف. يعرض الاستدعاء الأول قيمة غير صفرية لـ cache_creation_input_tokens وقيمة صفرية لـ cache_read_input_tokens. يعكس الاستدعاء الثاني ذلك لأن البادئة عُثر عليها في التخزين المؤقت. يحسب input_tokens الرموز الموجودة بعد آخر نقطة توقف فقط، لذلك تكون قيمته صغيرة في الاستدعاء الثاني السليم، وعادةً لا تتجاوز رسالة المستخدم الجديدة.

يمكنك إجراء الفحص نفسه من shell باستخدام نص طلب حفظته في request.json:

curl -s https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d @request.json | jq '.usage'

يعرض الاستدعاء الثاني السليم شيئاً قريباً من الآتي:

{
  "input_tokens": 42,
  "cache_creation_input_tokens": 0,
  "cache_read_input_tokens": 20143,
  "output_tokens": 187
}

يوضح سطر واحد الحالة الفعلية. إذا بقيت قيمة cache_read_input_tokens تساوي 0 في جميع الاستدعاءات، فأنت تدفع تكلفة الكتابة البالغة 1.25x في كل مرة، ولا تستفيد من التخزين المؤقت.

بالنسبة إلى مدة الصلاحية البالغة 1 ساعة، تتضمن نقطة التوقف مدة بقاء (TTL):

{
  "type": "text",
  "text": "your stable prefix",
  "cache_control": {"type": "ephemeral", "ttl": "1h"}
}

يتوفر أيضاً التخزين المؤقت التلقائي. أضف حقلاً واحداً باسم cache_control في المستوى الأعلى من الطلب، وبعد ذلك تدير API نقاط التوقف تلقائياً مع نمو المحادثة. يستهلك هذا الحقل واحدة من فتحات نقاط التوقف الأربع. ابدأ به. استخدم نقاط التوقف الصريحة عندما تحتاج إلى تحديد موضع الحد بدقة.

قاعدة الترتيب التي تقضي على معدلات الإصابة

تطابق ذاكرة التخزين المؤقت بادئةً بايتاً ببايت بدءاً من بداية الطلب، ويُجمَّع الطلب بترتيب ثابت: الأدوات، ثم النظام، ثم الرسائل. يؤدي أي تغيير على أي مستوى إلى إبطال ذلك المستوى وكل ما يليه. فإذا عدّلت وصف أداة واحدة، يُبطَل prompt النظام وسجل الرسائل بالكامل معها، حتى إنك لم تغيّرهما.

ينتج عن ذلك rule واحدة بلا استثناءات. يجب أن يأتي كل ما يتغير بين الاستدعاءات بعد كل ما لا يتغير.

المتسبب المعتاد هو الطابع الزمني. يضمن وجود سطر يقرأ Current time: 2026-08-03T14:07:11Z في أعلى prompt النظام معدل إصابة يبلغ 0 بالمئة، لأن hash البادئة يختلف في كل استدعاء، ولا يمكن لأي إدخال سابق أن يطابقه. انقله إلى رسالة المستخدم، في النهاية. ويؤدي معرّف الجلسة أو nonce الخاص بكل طلب إلى المشكلة نفسها، وله الحل نفسه. يجب أيضاً وضع المستندات المسترجعة التي تختلف من طلب إلى آخر بعد الكتلة المخزنة مؤقتاً، وإلا دفعت كل token ثابت خلف حدّ متحرك.

المتسبب الثاني هو وضع نقطة الفصل على الكتلة التي تتغير. تحدث عمليات الكتابة إلى ذاكرة التخزين المؤقت عند نقطة الفصل، لذلك إذا اختلفت تلك الكتلة في كل مرة، فلن يُخزَّن أي محتوى ثابت، ولن يعثر lookback إلا على إدخالات كتبتها الطلبات السابقة عند نقاط الفصل المتحركة الخاصة بها. ضع cache_control على آخر كتلة يكون محتواها متطابقاً بين الطلبات.

المتسبب الثالث هو تغيير parameter لم تعتبره جزءاً من محتوى prompt. لكل model مختلف ذاكرة تخزين مؤقت مختلفة. يؤدي تغيير اختيار الأداة إلى الإبطال بدءاً من مستوى النظام. ويؤدي إضافة أداة أو إزالتها إلى إبطال كل شيء.

الحد الأدنى للبادئة، وعدم التنفيذ الصامت

لا تُخزَّن البادئة الأقصر من الحد الأدنى للنموذج في ذاكرة التخزين المؤقت، ولا يُعلمك النظام بذلك. لا يظهر خطأ أو تحذير. ينجح الطلب، وتبقى العدّادتان عند 0. اعتباراً من August 2026، الحدود الدنيا المنشورة هي:

• 512 token على Claude Opus 5 وClaude Fable 5
• 1,024 token على Claude Sonnet 5 وClaude Opus 4.8
• 4,096 token على Claude Haiku 4.5

إذا كانت العدّادتان عند 0 في طلب تعتقد أنه مخزَّن مؤقتاً، فتحقق من طول البادئة قبل أي شيء آخر. وهذا يفسر أيضاً سبب عدم كون النموذج الأرخص هو الأرخص تلقائياً في أحمال العمل التي تستخدم التخزين المؤقت. يحتاج Haiku 4.5 إلى بادئة أطول بثماني مرات من Opus 5 قبل تفعيل التخزين المؤقت، ولذلك تُخزَّن مطالبة نظامية من 2,000 token على أحدهما، بينما يتجاهلها الآخر بصمت.

أين يخزّن Claude Code ذاكرة التخزين المؤقت لك، وأين لا يستطيع ذلك

يخزّن Claude Code البادئة الخاصة به. يوجد system prompt وتعريفات الأدوات في بداية كل طلب ولا تتغير مواضعها، لذلك تُكتب مرة واحدة ثم تُقرأ لبقية الجلسة. لهذا تكون تكلفة كل دور في الجلسة الطويلة أقل بكثير مما يوحي به حجم السياق، ويظهر ذلك في العدادات الموضحة في كيفية الإبلاغ عن استخدام الرموز في Claude Code.

لا يمكنه مساعدتك عند إجراء تعديل بالقرب من بداية السياق. فسجل المحادثة لا يقبل إلا الإضافة، ولذلك تمدّد الأدوار الجديدة العادية بادئة مخزّنة مؤقتاً بالفعل. يؤدي تعديل ملف قُرئ في وقت مبكر من الجلسة إلى تغيير المحتوى في منتصف هذه البادئة، ويجب عندئذ كتابة كل رمز يأتي بعد التغيير من جديد. وتؤدي فترة خمول طويلة إلى النتيجة نفسها، لأن الإدخال تنتهي صلاحيته، ويدفع الدور التالي تكلفة كتابة كاملة. لا يمثل أي من الأمرين خطأً. فكلاهما تطبيق مباشر لقاعدة البادئة.

إذا كنت تكتب client الخاص بك، فطبّق التخطيط منذ الطلب الأول بدلاً من تعديله لاحقاً: أنشئ الاستدعاء بالطريقة الموضحة في أول تطبيق Claude API على VPS، مع وضع الكتل الثابتة أولاً والمتغيرة أخيراً.

حالات الفشل وما ستراه

كل استدعاء هو عملية كتابة. تكون قيمة cache_creation_input_tokens غير صفرية في كل طلب، بينما تبقى cache_read_input_tokens عند 0. يتغير شيء ما عند نقطة التوقف أو قبلها بين الاستدعاءات. اطبع أول 200 حرف من البادئة التي جمّعتها في طلبين متتاليين، ثم قارن بينهما بصرياً.

العدّادان يساويان 0. البادئة أقصر من الحد الأدنى الذي يتطلبه النموذج، أو أن الحقل cache_control لم يصل إلى واجهة API. احسب رموز البادئة أولاً، ثم سجّل نص الطلب الذي أرسلته فعلياً.

تعمل القراءات ثم تتوقف. تظهر سلسلة من مرات الإصابة، ثم عملية كتابة، ثم تعود مرات الإصابة. كانت الفترة بين الطلبات أطول من مدة الصلاحية. اقبل عملية الكتابة، أو انتقل إلى مدة TTL البالغة 1 hour بعد التحقق من أن معدل الإصابة يتجاوز 53 percent.

ينخفض معدل الإصابة بعد النشر. جرى تعديل وصف أداة أو تغيير النموذج. يؤدي كلا الأمرين إلى إبطال البادئة بأكملها. توقّع جولة مكلفة واحدة من عمليات الكتابة بعد كل عملية نشر تؤثر في prompt.

ارتفعت الفاتورة بعد تمكين التخزين المؤقت. معدل الإصابة لديك أقل من نقطة التعادل. عند أقل من نحو 22 percent في التخزين المؤقت لمدة 5 minutes، يكون إرسال البادئة من دون تخزين مؤقت أقل تكلفة. وينطبق الأمر نفسه على التخزين المؤقت لمدة 1 hour عند أقل من نحو 53 percent.

FAQ

كم مرة يجب إعادة استخدام الطلب قبل أن يصبح التخزين المؤقت مجدياً؟

مرة واحدة، عند استخدام التخزين المؤقت لمدة 5 دقائق. تبلغ تكلفة الكتابة 1.25x من تكلفة الإدخال الأساسية، وتبلغ تكلفة القراءة 0.1x، لذلك تبلغ تكلفة N من الطلبات غير المخزنة مؤقتاً N، بينما تبلغ تكلفة N من الطلبات المخزنة مؤقتاً 1.25 زائد 0.1 مضروباً في N ناقص 1. يتساوى الرقمان عند N = 1.28، لذلك يكون الطلب الثاني مجدياً بالفعل. يكتب التخزين المؤقت لمدة 1 ساعة بتكلفة 2x، ويتساوى الرقمان عند N = 2.11، لذلك يحتاج إلى قراءتين.

لماذا تكون قيمة cache_read_input_tokens صفراً دائماً؟

تحقق أولاً من طول البادئة: إذا كان أقل من الحد الأدنى للنموذج، وهو 512 token في Claude Opus 5 و4,096 في Claude Haiku 4.5 اعتباراً من August 2026، فسيُتخطى التخزين المؤقت بصمت، ويظهر العدّادان بالقيمة 0. إذا كان طول البادئة كافياً، فابحث عن محتوى يتغير بين الاستدعاءات ويقع عند breakpoint أو قبله، مثل timestamp أو session identifier داخل system prompt. إذا كان العدّادان يعملان ثم توقفا، فالفاصل بين الطلبات تجاوز مدة بقاء التخزين المؤقت.

هل يغيّر التخزين المؤقت للطلبات إجابات Claude؟

لا. يخزن التخزين المؤقت الشكل المعالَج من token التي أرسلتها مسبقاً، ويرى النموذج الطلب نفسه في الحالتين. هذه ميزة للفوترة وتقليل زمن الاستجابة، وليست تغييراً في السلوك. لذلك يمكنك تفعيلها في طلب يعمل من دون إعادة تشغيل اختبارات التقييم.

هل ينبغي أن أدفع مقابل التخزين المؤقت لمدة 1 ساعة؟

فقط عندما تتضمن حركة الطلبات فواصل أطول من 5 دقائق، ويظل معدل الإصابات لديك أعلى من نحو 53 بالمئة. تكلفة الكتابة 2x، أي إنها تضاعف الجانب السلبي مقارنةً بتكلفة الكتابة 1.25x عند عدم حدوث إصابة. يُحدَّث الإدخال لمدة 5 دقائق عند كل إصابة، لذلك تحافظ حركة الطلبات المستقرة على بقائه بأسعار القراءة من دون دفع تكلفة مدة البقاء الأطول.