تخزين موجه Claude المؤقت لا يعمل؟ استكشاف 5 أسباب محتملة ودليل سريع للحد الأدنى من الرموز المميزة (Token)

عند استخدام Claude API لإجراء استدعاءات ذات سياق طويل، يواجه العديد من المطورين حيرة مشتركة: على الرغم من التصريح عن التخزين المؤقت في حقل cache_control، إلا أن قيم cache_creation_input_tokens و cache_read_input_tokens في الاستجابة تظل صفرًا، ولا تظهر أي خصومات للتخزين المؤقت في الفاتورة. سنقوم في هذا المقال بتفكيك الأسباب الخمسة الرئيسية لفشل التخزين المؤقت (Prompt Caching) في Claude، مع التركيز على "الحد الأدنى لعدد الرموز (Tokens) القابلة للتخزين" وآلية "الفشل الصامت" التي غالبًا ما يتم تجاهلها.

القيمة الجوهرية: بعد قراءة هذا المقال، ستفهم الحدود الدنيا للتخزين المؤقت في نماذج Anthropic، وستعرف لماذا لا تظهر أخطاء عند استخدام موجه قصير مع cache_control رغم عدم حدوث تخزين، وستتعلم كيفية التحقق من نجاح التخزين باستخدام 4 أسطر من الكود.

النقاط الجوهرية لـ Claude prompt caching

تعد خاصية التخزين المؤقت للموجه (Prompt Caching) في Claude آلية مقدمة من Anthropic: حيث يتم تخزين الموجهات النظامية (System Prompts) المتكررة، والمستندات الطويلة، وتعريفات الأدوات في ذاكرة مؤقتة، وعند حدوث تطابق في المرة التالية، يتم احتساب التكلفة بناءً على سعر القراءة، وهو أرخص بنحو 90% من سعر الإدخال العادي. تتميز هذه الخاصية بـ "مطابقة البادئة + التصريح الصريح + الفشل الصامت"، وهذه النقاط الثلاث تحدد مسار استكشاف الأخطاء وإصلاحها.

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

إذا كنت تستخدم منصة APIYI (apiyi.com) لاستدعاء نماذج Claude (Sonnet، Opus، Haiku)، فإن منطق التخزين المؤقت يتطابق تمامًا مع واجهة Anthropic الرسمية. نوصي بطباعة حقل usage مرة واحدة قبل الاعتماد الكلي، للتأكد من أن التخزين المؤقت يعمل بالفعل قبل زيادة حجم الاستخدام.

دليل سريع: الحد الأدنى لعدد الـ Token في ميزة التخزين المؤقت (Prompt Caching) لنماذج Claude

السبب الأكثر شيوعاً لفشل التخزين المؤقت هو عدم وصول طول الموجه (Prompt) إلى الحد الأدنى الذي حددته Anthropic لكل نموذج. إذا كان طول الموجه أقل من هذا الحد، فسيتم التعامل معه كطلب عادي حتى لو قمت بتضمين cache_control. تختلف هذه الحدود بشكل كبير بين النماذج؛ إليك البيانات الرسمية المحدثة لشهر مايو 2026، ننصحك بحفظها للرجوع إليها.

قد يتفاجأ البعض عند رؤية هذا الجدول: لماذا يتطلب نموذج "صغير" مثل Haiku 4.5 حداً مرتفعاً مثل Opus 4.7؟ السبب هو أن الجيل الجديد من Haiku يستخدم نافذة انتباه (Attention Window) أطول، حيث لا تظهر الفائدة الهندسية للتخزين المؤقت إلا مع بادئات (Prefixes) أطول، لذا قامت Anthropic برفع الحد كجزء من استراتيجية المنتج.

الخطأ الأكثر شيوعاً في الممارسة العملية هو أن المطورين يصممون الموجهات بناءً على اعتيادهم على حد 1024 الخاص بـ Sonnet 3.7، وعند الانتقال إلى Sonnet 4.6 يتوقف التخزين المؤقت عن العمل، فيظنون أن هناك خطأ في الكود. إذا كنت تستخدم APIYI (apiyi.com) لاستدعاء أجيال متعددة من نماذج Claude، فنحن ننصح بشدة بجعل هذا الجدول جزءاً من فحص المعاملات (Parameters) لديك، مع ضبط الحد ديناميكياً بناءً على حقل model.

الأسباب الخمسة الرئيسية لفشل التخزين المؤقت للموجه (Claude Prompt Caching)

بعد فهم "الحد الأدنى لعدد الرموز (Tokens)" و"الفشل الصامت"، يمكنك الآن استكشاف أسباب عدم نجاح التخزين المؤقت بشكل منهجي. فيما يلي الأسباب الخمسة مرتبة حسب تكرار الحدوث، حيث يمثل السببان الأولان غالبية الحالات التي نواجهها في التصحيح اليومي.

السبب 1: طول الموجه أقل من الحد الأدنى

هذا هو السبب الأول بلا منازع. على سبيل المثال، إذا قمت بتعريف التخزين المؤقت على نموذج Sonnet 3.5، ولكن الموجه النظامي (System Prompt) الفعلي يحتوي على 1500 رمز فقط، فلن يتم إنشاء التخزين المؤقت على الإطلاق. طريقة التشخيص بسيطة: استخدم "محلل الرموز" (Tokenizer) المحلي لتقدير إجمالي عدد الرموز للموجه النظامي + تعريفات الأدوات + أجزاء الرسائل المخزنة مؤقتاً، ثم قارنها بالحد الأدنى المذكور في الجدول.

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

السبب 2: أي تغيير على مستوى البايت في بادئة التخزين المؤقت

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

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

أفضل طريقة لاستكشاف هذه المشكلة هي إجراء مقارنة (diff) لحمولة (payload) الطلبين بالكامل. إذا كنت تستخدم خدمة APIYI (apiyi.com) كوكيل موحد في بوابتك البرمجية الخاصة، يمكنك استخراج بصمة (hash) جسم الطلب مباشرة من سجلات البوابة، وإذا وجدت أن البصمات غير متطابقة، فستتمكن غالباً من تحديد مكان الانحراف في البادئة.

السبب 3: انتهاء صلاحية TTL

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

من سمات انتهاء صلاحية TTL أن cache_creation_input_tokens تصبح فجأة قيمة غير صفرية، بينما كنت تعتقد أن هذا الطلب يجب أن يقرأ من التخزين المؤقت. إذا اكتشفت هذه الحالة، يمكنك تقليل الفاصل الزمني بين الطلبين، أو التبديل إلى "ttl": "1h".

السبب 4: خطأ في موقع cache_control

يجب وضع cache_control على كتلة محتوى محددة داخل مصفوفات system أو messages أو tools، ويجب أن يكون النوع ephemeral. تشمل الاستخدامات الخاطئة الشائعة:

• وضع cache_control في المعلمات العليا لـ messages.create() بدلاً من كتلة محتوى معينة.
• التصريح عنه في رسالة user داخل مصفوفة messages بينما البادئة التي تريد تخزينها فعلياً هي system.
• كتابة عدة cache_control في نفس الرسالة دون الوصول إلى حد 2048 رمزاً.

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

السبب 5: عدم مشاركة التخزين المؤقت عبر مساحات العمل أو النماذج

منذ 5 فبراير 2026، قامت Anthropic بتغيير حدود عزل التخزين المؤقت للموجه لتصبح على "مستوى مساحة العمل" (workspace)، مما يعني أن التخزين المؤقت بين مساحات العمل المختلفة غير مرئي لبعضه البعض. إذا كانت استدعاءاتك تمر عبر مفاتيح API مختلفة أو مساحات عمل مختلفة، فلن يمكن إعادة استخدام التخزين المؤقت.

ينطبق المنطق نفسه على مستوى النموذج. إذا قمت بكتابة نفس الموجه في التخزين المؤقت على نموذج Sonnet 3.5، فلن يتم استخدامه عند التبديل إلى Sonnet 3.0. عند جدولة نماذج متعددة، من الأفضل الاحتفاظ بنص برمجي لتسخين التخزين المؤقت لكل نموذج على حدة، أو إعادة استخدام نفس مساحة العمل الأصلية مباشرة عبر منصات التجميع مثل APIYI (apiyi.com) لتجنب تفتت التخزين المؤقت.

كود التحقق من نجاح التخزين المؤقت (Caching) في Claude ومنطق اتخاذ القرار

الخطوة الأولى دائمًا لاستكشاف أخطاء عدم نجاح التخزين المؤقت هي "طباعة حقل usage". في كل استجابة من messages.create في Anthropic، يتم إرفاق كائن usage يحتوي على 4 حقول أساسية، وهي المرجع الوحيد الموثوق للحكم على حالة التخزين المؤقت.

كود التحقق المبسط

import anthropic

client = anthropic.Anthropic(
    api_key="YOUR_APIYI_KEY",
    base_url="https://api.apiyi.com"
)

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    system=[{
        "type": "text",
        "text": LONG_SYSTEM_PROMPT,   # يجب أن يكون ≥ 2048 token
        "cache_control": {"type": "ephemeral"}
    }],
    messages=[{"role": "user", "content": "your question"}]
)

u = response.usage
print(f"كتابة التخزين: {u.cache_creation_input_tokens}")
print(f"قراءة التخزين: {u.cache_read_input_tokens}")
print(f"مدخلات غير مخزنة: {u.input_tokens}")

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

import anthropic
import logging

MIN_TOKENS = {
    "claude-opus-4-7": 4096,
    "claude-opus-4-6": 4096,
    "claude-opus-4-5": 4096,
    "claude-sonnet-4-6": 2048,
    "claude-sonnet-4-5": 1024,
    "claude-haiku-4-5": 4096,
    "claude-haiku-3-5": 2048,
}

def call_with_cache_check(model: str, system_text: str, user_msg: str):
    client = anthropic.Anthropic(
        api_key="YOUR_APIYI_KEY",
        base_url="https://api.apiyi.com"
    )
    response = client.messages.create(
        model=model,
        max_tokens=1024,
        system=[{
            "type": "text",
            "text": system_text,
            "cache_control": {"type": "ephemeral"}
        }],
        messages=[{"role": "user", "content": user_msg}]
    )
    u = response.usage
    if u.cache_creation_input_tokens == 0 and u.cache_read_input_tokens == 0:
        logging.warning(
            f"التخزين المؤقت لم يعمل، قد يكون السبب أقل من الحد الأدنى {MIN_TOKENS.get(model)} token"
        )
    return response

جدول تحديد حالة النجاح

السطر الأخير هو السمة المميزة عند حدوث مشكلة. عند رؤية هذه القيم، انتقل مباشرة إلى السبب الأول وابدأ الفحص وفقًا للاتجاهات الخمسة. إذا كان فريقك يتطلب استقرارًا عاليًا للواجهة، يمكنك دمج منطق التحقق هذا كـ "وسيط" (Middleware) في سلسلة استدعاءات APIYI apiyi.com، وإرسال تنبيه فوري عند حدوث أي خلل.

4 حيل عملية للوصول إلى الحد الأدنى من الـ Token

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

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

الحيلة الثانية "تعريف الأدوات" غالبًا ما يتم تجاهلها. يدعم حقل tools في Anthropic خاصية cache_control أيضًا، وهو فعال بشكل خاص لتطبيقات الوكلاء (Agents) التي تستخدم أدوات متعددة.

الحيلة الثالثة "أمثلة few-shot" مناسبة للمهام المعقدة. وضع 3-5 حالات قياسية في نهاية الـ system لا يحسن استقرار المخرجات فحسب، بل يرفع عدد الـ Token من 1500 إلى 2500-3500، مما يتجاوز عتبة Sonnet 4.6.

الحيلة الرابعة "حشو نصوص غير ذات صلة" هي للطوارئ فقط، ولا يُنصح باستخدامها يوميًا لأن النموذج سيقرأ تلك النصوص، مما قد يؤثر على أسلوب المخرجات. إذا لم يكن هناك بديل لزيادة الطول، يمكنك التفكير في التبديل عبر منصة APIYI apiyi.com إلى نماذج ذات عتبة أقل مثل Sonnet 4.5 أو Sonnet 3.7.

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

الخلاصة

قد يبدو استخدام prompt caching في Claude بسيطاً بمجرد إضافة حقل cache_control، ولكن عند التطبيق الفعلي قد تواجه عقبات مثل "الفشل الصامت + الحد الأدنى لعدد الـ Token + المطابقة الصارمة للبادئة". قائمة التحقق المكونة من 5 أسباب وجدول تحديد نجاح التخزين المؤقت في هذا المقال سيساعدان المطورين على تحديد 90% من مشاكل عدم التخزين في غضون 5 دقائق.

نصيحتنا هي تحويل كود التحقق إلى "برمجية وسيطة" (Middleware) افتراضية، وجعل جدول حدود النماذج ثابتاً برمجياً، وتحويل عملية تهيئة التخزين المؤقت إلى نص برمجي منفصل. إذا كان عملك يتطلب التبديل المتكرر بين نماذج لغة كبيرة متعددة، يمكنك إدارة استدعاءات Claude مركزياً عبر منصة APIYI (apiyi.com)، مما يتيح لك إعادة استخدام نفس استراتيجية التخزين المؤقت ومنطق المراقبة، وتجنب التكاليف الخفية الناتجة عن تشتت التخزين المؤقت واختلاف الحدود بين البيئات المختلفة.

الكاتب: فريق APIYI التقني
للتواصل: احصل على دعم كامل لتصحيح أخطاء سلسلة نماذج Claude و prompt caching عبر APIYI (apiyi.com)
تاريخ التحديث: 2026-05-12