ملاحظة المؤلف: عندما تنخفض نسبة إصابة التخزين المؤقت لموجهات Claude فجأة إلى 0، أو تبقى الفاتورة مرتفعة ولا تنخفض، يمكنك استخدام diagnostics في ثلاث خطوات لتحديد موضع تفرّع البادئة (prefix)، ثم الاستعانة بـ usage للحكم على ما إذا كان التخزين المؤقت قد أصاب فعلاً. توضح هذه المقالة أيضًا كيفية التحقق الذاتي عند المرور عبر خدمة وكيل APIYI. (إن كنت تواجه هذه المشكلة، يمكنك بعد قراءة المقال إرساله إلى الـ Agent الخاص بك ليبدأ التحقيق.)
عدم إصابة التخزين المؤقت ليس ضربًا من الغموض، فالـ API سيخبرك من أي مقطع تبدأ البادئة في التفرّع. كل ما عليك فعله هو تمرير id استجابة الجولة السابقة مرة أخرى، وسترى أول نقطة اختلاف: هل تقع في model أم system أم tools أم messages.
هذه ليست مقالة تشرح إطلاق ميزة جديدة. هذا المقال موجّه للمطورين الذين يستخدمون التخزين المؤقت لموجهات Claude بالفعل، لكن نسبة الإصابة لديهم انخفضت فجأة إلى الصفر أو بقيت فاتورتهم مرتفعة؛ وسنوضّح في كل خطوة من خطوات التشخيص ما ستراه بالضبط.
القيمة الأساسية: بعد قراءة المقال، ستتمكن من تحديد سبب تعطّل التخزين المؤقت خلال ثلاث طلبات فقط. وستفرّق أيضًا بين ما يخبرك به diagnostics وما يخبرك به usage، وتعرف أي حقلين تقارن بينهما عند استخدام خدمة وكيل.
النقاط الأساسية في تشخيص التخزين المؤقت Claude diagnostics
لنوضّح الأمر بجملة واحدة: تمرّر معرّف (id) استجابة الجولة السابقة، فتقارن الواجهة الطلبين وتشير إلى أول نقطة تفرّع، سواء وقعت في model أو system أو tools أو messages. في السابق، حين كان التخزين المؤقت يتعطّل بصمت، لم تكن ترى سوى أن usage.cache_read_input_tokens صار 0، من دون أن تعرف أي جزء هو الذي تغيّر.
| النقطة | الشرح | قيمتها بالنسبة لك |
|---|---|---|
| مفتاح التشغيل | لا تُخزَّن البصمة إلا إذا حمل جسم الطلب كائن diagnostics في مستواه الأعلى |
لا حاجة لتعديل منطق العمل، يكفي إضافة حقل واحد |
| طريقة المقارنة | تمرير معرّف استجابة الجولة السابقة في previous_message_id |
تحديد موقع أول مقطع متفرّع مباشرةً |
| حقل النتيجة | يعطي cache_miss_reason واحدًا من ستة أنواع |
لكل نوع موضع إصلاح واضح |
| المؤشر المرافق | يجب قراءته مع usage.cache_read_input_tokens |
لتجنّب الخلط بين «لا يوجد تفرّع» و«لم يُفعَّل» |
| نطاق التوفّر | واجهة Claude API الرسمية فقط هي التي توفّره | عند المرور عبر قنوات أخرى تحتاج إلى فحص usage بدلًا منه |
الخط الزمني لتشخيص التخزين المؤقت في Claude
أُطلق هذا Feature في مايو 2026 بصيغة beta، وكان يتطلّب حينها ترويسة anthropic-beta: cache-diagnosis-2026-04-07. وخلال سبتمبر شُدّدت القواعد مرّة واحدة: فلا تُخزَّن البصمة إلا للطلبات التي تحمل كائن diagnostics صراحةً، أما الطلبات التي تحمل الترويسة فقط فلا تُسجَّل.
وفي 23 سبتمبر تحوّل إلى إصدار رسمي، فلم تبقَ حاجة إلى cache-diagnosis-2026-04-07، والطلبات التي تحمل الترويسة القديمة تعمل كالمعتاد. والآن يظهر الحقل diagnostics دائمًا في استجابة POST /v1/messages، وتكون قيمته null عند عدم تفعيله. لذا فإن رؤية هذا الحقل بقيمة null لا تعني أن الواجهة وقع فيها خلل.
تحتفظ البصمة بالهاش وتقدير عدد الـ tokens فقط، ولا تحتفظ بمحتوى الموجه الأصلي. وهي مفهرسة حسب response id، ويقتصر نطاقها على المؤسسة والـ workspace الحاليين، ومدة الاحتفاظ بها قصيرة.
3 خطوات لاكتشاف معدل إصابة التخزين المؤقت في Claude باستخدام diagnostics
نكتب الخطوات الثلاث التالية وفقًا لوصف الحقول الرسمي. إذا كنت تستدعي عبر APIYI، فإن واجهة Messages الأصلية تُملأ فيها base_url بـ https://api.apiyi.com/v1، ومسار الطلب هو /v1/messages. لكن انتبه، سيبيّن الجزء التجريبي لاحقًا الوضع الفعلي لعودة diagnostics في سيناريو الوكيل.
الخطوة 1: أضف كائن diagnostics في المستوى الأعلى للطلب
diagnostics هو المفتاح الوحيد، والطلبات التي لا تحمله لن تخزّن أي بصمة، وبالتالي لا يوجد ما يمكن مقارنته لاحقًا. في الجولة الأولى لا يوجد موضوع للمقارنة، لذا يُمرَّر previous_message_id بالقيمة null، أي «ابدأ التسجيل من هذه الجولة».
- احتفظ برقم الإصدار المعتاد في ترويسة الطلب:
anthropic-version: 2023-06-01 - لا حاجة لحمله بعد الإصدار الرسمي:
anthropic-beta: cache-diagnosis-2026-04-07 - أضف في المستوى الأعلى لجسم الطلب:
"diagnostics": {"previous_message_id": null} - كتلة system التي تحتاج التخزين المؤقت تضع نقطة التوقف كالمعتاد:
"cache_control": {"type": "ephemeral"} - ماذا سترى: في الاستجابة تكون
diagnosticsبقيمةnull، وcache_read_input_tokensعادةً 0، وcache_creation_input_tokensأكبر من 0
رؤية null في الجولة الأولى لا تعني الفشل. هذه الجولة تكتب التخزين المؤقت، ولم يكن هناك جولة سابقة للمقارنة أصلًا، فلا حاجة لاستكشاف الأخطاء.
الخطوة 2: في كل جولة لاحقة، مرّر معرّف id الخاص باستجابة الجولة السابقة
بدءًا من الجولة الثانية، ضع قيمة id الخاصة باستجابة الجولة السابقة في previous_message_id. الخطأ الأكثر شيوعًا هو تمرير diagnostics في الجولة الأولى فقط ثم نسيانها بعد ذلك. فتكون النتيجة أن الطلب الذي تشير إليه الجولة التالية لم يُسجَّل، فيُعاد إليك الخطأ previous_message_not_found.
- جسم طلب الجولة الثانية:
"diagnostics": {"previous_message_id": "<معرّف استجابة الجولة الأولى>"} - جسم طلب الجولة الثالثة:
"diagnostics": {"previous_message_id": "<معرّف استجابة الجولة الثانية>"} - قاعدة الحلقة متعددة الجولات: الجولة الأولى تمرّر
null، والثانية تمرّرr1.id، والثالثة تمرّرr2.id، وهكذا - عند الاستدعاء المتدفق (streaming)، تظهر النتيجة في حدث
message_start، ويُمرَّر المعرّفidجولةً بعد جولة بالطريقة نفسها - ما الذي ستراه: عندما تكون الفجوة بين جولتين متجاورتين قصيرة بما يكفي، وكانتا داخل الـ workspace نفسه، تبدأ نتائج المقارنة بالظهور في الاستجابة
الخطوة 3: اقرأ cache_miss_reason وأصلح المشكلة المطابقة
لـ diagnostics ثلاث قيم محتملة، فرّق بينها قبل القراءة:
null: الطلب لم يحملdiagnostics؛ أو كانprevious_message_idقيمتهnull؛ أو اكتملت المقارنة ولم يُكتشف أي اختلاف{"cache_miss_reason": null}: المقارنة ما زالت جارية، لأن الاستجابة بدأت بسرعة كبيرة، فالجولة الحالية لا تعطي حكمًا، وانظر الجولة التاليةcache_miss_reasonكائن: يوجد حكم بالفعل، ويحمل نوع التفرّع وتفاصيله- ما الذي ستراه: بعد الحصول على النوع، عدّل وفق جدول المقارنة في القسم التالي، وأصلح أول تفرّع أولًا، لأنه يبلّغ عن أول نقطة اختلاف فقط، وقد تحجب المشاكل اللاحقة خلفه
🚀 بداية سريعة: إذا أردت أولًا التأكد مما إذا كانت بادئة التخزين المؤقت (cache prefix) لديك قابلة للكتابة والوصول (hit)، يمكنك في APIYI apiyi.com استخدام المفتاح نفسه للتبديل بين طرازات Claude المختلفة وإجراء جولتين للمقارنة، مع التركيز على مطابقة الرقمين: كتابة التخزين المؤقت وقراءته في usage.
أنواع cache_miss_reason الستة وأماكن الإصلاح
بعد الحصول على cache_miss_reason، طابقه مع الجدول التالي لتعرف أين يجب أن تُجري التعديل:
| النوع | المعنى | أين تُصلح |
|---|---|---|
model_changed |
النموذج مختلف عن الجولة السابقة، مثل أن التوجيه أو اختبار A/B أو fallback غيّر النموذج. التخزين المؤقت معزول حسب النموذج | ثبّت النموذج داخل محادثة التخزين المؤقت الواحدة |
system_changed |
تغيّر system، وأكثر الحالات شيوعًا إدراج طابع زمني أو معرّف طلب أو أي قيمة تختلف في كل مرة | حوّل system إلى ثابت مستقر بايتًا ببايت، وانقل البيانات الديناميكية إلى أول رسالة user بعد نقطة الفصل |
tools_changed |
حُذفت الأدوات أو أُضيفت أو تغيّر ترتيبها، أو كان ناتج تسلسل input_schema غير مستقر |
أرسل نفس قائمة الأدوات في كل جولة بترتيب ثابت، مع تسلسل المفاتيح مرتبة |
messages_changed |
عُدّلت رسائل أقدم أو أُعيد ترتيبها أو حُذفت، بدلًا من الإضافة في نهاية السجل | أضف إلى السجل فقط، وأعد تمرير محتوى assistant ونتائج الأدوات كما هي |
previous_message_not_found |
تعذّر العثور على البصمة المقابلة، وهذا لا يعني أن الطلب تغيّر | أرفق diagnostics في كل جولة، ولا تنتقل بين workspaces، ولا تجعل الفاصل طويلًا |
unavailable |
تعذّر الحصول على نتيجة التشخيص في هذه الجولة، مثل عدم اتساق tool_choice أو thinking أو context_management أو output_config أو output_format أو مجموعة beta header، وقد يكون السبب أيضًا أن المحادثة طويلة جدًا |
أبقِ هذه المعاملات ثابتة طوال دورة حياة محادثة التخزين المؤقت الواحدة |
الأنواع الأربعة *_changed تُرفق أيضًا بـ cache_missed_input_tokens، وهو يشير إلى عدد رموز الإدخال القابلة للتخزين المؤقت التي فُقدت تقريبًا بعد نقطة التفرّع. هذا الرقم محسوب من طول البايت، ويصلح فقط لتقدير الحجم، وليس رقم فاتورة، وقد يكون أحيانًا أكبر من usage.input_tokens.
الاعتماد على diagnostics وحده يضلّلك: ادمجها مع usage للحكم على إصابة ذاكرة Claude المؤقتة
تجيب diagnostics عن سؤال «هل تغيّر طلبي؟»، بينما يجيب usage.cache_read_input_tokens عن سؤال «هل أصابت الذاكرة المؤقتة؟». السؤالان مختلفان، والاعتماد على أحدهما وحده يوصلك بسهولة إلى استنتاج خاطئ.
| نتيجة diagnostics | الرموز المقروءة من الذاكرة المؤقتة | الاستنتاج | ما الذي تفعله |
|---|---|---|---|
null |
مرتفع | البادئة مستقرة، والذاكرة المؤقتة أصيبت | لا حاجة لأي إجراء |
null |
منخفض أو صفر | الطلب لم يتغير، لكن صلاحية الذاكرة المؤقتة انتهت | قلّل الفاصل بين الطلبات، أو استخدم TTL مدته ساعة واحدة |
*_changed |
منخفض | الطلب تغيّر، فلم تُصب الذاكرة المؤقتة | أصلح السبب وفق جدول القسم السابق |
*_changed |
مرتفع | التغيير وقع في موضع متأخر، ونقاط التوقف الأمامية ما زالت تُصيب | يستحق الإصلاح، لكن أثره محدود |
نؤكد مرة أخرى: null لا تعني أن الأمر لم ينجح، بل قد تكون هي أفضل نتيجة ممكنة. وهناك حالات لا ينطبق عليها هذا الجدول: الجولة الأولى، وحين تكون cache_miss_reason قيمتها null (أي أن المقارنة ما زالت جارية)، وكذلك previous_message_not_found وunavailable. في هذه الحالات لم تحدث مقارنة صالحة من الأصل.
إذا لم تكن متأكدًا من الجولة التي تنتمي إلى أي خانة، يمكنك على APIYI عبر apiyi.com إرسال الطلب نفسه مرتين متتاليتين، وتسجيل أرقام القراءة والكتابة من الذاكرة المؤقتة في كل جولة، ثم مقارنتها بالمصفوفة أعلاه واستبعاد الاحتمالات بندًا بندًا.
أسباب انخفاض معدل إصابة الذاكرة المؤقتة في Claude: ثلاثة شروط صارمة
في كثير من الحالات، لا يكون سبب انخفاض معدل الإصابة هو تغيّر الطلب، بل إن الذاكرة المؤقتة لم تُكتب من الأساس. إذا غاب أحد الشروط الثلاثة التالية، فلن تعمل الذاكرة المؤقتة إطلاقًا:
- يجب وضع
cache_controlبشكل صريح: يمكنك وضعه على كتلة محتوى محددة لإنشاء نقطة توقف صريحة، أو وضعه على مستوى أعلى الطلب ليقوم النظام تلقائيًا بوضع نقطة التوقف على آخر كتلة قابلة للتخزين المؤقت. أما إذا كان المحتوى نصًا خالصًا (سلسلة نصية) بلا كتل محتوى يمكن تعليق العلامات عليها، فلن يتم التخزين المؤقت أبدًا. - بلوغ الحد الأدنى لطول المحتوى القابل للتخزين المؤقت: في Claude API، الحد لكل من Sonnet 5.5 و Opus 5.5 هو 512 tokens. وعندما تكون البادئة (prefix) أقصر من ذلك، تُتجاهل الذاكرة المؤقتة بصمت دون إرجاع أي خطأ.
- تطابق البادئة بايتًا ببايت: يُضاف السجل إلى النهاية فقط، مع بقاء
systemوtoolsمستقرين. أي تغيّر في المسافات أو ترتيب حقول JSON أو الطوابع الزمنية سيُعامل كبادئة جديدة.
توثيق الذاكرة المؤقتة في APIYI يذكر أيضًا حدّين صارمين: لا يزيد عدد نقاط التوقف cache_control في الطلب الواحد عن 4، وكل نقطة توقف تعود للخلف فقط عبر آخر 20 كتلة محتوى. لذلك فإن وضع العلامة على الرسالة الأخيرة فقط في محادثة طويلة متعددة الأدوار لن يغطي كامل السجل.
كذلك غالبًا ما يُغفل أمر TTL. القيمة الافتراضية هي 5 دقائق، ويُجدَّد العداد مع كل إصابة، لكن العدّ يبدأ من لحظة كتابة الطلب أو قراءته، لا من لحظة انتهاء الاستجابة. فإذا استغرق رد متدفق (streaming) نحو 4 دقائق، فعليك إرسال الطلب التالي خلال دقيقة تقريبًا. وإذا احتجت نافذة أطول، يمكنك كتابة "ttl": "1h" داخل cache_control.
حساب التكلفة عندما تنخفض نسبة إصابة التخزين المؤقت في Claude إلى الصفر
نعرض الأسعار أولًا، والوحدة دولار لكل مليون token، والبيانات بتاريخ 2026-10-25، والمرجع هو السعر اللحظي في لوحة التحكم:
| النموذج | الإدخال | الإخراج | قراءة التخزين المؤقت | كتابة 5 دقائق | كتابة ساعة واحدة |
|---|---|---|---|---|---|
| Claude Sonnet 5.5 | $2 | $10 | $0.10 | $2.50 | $4 |
| Claude Opus 5.5 | $4 | $20 | $0.20 | $5 | $8 |
| Claude Haiku 5.5 (حتى 100 ألف token) | $0.1 | $0.5 | $0.01 | $0.125 | $0.20 |
| Claude Haiku 5.5 (أكثر من 100 ألف token) | $0.50 | $2.50 | $0.05 | $0.625 | $1 |
يجب النظر إلى المعاملات كلٌّ على حدة. فالإرشاد العام في دليل التخزين المؤقت من APIYI هو: الإصابة 0.1×، والكتابة لمدة 5 دقائق 1.25×، والكتابة لمدة ساعة 2×. وقد تغيّر Sonnet 5.5 في 7 أكتوبر مع التعديل الرسمي، إذ انخفضت قراءة التخزين المؤقت من $0.20 إلى $0.10، لتصبح 0.05× من سعر الإدخال الأساسي، أما سعر الكتابة فلم يتغير.
هذا التعديل ليس تخفيضًا شاملًا، فقراءة التخزين المؤقت في Sonnet 5 لا تزال $0.20. لذلك لا تستخدم 0.1× لحساب Sonnet 5.5، بل ارجع إلى قائمة النماذج في المنصة لمعرفة السعر الدقيق لكل نموذج.
تُحسب نقطة التعادل وفق المعامل العام 0.1× في المنصة: مع TTL لمدة 5 دقائق يكفي إعادة الاستخدام مرتين للتعادل (1.25 + 0.1 = 1.35، وهو أقل من 2.0 بدون تخزين مؤقت)؛ ومع TTL لمدة ساعة يلزم إعادة الاستخدام ثلاث مرات (2 + 0.2 = 2.2، وهو أقل من 3.0).
لنأخذ مثالًا حسابيًا. Sonnet 5.5، بادئة ثابتة من 30 ألف token، و200 طلب في اليوم، وكلها ضمن TTL لمدة 5 دقائق:
- إصابة كاملة: 200 × 30 ألف × $0.10/مليون = $0.60، مع إضافة كتابة واحدة بقيمة $0.075، ليكون الإجمالي نحو $0.675/يوم
- عدم إصابة إطلاقًا: 200 × 30 ألف × $2/مليون = $12/يوم
الفرق في فاتورة اليوم الكامل بين الحالتين نحو 17.8 ضعفًا، وهو ليس فرقًا في سعر الوحدة. فسعر الوحدة $2 مقابل $0.10، أي فرق 20 ضعفًا. وإذا استخدمت TTL لمدة ساعة، تصبح الكتابة الواحدة $0.12، وسعر الإصابة لا يتغير. وعندما تتجاوز الفواصل بين الطلبات 5 دقائق بشكل متكرر، قارن بين الاثنين: أيهما أقل، هذه الزيادة في تكلفة الكتابة أم تكلفة إعادة بناء البادئة مرارًا؟
كيف تتحقق من معدل إصابة التخزين المؤقت في Claude عند المرور عبر APIYI
لنبدأ بنتيجة الاختبار الفعلي. في 2026-10-26 أجرينا اختبارًا مباشرًا على APIYI باستخدام Claude Sonnet 5.5 في جولتين: في الجولة الأولى كان الكتابة إلى التخزين المؤقت 2523 والقراءة 0؛ وفي الجولة الثانية، بعد إعادة إرسال الطلب نفسه كما هو، أصبحت القراءة من التخزين المؤقت 2523 والكتابة 0، وتطابقت أعداد الـ tokens تمامًا. وباستخدام Claude Opus 5.5 مع بادئة طويلة تمكّنا أيضًا من الكتابة والقراءة بنجاح.
لكن حقل diagnostics لم يظهر في الاستجابة. لا في الاستدعاء غير المتدفق، ولا داخل message_start في الاستدعاء المتدفق. أعدنا الإرسال مع beta header، وتعمدنا تعديل الـ system لإحداث حالة عدم إصابة حقيقية (قراءة 0، كتابة 2526)، ومع ذلك لم يظهر الحقل في الاستجابة. جميع الطلبات أعادت 200 دون أي خطأ. فقناة المنبع في طبقة الوسيط ليست بالضرورة واجهة Claude API الرسمية، لذا في سيناريو الوسيط نعتمد أساسًا على مقارنة الحقلين الموجودين في usage.
| الظاهرة عند الفحص | التفسير |
|---|---|
cache_read_input_tokens في هذه الجولة يساوي بدقة cache_creation_input_tokens في الجولة السابقة |
إصابة كاملة للبادئة |
| القراءة في هذه الجولة أقل بوضوح من الكتابة في الجولة السابقة | تمت إصابة مقطع أقرب فقط، وهناك محتوى تغيّر في المنتصف |
| الكتابة تظل صفرًا دائمًا | لم يتم وضع العلامة، أو الطول غير كافٍ، أو تم استخدام صيغة متوافقة مع OpenAI |
| الجولة الثانية تكتب مجددًا والقراءة صفر | تغيّرت البادئة، تحقق من الطابع الزمني وUUID وترتيب التسلسل |
انتبه أيضًا إلى نقطة مهمة جدًا: التخزين المؤقت يعمل فقط عبر /v1/messages الأصلية. إذا استدعيت Claude بالصيغة المتوافقة مع OpenAI عبر /v1/chat/completions، فلن تحصل على فوترة التخزين المؤقت مهما كانت المعاملات التي تمررها.
💡 نصيحة للفحص: يقوم APIYI على apiyi.com بتمرير
cache_controlإلى المنبع كما هو، ويعيد الحقلين الخاصين بالتخزين المؤقت في الاستجابة كما هما، فلا حاجة إلى أي تعديل إضافي في الكود لطبقة الوسيط. يكفي أن تحوّل قاعدة «قراءة هذه الجولة = كتابة الجولة السابقة» إلى تنبيه في السجلات، وستستغني بذلك عن معظم الفحص اليدوي.
قيود ميزة التشخيص diagnostics في التخزين المؤقت لدى Claude
لا تحلّ diagnostics كل المشكلات، لذا تعرّف على حدودها قبل أن تستخدمها:
- تتوفر في Claude API الرسمي فقط، أما Claude المستضاف على Amazon Bedrock وGoogle Cloud فلا يوفّرها
- تُحفظ البصمات لفترة قصيرة فقط، لذا تحتاج إلى إرسال الطلبات في جولات متتالية وبفواصل زمنية قصيرة
- يجب أن ينتمي الطلبان إلى المنظمة نفسها وإلى مساحة العمل (workspace) نفسها، ويمكنك التحقق من ذلك عبر ترويسة الاستجابة
anthropic-workspace-id - في المحادثات الطويلة، إذا كان التغيير مختبئًا في موضع عميق داخل قائمة الرسائل، فقد يعود الناتج
unavailableفقط - إنها آلية best-effort، أي أن عدم الحصول على نتيجة لا يعطّل الطلب ولا يجعله يفشل
الأسئلة الشائعة
س1: لماذا تبقى diagnostics بقيمة null دائمًا؟
هناك ثلاث حالات: إما أنك لم تُرفق كائن `diagnostics`، أو أنك في الجولة الأولى وحقل `previous_message_id` يساوي `null`، أو أن المقارنة اكتملت ولم يظهر أي اختلاف. احكم على الأمر بالاقتران مع قراءات التخزين المؤقت: إذا كانت القراءة مرتفعة فكل شيء سليم، وإذا كانت صفرًا فالسبب الأرجح أن التخزين المؤقت انتهت صلاحيته. وإذا كنت تمرّ عبر خدمة وكيل، فقد لا يُعاد الحقل أصلًا، وعندها استخدم فحص usage بدلًا منه.
س2: هل يعني previous_message_not_found أن الطلب تغيّر؟
لا. هو يعني فقط أن البصمة المقابلة لم تُوجد. والأسباب الشائعة ثلاثة: الجولة السابقة لم تحمل `diagnostics`، أو أن الجولة السابقة جاءت من مساحة عمل أخرى، أو أن الفاصل الزمني كان طويلًا جدًا. أرفق `diagnostics` في كل جولة وقلّص الفاصل الزمني وسيعود كل شيء طبيعيًا.
س3: هل تُحتسب رسوم إضافية على التشخيص؟
لا تُدرج الوثائق الرسمية «رسوم التشخيص» كبند منفصل، بل تُحتسب مع طلبات Messages العادية. كما أن الوثائق لا تنص صراحةً على عدم وجود زيادة في السعر، لذا اعتمد على الفاتورة ولوحة التحكم في معرفة التكلفة الفعلية.
س4: هل يمكن استخدام هذا التشخيص عند المرور عبر خدمة وكيل؟
في اختباراتنا الفعلية على APIYI لم نحصل على حقل `diagnostics`، لكن كتابة التخزين المؤقت وإصاباته كانت تعمل بشكل طبيعي. يمكنك الحكم عبر مقارنة «هل قراءة هذه الجولة تساوي تمامًا كتابة الجولة السابقة؟»، وتجد طريقة التكامل في وثائق فوترة التخزين المؤقت على APIYI apiyi.com.
س5: كتبت cache_control لكن لم يُكتب شيء إلى التخزين المؤقت؟
تحقّق من ثلاثة أمور أولًا: هل content مجرد نص عادي؟ وهل بلغت البادئة 512 tokens (في Sonnet 5.5 وOpus 5.5)؟ وهل تستخدم صيغة متوافقة مع OpenAI؟ إذا اختلّ أي شرط من الثلاثة، فسيُتخطّى التخزين المؤقت بصمت.
س6: ظهرت عدة مشكلات في الوقت نفسه، أيّها أصلح أولًا؟
أصلح المشكلة التي يبلّغ عنها `cache_miss_reason` أولًا. فهو يذكر نقطة التفرّع الأبكر فقط، وبعد إصلاحها شغّل جولة أخرى لتظهر المشكلات التي كانت محجوبة خلفها. وإعادة تشغيل الطلب نفسه مرارًا على APIYI apiyi.com تساعدك على استبعاد المشكلات واحدة تلو الأخرى بسرعة معقولة.
النقاط الأساسية لتشخيص التخزين المؤقت في Claude
- ما هو diagnostics: تمرّر معرّف استجابة الجولة السابقة، لتحديد أول نقطة تشعّب في البادئة
- كيف تُفعّله: ضع
diagnosticsفي المستوى الأعلى، ومرّرnullفي الجولة الأولى، ثم مرّره في كل جولة بعدها - معنى
null: يكونnullأيضًا في الجولة الأولى أو عند عدم وجود اختلاف، ولا يصح اعتباره بمفرده إشارة إلى عطل - كيف تحكم: لا يمكنك استنتاج شيء إلا بالنظر إلى diagnostics مع
cache_read_input_tokensفي الوقت نفسه - الشروط الصارمة: وضع علامة صريحة، وبلوغ 512 tokens، وتطابق البادئة بايتًا ببايت
- فارق التكلفة: بادئة من 30 ألف token مع 200 استدعاء يوميًا، تختلف فاتورة اليوم بأكمله بنحو 17.8 مرة
- الفحص الذاتي عبر خدمة الوسيط: تحقّق على APIYI apiyi.com من أن «قراءة هذه الجولة تساوي كتابة الجولة السابقة»
الخلاصة
يمكن اختصار تتبّع معدل إصابة التخزين المؤقت في Claude إلى ثلاثة أمور:
- حدّد نقطة التشعّب: أرفق
diagnosticsفي كل جولة، واقرأcache_miss_reason، وأصلح أول موضع يُبلَّغ عنه - الحكم المتقاطع: انظر إلى diagnostics وusage معًا، فـ
nullلا يعني أنه لم يُفعّل - التزم بالشروط الصارمة: ضع العلامات جيدًا، واحرص على بلوغ الطول المطلوب، وأضف إلى السجل فقط دون تعديل، وحافظ على ثبات system وtools
إذا تعذّر على سلسلة الاستدعاء لديك الحصول على diagnostics، فابنِ فحصًا ذاتيًا من الحقلين الموجودين في usage. يُنصح أولًا بالتحقق من أرقام قراءة وكتابة التخزين المؤقت عبر طلبين على APIYI apiyi.com، ثم الانتقال إلى بيئة الإنتاج.
📚 المراجع
- وثائق Claude الرسمية: تشخيصات التخزين المؤقت (Cache diagnostics): حقول التشخيص والأنواع الستة ومصفوفة الحكم
- الرابط:
platform.claude.com -
الوصف: تعتمد حقول diagnostics والجدول الزمني والقيود الواردة في هذا المقال على هذه الوثيقة
-
وثائق Claude الرسمية: التخزين المؤقت للموجهات (Prompt caching): قواعد التخزين المؤقت ومدة الصلاحية (TTL) والحد الأدنى للطول والأسعار
- الرابط:
platform.claude.com -
الوصف: مصدر الحد الأدنى القابل للتخزين المؤقت وجدول الأسعار الرسمي
-
قائمة طرازات APIYI: أسعار الإدخال والإخراج وقراءة التخزين المؤقت لمختلف طرازات Claude
- الرابط:
docs.apiyi.com/models -
الوصف: تم تحديث بيانات الأسعار في 2026-10-25
-
دليل فوترة التخزين المؤقت لـ Claude Prompt Caching من APIYI: المعاملات ونقطة استرداد التكلفة ومعايير الفحص الذاتي
- الرابط:
docs.apiyi.com/api-capabilities/claude-prompt-caching - الوصف: الأساس المعتمد لاستكشاف الأخطاء في سيناريوهات خدمة وكيل API
المؤلف: فريق APIYI التقني
التواصل التقني: يسعدنا تواصلكم معنا عبر الصفحة الرئيسية لموقع APIYI، ولمزيد من المواد يمكنكم زيارة مركز التوثيق docs.apiyi.com
