تصميم الـ Cache الذي خفّض تكاليف Claude Code API بنسبة 90%

كنت أعمل على مسألة عاجلة في بيئة الإنتاج. في منتصف الجلسة، انهار الـ cache فجأة. فاتورة الـ API لتلك الساعة الواحدة كانت أعلى من مجموع الأيام الثلاثة السابقة مجتمعةً.

كان التوقيت شبه ساخر. في المساء ذاته، نشر كل من Thariq، الذي بنى Claude Code في Anthropic، وLance Martin من Anthropic، منشورات تشرح تصميم الـ prompt caching. حين قرأتها، أدركت أن الـ cache كان هشاً في بنيته من الأساس، لا بسبب خطأ عابر.

فيما يلي ما استخلصته من المنشورين، مُصفّىً عبر الألم الذي عشته في الإنتاج.

مطابقة البادئة تعني أن الترتيب هو كل شيء

يعمل الـ prompt caching في Anthropic API بمطابقة الطلب من بدايته، رمزاً برمز. بمجرد اختلاف حرف واحد عن النسخة المخزنة، يتحول كل ما يليه إلى cache miss. لا مطابقة جزئية، ولا تخطي إلى الأمام.

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

تُكلّف الرموز المخزنة 10% فقط من تكلفة الرموز العادية. هذا الفارق يفسر لماذا يبدو انهيار الـ cache وكأنه مضاعفة عشرية للسعر.

خطئي كان تضمين طابع زمني داخل الـ system prompt. كل طلب يُنتج طابعاً زمنياً جديداً، ما يعني أن أول الرموز يختلف في كل مرة، فلا شيء بعده يستطيع التخزين. سطر debug في المكان الخطأ، وأصبحت أدفع السعر الكامل على أكثر من 100K رمز في الطلب الواحد.

كشف فريق Claude Code أيضاً أن الترتيب غير الحتمي لتعريفات الأدوات يُسبب cache misses. إن كانت أدواتك تُسلسَل بترتيب مختلف بين الطلبات، ينكسر الـ cache عند تلك النقطة حتى لو لم تتغير الأدوات نفسها.

أرسل التحديثات عبر الرسائل، لا بتعديل الـ system prompt

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

يتعامل Claude Code مع هذا بإبقاء الـ system prompt كما هو بعد الطلب الأول. أي سياق متغير يذهب إلى رسالة المستخدم التالية، مُلفوفاً بعلامة system-reminder. يقرأه النموذج بالطريقة ذاتها، لكن البادئة المخزنة تبقى سليمة.

Plan Mode مثال جيد على ذلك. التبديل إلى Plan Mode قد يعني استبدال تعريفات الأدوات، وهو ما سيكسر الـ cache. بدلاً من ذلك، يُنفّذه Claude Code كاستدعاء أداة (EnterPlanMode) يستطيع النموذج استدعاؤها بنفسه. مجموعة الأدوات لا تتغير قط. حين يرصد النموذج مسألة صعبة، يدخل Plan Mode من تلقاء نفسه دون أي تعديل على الـ system prompt.

المنطق ذاته ينطبق على تبديل النماذج. تغيير النموذج في منتصف المحادثة يكسر الـ cache كلياً. يتجنب Claude Code ذلك بتشغيل النماذج المختلفة كعملاء فرعيين في سياقات منفصلة، محافظاً على الـ cache في المحادثة الأم.

أخفِ الأدوات بدلاً من حذفها

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

حل فريق Claude Code: defer_loading. بدلاً من تضمين مخططات الأدوات الكاملة، يُدرجون نسخاً خفيفة تحتوي فقط على اسم الأداة وعلامة defer_loading: true. تبقى هذه النسخ بالترتيب ذاته في كل مرة، محافظةً على البادئة المخزنة كما هي. حين يحتاج النموذج فعلاً إلى مخطط أداة كامل، يستدعي أداة ToolSearch لتحميله عند الطلب.

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

وصف peakji من Manus معدل الـ cache hit rate بأنه المقياس الأكثر حسماً في عملاء الإنتاج. بعد ما عشته أمس، أوافقه تماماً.

لضغط السياق فخ خاص بالـ cache

حين تمتلئ نافذة السياق، تحتاج إلى الضغط: تلخيص المحادثة ومتابعتها في شكل مختصر. المنهج الواضح هو استدعاء الـ API بـ prompt تلخيصي. لكن إن استخدم هذا الاستدعاء system prompt أو تعريفات أدوات مختلفة، فلن يطابق الـ cache الموجود. ستُعالج محادثة بأكملها تتجاوز 100K رمز دون أي استفادة من الـ cache، وتحديداً في اللحظة التي تكون فيها التكاليف في أعلاها.

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

منذ ذلك الحين، دمجت Anthropic هذا النمط في الـ API كميزة ضغط مدمجة. كما أصدروا الـ auto-caching، حيث يتولى وضع cache_control مرة واحدة في جسم الطلب إدارة نقاط كسر الـ cache تلقائياً.

معدل الـ cache hit rate كمقياس تشغيلي

يراقب فريق Claude Code معدل الـ cache hit rate بالطريقة التي تراقب بها فرق العمليات وقت التشغيل. حين ينخفض الرقم، يعاملونه كحادثة طارئة.

هذا التأطير غيّر طريقة تفكيري في تصميم الـ prompt. كل تعديل على الـ system prompt، وكل إعادة ترتيب للأدوات، وكل تبديل للنموذج في منتصف الجلسة، حادثة محتملة. أرخص رمز هو ذاك الذي يُصيب الـ cache، وقد تعلمت بالتجربة المؤلمة كم يكلف البديل.