دليل تكلفة Prompt Caching: مرات نجاح التخزين المؤقت (Cache Hits)، والبادئات (Prefixes)، والإنفاق الفعلي على الـ API

تعتمد تكلفة التخزين المؤقت للمطالبات (Prompt Caching) على ثلاثة متغيرات: مقدار المطالبة (prompt) الذي يمثل بادئة قابلة لإعادة الاستخدام، ومدى تكرار تلك البادئة ضمن النافذة النشطة لذاكرة التخزين المؤقت، وكيفية تسعير مزود الخدمة لعمليات الكتابة في ذاكرة التخزين المؤقت مقابل زياراتها. إذا حصلت على هذه الأرقام الثلاثة بشكل صحيح، يمكن للتخزين المؤقت أن يخفض بشكل ملموس فاتورة الرموز (tokens) المدخلة في أعباء العمل المتكررة؛ أما إذا أخطأت فيها، فقد تدفع علاوة كتابة مقابل ذاكرة تخزين مؤقت لا يتم إعادة استخدامها أبداً.

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

أبرز النقاط

• تتكون تكلفة التخزين المؤقت للمطالبات من عنصرين: تكلفة الكتابة (تُفرض عادةً عند إنشاء إدخال جديد في ذاكرة التخزين المؤقت) وتكلفة الزيارة (تُفرض عادةً عند إعادة استخدام الطلب لهذا الإدخال). تصف وثائق Anthropic هذا التمييز بين الكتابة والزيارة بوضوح؛ يجب عليك تأكيد المضاعفات الحالية في صفحة الوثائق قبل نمذجة الإنفاق.
• تتطلب زيارات ذاكرة التخزين المؤقت تطابقاً دقيقاً أو شبه دقيق للبادئة حتى نقطة توقف محددة. إعادة ترتيب تعليمات النظام، أو تعريفات الأدوات، أو أمثلة few-shot قبل نقطة التوقف تلك تؤدي إلى إبطال ذاكرة التخزين المؤقت وتفرض إعادة كتابة.
• تنتهي صلاحية إدخالات ذاكرة التخزين المؤقت بعد فترة زمنية محددة من قبل المزود (time-to-live). إذا كان حجم طلباتك لبادئة معينة نادراً جداً بحيث لا يقع ضمن تلك النافذة، فسوف تدفع تكاليف كتابة متكررة بدلاً من تجميع وفورات الزيارات.
• تشير وثائق OpenRouter إلى أن سلوك التخزين المؤقت للمطالبات وتسعيره يختلفان باختلاف المزود الأساسي والنموذج، لذا فإن استراتيجية التخزين المؤقت التي توفر المال على خلفية (backend) واحدة لا تنتقل تلقائياً إلى أخرى. تحقق من الدعم لكل نموذج قبل توجيه حركة المرور بناءً على وفورات مفترضة.

ما الذي تدفع تكلفته فعلياً عند استخدام التخزين المؤقت للمطالبات

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

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

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

كيف تعمل زيارات ذاكرة التخزين المؤقت: البادئات، البادئات، ونقاط التوقف

تعتمد زيارات ذاكرة التخزين المؤقت على البادئة، وليس على المحتوى بمعناه الغامض. يجب أن يتطابق الجزء المخزن مؤقتاً من المطالبة مع الطلب الوارد رمزاً برمز حتى النقطة التي يتم فيها تعيين حدود ذاكرة التخزين المؤقت، والتي تسمى أحياناً نقطة التوقف (breakpoint). تصف وثائق Anthropic هذا كآلية صريحة حيث يحدد المطورون أي جزء من المطالبة مؤهل للتخزين المؤقت، وعادة ما يكون ذلك تعليمات النظام المستقرة، وتعريفات الأدوات، والمستندات المرجعية الطويلة التي لا تتغير بين المكالمات.

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

الحل مباشر: احتفظ بالمحتوى الثابت حقاً (تعريفات الأدوات، تعليمات أسلوب المؤسسة، المستندات المرجعية الكبيرة) في البادئة المخزنة مؤقتاً، وادفع بأي شيء خاص بالطلب إلى اللاحقة غير المخزنة مؤقتاً، وعادة ما تكون رسالة المستخدم.

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

نمذجة الإنفاق الفعلي على API: نهج عملي

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

{
  "model": "claude-sonnet-5",
  "system": [
    {
      "type": "text",
      "text": "You are a support agent. Full policy document follows...",
      "cache_control": { "type": "ephemeral" }
    }
  ],
  "messages": [
    { "role": "user", "content": "What is the refund window for order 48213?" }
  ]
}

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

لتقدير ما إذا كان هذا يستحق التنفيذ لخدمتك، اجمع أربعة أرقام من سجلاتك الخاصة:

1. حجم البادئة: عدد الرموز للمحتوى المستقر الذي تنوي تخزينه مؤقتاً (مطالبة النظام، مخطط الأداة، المستند المرجعي).
2. تكرار المكالمات ضمن نافذة TTL: عدد الطلبات التي تعيد استخدام تلك البادئة بالضبط داخل المدة النشطة لذاكرة التخزين المؤقت.
3. معدلات الكتابة والزيارة: مستمدة من وثائق المزود الحالية، وليس مفترضة من الذاكرة.
4. تباين اللاحقة: ما إذا كان الجزء غير المخزن مؤقتاً من مطالبتك صغيراً مقارنة بالجزء المخزن مؤقتاً، حيث تتناسب الوفورات مع مقدار المطالبة الإجمالية التي تقع خلف نقطة توقف ذاكرة التخزين المؤقت.

إذا كانت بادئتك كبيرة، وكان تكرار مكالماتك داخل نافذة TTL مرتفعاً، وكانت لاحقتك صغيرة، فمن المرجح أن يقلل التخزين المؤقت من الإنفاق. إذا كان أي من هذه الشروط الثلاثة ضعيفاً، فقم بإجراء مقارنة تكلفة جنباً إلى جنب قبل طرح التخزين المؤقت على نطاق واسع. يتناول دليل TokenLab حول خفض تكاليف AI API مجموعة أوسع من الروافع بخلاف التخزين المؤقت، بما في ذلك اختيار النموذج والتجميع، على الرابط /blog/cut-ai-api-costs-30-percent.

جدول القرار: متى يؤتي التخزين المؤقت للمطالبات ثماره

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

استخدم هذا الجدول كقائمة مراجعة أولية، وليس كإجابة نهائية. أكد TTL، وتسعير الكتابة/الزيارة، وآليات نقطة التوقف مقابل وثائق المزود للنموذج المحدد الذي تخطط لاستخدامه، حيث تتغير هذه التفاصيل وتختلف حسب عائلة النموذج.

اختلافات المزودين التي يجب عليك التحقق منها قبل الالتزام

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

إذا كانت بنيتك تستخدم توجيه النموذج للتحكم في التكلفة (على سبيل المثال، إرسال مهام التصنيف الروتينية إلى نموذج منخفض التكلفة مثل DeepSeek V4 Flash، أو GLM-5.2، أو Gemini 3.5 Flash مع حجز Claude Sonnet 5 أو GPT-5.5 لمهام التفكير الأكثر صعوبة)، فأنت بحاجة إلى التحقق من دعم التخزين المؤقت بشكل مستقل لكل نموذج في جدول التوجيه ذلك. استراتيجية التخزين المؤقت التي تم التحقق منها مقابل وثائق نموذج واحد ليست افتراضاً آمناً لنموذج آخر. تتبع صفحة تصنيفات TokenLab اختلافات مستوى النموذج التي يمكنك استخدامها كنقطة مرجعية أولية على الرابط /models/rankings، ويغطي تحليل معيار التوجيه على الرابط /blog/ai-model-routing-benchmark-cost-per-task كيفية تفاعل قرارات التوجيه مع تكلفة كل مهمة، والتي تتضاعف مع قرارات التخزين المؤقت بدلاً من استبدالها.

قيود هذا التحليل

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

الأسئلة الشائعة

هل يقلل التخزين المؤقت للمطالبات دائماً من إنفاق API؟ لا. إنه يقلل الإنفاق فقط عندما يتم إعادة استخدام بادئة مستقرة بشكل متكرر بما يكفي ضمن النافذة النشطة لذاكرة التخزين المؤقت لتعويض تكلفة الكتابة. غالباً ما تكلف المطالبات المتقطعة أو عالية التباين أكثر مع تمكين التخزين المؤقت مقارنة بعدم تمكينه.

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

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

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