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

تعتمد تكلفة التخزين المؤقت للمطالبات (Prompt Caching) على ما إذا كان طلبك الثاني يبدو تماماً مثل طلبك الأول، وليس على الخصم المعلن. في تقديراتنا لمطالبة نظام (system prompt) بحجم 20,000 token على نموذج claude-sonnet-5، تبلغ تكلفة 1,000 طلب حوالي 18.18 دولاراً بدون تخزين مؤقت، وحوالي 2.00 دولار عندما يصل كل طلب بعد الأول إلى ذاكرة التخزين المؤقت. وتكلف نفس المطالبة أكثر من التكلفة الأساسية بدون تخزين مؤقت إذا تغيرت البادئة في كل استدعاء. يستخدم هذا الدليل أسعار TokenLab المرصودة بتاريخ 2026-10-03 لتوضيح مكان هذا الفارق، ويحدد ما لم نتمكن من تأكيده في الوثائق.

أبرز النقاط

• في النماذج الخمسة التي فحصناها، تبلغ تكلفة قراءة ذاكرة التخزين المؤقت من 2% إلى 10% من سعر الإدخال العادي. اثنان من النماذج الخمسة لا يدرجان سعراً لكتابة ذاكرة التخزين المؤقت.
• حيثما يوجد سعر للكتابة، فإنه إما يساوي سعر الإدخال (deepseek-v4.1-flash) أو 1.25 ضعف سعر الإدخال (claude-sonnet-5، claude-sonnet-5-5).
• وفقاً لحساباتنا، فإن زيارة واحدة لذاكرة التخزين المؤقت لكل عملية كتابة تعوض علاوة الكتابة البالغة 1.25 ضعف. يفترض هذا أن إدخال ذاكرة التخزين المؤقت لا يزال نشطاً، علماً بأن عمر ذاكرة التخزين المؤقت غير موثق في الأدلة التي قرأناها.
• يقلل التخزين المؤقت من جانب الإدخال في الفاتورة فقط. أما tokens المخرجات فيتم تسعيرها كما في السابق.
• وثائق TokenLab API التي قرأناها لا تذكر حقلاً خاصاً بـ cached-token في usage. قم بتسجيل الكائن الخام (raw object) من اختبارك الخاص وقم بمطابقته مع Usage.

تكلفة التخزين المؤقت للمطالبات حسب النموذج: أسعار القراءة، الكتابة، والإدخال

لقد قرأنا API النموذج المباشر لكل نموذج أدناه بتاريخ 2026-10-03. تدرج جميع النماذج الخمسة prompt-cache ضمن قدراتها، وتم تحديث الأسعار آخر مرة في 2026-10-02T16:53:30.068Z. الأسعار بالدولار الأمريكي لكل 1 مليون token.

النموذج	الإدخال	قراءة ذاكرة التخزين المؤقت	كتابة ذاكرة التخزين المؤقت	القراءة كحصة من الإدخال	الكتابة مقابل الإدخال
claude-sonnet-5	0.90	0.09	1.125	10%	1.25x
claude-sonnet-5-5	0.60	0.06	0.75	10%	1.25x
gpt-5.5	1.50	0.15	غير مدرج	10%	غير مدرج
deepseek-v4.1-flash (خارج أوقات الذروة)	0.15	0.003	0.15	2%	1.0x
deepseek-v4.1-flash (أوقات الذروة)	0.30	0.006	0.30	2%	1.0x
gemini-3.8-flash	0.375	0.0375	غير مدرج	10%	غير مدرج

عمودا النسبة المئوية هما نتيجة قسمتنا للأسعار المدرجة.

المصادر، جميعها رُصدت بتاريخ 2026-10-03:

• claude-sonnet-5 (صفحة النموذج: /models/claude-5/claude-sonnet-5)
• claude-sonnet-5-5 (صفحة النموذج: /models/claude-5/claude-sonnet-5-5)
• gpt-5.5 (صفحة النموذج: /models/gpt-5-5/gpt-5.5)
• deepseek-v4.1-flash (صفحة النموذج: /models/deepseek-v4/deepseek-v4.1-flash)
• gemini-3.8-flash (صفحة النموذج: /models/gemini-3/gemini-3.8-flash)

هناك ثلاث تفاصيل مهمة عند قراءة هذا الجدول.

أولاً، يدرج كل من gpt-5.5 و gemini-3.8-flash سعراً لقراءة ذاكرة التخزين المؤقت ولا يدرجان سعراً للكتابة. لا يمكننا تحديد كيفية محاسبة البادئة لأول مرة في هذين النموذجين من هذه البيانات. الأدلة لا تقول إنها مجانية، ولا تقول إنها تُحاسب بسعر الإدخال. تحقق من Usage بعد الطلب الأول قبل بناء توقعات بناءً على أي من الافتراضين.

ثانياً، عندما قرأنا deepseek-v4.1-flash، وجدنا إدخالي سعر. يختلف إدخال off-peak (المحدد offPeak: true) وإدخال peak (offPeak: false) بمعامل اثنين في كل سطر. مدخرات ذاكرة التخزين المؤقت الخاصة بك لكل token هي نفس النسبة المئوية، لكن الدولارات المطلقة تتضاعف في أوقات الذروة.

ثالثاً، هذه أسعار TokenLab العامة. يقول دليل الفوترة (المرصود بتاريخ 2026-10-03) إن الطلب المكتمل يُحاسب مرة واحدة مقابل خيار التسليم الذي أنتجه. يتبع Official السعر العام لصانع النموذج، لذا تأكد من الخيار الذي خدم طلبك قبل المقارنة مع قائمة أسعار الصانع.

يُظهر مرجع Get a Model نموذج gpt-5.6-terra مع prompt-cache ضمن قدراته. استجابته النموذجية لا تحمل أسعاراً، لذا استبعدنا ذلك النموذج من الجدول. لم نتحقق من النماذج الأخرى في الكتالوج.

مثال عملي على تكلفة التخزين المؤقت للمطالبات: مطالبة نظام طويلة واحدة

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

• مطالبة نظام (system prompt) وكتلة أدوات بحجم 20,000 token، متطابقة في كل طلب.
• رسالة مستخدم بحجم 200 token تتغير في كل طلب.
• 1,000 طلب، مع بقاء ذاكرة التخزين المؤقت نشطة طوال فترة التشغيل، لذا هناك عملية كتابة واحدة و999 عملية قراءة.
• تم تجاهل tokens المخرجات، لأنها تكلف نفس الشيء مع أو بدون التخزين المؤقت.

claude-sonnet-5 بسعر 0.90 للإدخال، 0.09 للقراءة، و 1.125 للكتابة لكل 1 مليون token:

• بدون تخزين مؤقت: 1,000 × 20,200 = 20,200,000 token × 0.90 دولار/1 مليون = 18.18 دولاراً
• كتابة ذاكرة التخزين المؤقت: 20,000 × 1.125 دولار/1 مليون = 0.0225 دولار
• قراءات ذاكرة التخزين المؤقت: 999 × 20,000 = 19,980,000 token × 0.09 دولار/1 مليون = 1.7982 دولار
• اللواحق غير المخزنة مؤقتاً: 1,000 × 200 = 200,000 token × 0.90 دولار/1 مليون = 0.18 دولار
• مع التخزين المؤقت: 0.0225 + 1.7982 + 0.18 = حوالي 2.00 دولار، أي أقل بنسبة 89% تقريباً من الرقم بدون تخزين مؤقت.

الآن حالة الفشل، مع تغير البادئة قليلاً في كل استدعاء بحيث يدفع كل طلب تكلفة كتابة ولا يقرأ أبداً. يكلف ذلك 1,000 × 20,000 × 1.125 دولار/1 مليون = 22.50 دولاراً للبادئات، بالإضافة إلى نفس الـ 0.18 دولار للواحق. الإجمالي هو حوالي 22.68 دولاراً، وهو ما يزيد بمقدار 4.50 دولار (25%) عن الـ 18.18 دولاراً بدون تخزين مؤقت.

نقطة التعادل تتبع نفس الأسعار. لكل 1 مليون token بادئة، تكلف الكتابة 0.225 دولار أكثر من الإدخال العادي، وتوفر كل قراءة 0.81 دولار. زيارة واحدة تعوض الكتابة مع وجود فائض (0.225 ÷ 0.81 ≈ 0.28 قراءة لكل كتابة).

نفس السيناريو على النماذج الأخرى:

النموذج	بدون ذاكرة تخزين مؤقت	مع ذاكرة تخزين مؤقت (تقديري)	الافتراض للطلب الأول
claude-sonnet-5	18.18 دولاراً	2.00 دولار	سعر الكتابة المدرج
claude-sonnet-5-5	12.12 دولاراً	1.33 دولار	سعر الكتابة المدرج
deepseek-v4.1-flash خارج الذروة	3.03 دولار	0.09 دولار	سعر الكتابة المدرج
deepseek-v4.1-flash الذروة	6.06 دولار	0.19 دولار	سعر الكتابة المدرج
gpt-5.5	30.30 دولاراً	3.33 دولار	لا يوجد سعر كتابة مدرج؛ قمنا بحساب 20,000 token بسعر الإدخال
gemini-3.8-flash	7.58 دولار	0.83 دولار	لا يوجد سعر كتابة مدرج؛ قمنا بحساب 20,000 token بسعر الإدخال

بالنسبة لـ gpt-5.5، الحساب هو 20,000 × 1.50 دولار/1 مليون = 0.03 دولار، بالإضافة إلى 19,980,000 × 0.15 دولار/1 مليون = 2.997 دولار، بالإضافة إلى 200,000 × 1.50 دولار/1 مليون = 0.30 دولار. الصفان المحددان يعتمدان على افتراض لا تدعمه الأدلة، لذا تعامل معهما كتقديرات تقريبية.

جعل المطالبة قابلة للتخزين المؤقت: ما تؤكده الوثائق

تدعم الأدلة قائمة قصيرة من المتطلبات.

1. اختر نموذجاً يدرج prompt-cache. مصفوفة capabilities من Get a Model (المرصودة بتاريخ 2026-10-03) هي المعيار. النموذج الذي لا يمتلكها لا يمنحك أي أساس لتوقع خصم.
2. احتفظ بالمحتوى المشترك في وضع ثابت. في نقطة نهاية Messages، system هو حقل من المستوى الأعلى ويأخذ سلسلة نصية أو مصفوفة من كتل المحتوى. في Chat Completions، توضع تعليمات النظام في messages. في كلتا الحالتين، يجب أن تأتي المواد المكررة أولاً.
3. أرسل بايتات متطابقة حتى الحدود. هذه هي قاعدة البادئة الدقيقة من الإصدار الأصلي لهذه المقالة، وهي تطابق كيفية عمل أسعار الجدول. سعر القراءة ينطبق فقط على جزء المطالبة الذي تطابق.

Request A: [ System Prompt + Tool Definitions ] [ User Query A ]
           ▲───────────── CACHED PREFIX ────────▲ ▲── SUFFIX ──▲

Request B: [ System Prompt + Tool Definitions ] [ User Query B ]
           ▲─────────── CACHE HIT (READ) ───────▲ ▲── SUFFIX ──▲

ثلاث عادات تكسر إعادة الاستخدام في أغلب الأحيان:

• الطوابع الزمنية، معرفات المستخدم، أو معرفات الجلسة في أعلى مطالبة النظام.
• تعريفات الأدوات أو مفاتيح JSON التي يتم إعادة ترتيبها بين الطلبات.
• تغييرات المسافة البادئة أو الأسطر الجديدة في النص المشترك.

شكل طلب توثقه مرجع Create Message:

{
  "model": "claude-sonnet-5",
  "max_tokens": 512,
  "system": [
    {
      "type": "text",
      "text": "You are a support assistant. The following policy governs all responses: [Full Policy Text]"
    }
  ],
  "messages": [
    { "role": "user", "content": "What is the return period for damaged items?" }
  ]
}

مسودة سابقة لهذه المقالة وضعت علامة cache_control من نوع ephemeral على كتلة النظام تلك. مرجع Create Message الذي قرأناه بتاريخ 2026-10-03 لا يدرج ذلك الحقل، لذا أزلناه من العينة. وينطبق الشيء نفسه على الحد الأدنى لطول البادئة وعمر ذاكرة التخزين المؤقت. لم نجد رقماً لأي منهما في وثائق TokenLab التي قرأناها. قبل الاعتماد على علامة صريحة أو TTL، اختبر النموذج الذي اخترته وقارن أعداد tokens المخزنة مؤقتاً عبر استدعاءين متطابقين.

قراءة أسعار ذاكرة التخزين المؤقت وتأكيد tokens المخزنة مؤقتاً

لا تنسخ الجدول أعلاه إلى الكود. يقول دليل الفوترة إن عليك قراءة السعر الحالي عندما يحتاجه تطبيقك. مساران موثقان:

curl "https://api.tokenlab.sh/v1/models/claude-sonnet-5"
curl "https://api.tokenlab.sh/v1/pricing?provider=openai&tag=chat"

الأول يعيد قدرات النموذج الواحد، حدوده، وتسعيره. معرف نموذج غير معروف يعيد 404 model_not_found. الثاني هو نقطة نهاية عامة لا تحتاج إلى مفتاح API. تظهر استجابته النموذجية الموثقة input_per_1m_tokens و output_per_1m_tokens لـ gpt-4o ولا توجد حقول ذاكرة تخزين مؤقت. تاريخ updated_at في تلك العينة هو 2026-04-20، وهي بيانات عينة، وليست تسعيراً حالياً. بالنسبة لأسعار ذاكرة التخزين المؤقت، استخدمنا نقطة نهاية كل نموذج.

لتأكيد أن التخزين المؤقت قد نجح، كائنات usage الموثقة أقل تفصيلاً مما قد تأمل. تدرج Chat Completions prompt_tokens، completion_tokens، و total_tokens. تدرج Messages input_tokens و output_tokens. لا يذكر أي مرجع حقلاً خاصاً بـ cached-token. يقول دليل تكلفة وكيل البرمجة (المرصود بتاريخ 2026-10-03) إن عليك تأكيد استخدام tokens المخزنة مؤقتاً في الاستجابة أو في Usage، وتسجيل tokens الإدخال، المخرجات، والمخزنة مؤقتاً لكل مهمة.

اختبار نود تشغيله:

1. أرسل نفس طلب البادئة الطويلة مرتين، بفارق بضع ثوانٍ، مع تغيير رسالة المستخدم النهائية فقط.
2. سجل كائن usage الخام الكامل من كلتا الاستجابتين، بالإضافة إلى billing_transaction_id إذا وجد.
3. قارن رسوم الطلب الثاني في Usage مقابل الحسابات أعلاه. يجب أن تهبط زيارة ذاكرة التخزين المؤقت بالقرب من رقم "مع التخزين المؤقت"، وليس الرقم بدون تخزين مؤقت.
4. كرر الاختبار مع سطر أول معدل عمداً لرؤية تكلفة الفشل.

بالنسبة لـ Chat Completions المتدفقة (streaming)، اضبط stream_options.include_usage: true لتلقي الاستخدام في أجزاء التدفق. يمكن أن يغيب رأس الفوترة عن التدفقات، لذا استخدم Usage للرسوم النهائية. يصف دليل استكشاف الأخطاء وإصلاحها أيضاً GET /v1/management/api-keys/{keyId}/usage، الذي يقوم بالتصفية حسب model، startDate، و endDate للمطابقة من جانب الخادم.

متى لا تكون تكلفة التخزين المؤقت للمطالبات مجدية؟

التخزين المؤقت هو رهان على حركة المرور المتكررة. يخسر في هذه الحالات:

• البادئة لا تتكرر أبداً. مستند بحجم 20,000 token لمرة واحدة يدفع أي علاوة كتابة ولا يكسب شيئاً في المقابل.
• الطلبات تصل ببطء شديد. إذا تجاوزت الفجوة بين الطلبات المتطابقة عمر ذاكرة التخزين المؤقت، فإن كل استدعاء هو عملية كتابة جديدة. لم نجد ذلك العمر في الأدلة، لذا قس فجوتك الخاصة مقابل ما تذكره صفحة النموذج.
• تتغير البادئة قبل الحدود. الإنفاق الزائد بنسبة 25% في حالة الفشل أعلاه يأتي من هذا النمط بالضبط.
• البادئة صغيرة. تتناسب المدخرات مع tokens البادئة. بضع مئات من tokens توفر كسوراً من السنت لكل طلب، والحد الأدنى للحجم القابل للتخزين المؤقت ليس في الأدلة.
• المخرجات تهيمن على الفاتورة. التخزين المؤقت يقلل الإدخال فقط. إذا كانت الإجابات طويلة، فإن سطر ذاكرة التخزين المؤقت يمثل حصة صغيرة من الإجمالي.
• النموذج لا يدرج سعر ذاكرة تخزين مؤقت. يقول دليل الفوترة إن الشرطة في عمود سعر TokenLab تعني عدم وجود عرض موثق، وليس مجانية. تحقق من تفاصيل تسعير النموذج قبل الاعتماد على أي خصم.

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

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

أسئلة شائعة

هل تجعل زيارة ذاكرة التخزين المؤقت الطلب أرخص دائماً؟

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

هل سعر كتابة ذاكرة التخزين المؤقت المفقود يعني أنه مجاني؟

لا. بالنسبة لـ gpt-5.5 و gemini-3.8-flash، أدرج API المباشر سعر قراءة ذاكرة التخزين المؤقت ولا يوجد سعر كتابة بتاريخ 2026-10-03. قم بتشغيل طلب أول واحد واقرأ الرسوم في Usage بدلاً من افتراض الصفر أو سعر الإدخال.

أين تذهب قيم المستخدم الواحد في مطالبة قابلة للتخزين المؤقت؟

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

لماذا قد لا يظهر طلب متكرر أي tokens مخزنة مؤقتاً؟

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

قارن أسعار ذاكرة التخزين المؤقت المباشرة قبل الالتزام بنموذج على صفحة نماذج TokenLab.