إتقان 3 نقاط رئيسية لفوترة التخزين المؤقت في Claude: لماذا يجب الاستدعاء بتنسيق Anthropic الأصلي

يواجه العديد من المطورين عند استخدام Claude API حيرةً كبيرة: لماذا لا تظهر خصومات التخزين المؤقت (Prompt Caching) في الفاتورة رغم تفعيلها؟

الإجابة غالباً ما تكون بسيطة للغاية – أنت تستخدم وضع التوافق مع OpenAI في استدعاء النموذج، بينما فوترة التخزين المؤقت في Claude لا تدعم سوى تنسيق Anthropic Messages API الأصلي.

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

المبادئ الأساسية لآلية التخزين المؤقت (Prompt Caching) في Claude

قبل التعمق في اختلافات تنسيق الاستدعاء، دعنا نفهم أولاً كيف تعمل آلية التخزين المؤقت للموجهات (Prompt Caching) في Claude.

كيف يعمل التخزين المؤقت في Claude

عندما ترسل طلباً مفعلاً فيه خاصية التخزين المؤقت للموجه، يتبع النظام الخطوات التالية:

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

المحتوى الذي يدعمه التخزين المؤقت في Claude

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

• الأدوات (Tools): تعريفات الأدوات في مصفوفة tools.
• رسائل النظام (System messages): كتل المحتوى في مصفوفة system.
• الرسائل النصية (Text messages): كتل المحتوى النصي في مصفوفة messages.content.
• الصور والمستندات (Images & Documents): الصور والمستندات الموجودة في رسائل المستخدم.
• استخدام الأدوات ونتائجها (Tool use & tool results): كتل المحتوى الخاصة باستدعاء الأدوات ونتائجها.

🎯 نصيحة تقنية: بالنسبة للسيناريوهات التي تتطلب استدعاء نفس موجهات النظام بشكل متكرر، يعد التخزين المؤقت للموجهات (prompt caching) أكثر الوسائل فعالية لتحسين التكلفة. نوصي باستخدام تنسيق Anthropic الأصلي لاستدعاء Claude API عبر منصة APIYI (apiyi.com) للاستفادة الكاملة من خصومات التخزين المؤقت.

تنسيق Anthropic الأصلي مقابل وضع توافق OpenAI: الاختلافات في دعم التخزين المؤقت لـ Claude

هذا هو الجزء الأهم في المقال — الاختلافات الجوهرية بين تنسيقي الاستدعاء فيما يتعلق بميزة التخزين المؤقت في Claude.

تصريح رسمي من Anthropic

وفقاً لوثائق توافق Anthropic الرسمية مع OpenAI SDK:

"التخزين المؤقت للموجهات (Prompt caching) غير مدعوم، ولكنه مدعوم في Anthropic SDK"

هذا يعني أنه إذا قمت باستدعاء Claude عبر وضع توافق OpenAI (نقطة النهاية /v1/chat/completions)، فلن تتمكن من استخدام ميزة التخزين المؤقت للموجهات على الإطلاق.

مقارنة الميزات بين تنسيقي استدعاء Claude API

لماذا لا يدعم وضع توافق OpenAI التخزين المؤقت في Claude

تم تصميم وضع توافق OpenAI لاختبار ومقارنة قدرات النماذج، وليس للاستخدام في بيئات الإنتاج:

1. اختلاف البروتوكول: معلمة cache_control هي حقل أصلي في Anthropic Messages API، ولا يوجد حقل مقابل لها في تنسيق OpenAI chat completions.
2. قيود البنية التحتية: تحتاج طبقة التوافق إلى تحويل تنسيق OpenAI إلى تنسيق Anthropic، وخلال عملية التحويل هذه، تُفقد معلومات التحكم في التخزين المؤقت.
3. اعتبارات الأولوية: صرحت Anthropic رسمياً بأن أولوية طبقة التوافق أقل من موثوقية واكتمال ميزات Claude API الأصلية.

💡 ملاحظة هامة: إذا كان عملك يعتمد على التخزين المؤقت للموجهات للتحكم في التكاليف، فيجب عليك استخدام تنسيق Anthropic Messages API الأصلي، وليس وضع توافق OpenAI.

تفاصيل تسعير تخزين الموجهات المؤقت (Prompt Caching) في Claude: وفر حتى 90% من التكلفة

يعد هيكل تسعير تخزين الموجهات المؤقت في Claude هو أكثر ميزاته جاذبية، حيث يبلغ سعر قراءة "إصابة التخزين المؤقت" (Cache Hit) 10% فقط من سعر الإدخال الأساسي.

مقارنة أسعار التخزين المؤقت لجميع نماذج Claude

MTok = مليون توكن. مصدر البيانات: صفحة تسعير Anthropic الرسمية (فبراير 2026)

قواعد حساب تسعير التخزين المؤقت في Claude

يتبع تسعير التخزين المؤقت 3 قواعد مضاعفة بسيطة:

• كتابة التخزين المؤقت لمدة 5 دقائق: سعر الإدخال الأساسي × 1.25
• كتابة التخزين المؤقت لمدة ساعة واحدة: سعر الإدخال الأساسي × 2.0
• قراءة التخزين المؤقت (إصابة): سعر الإدخال الأساسي × 0.1

لنأخذ نموذج Claude Sonnet 4.6 كمثال، بافتراض أن لديك موجه نظام (System Prompt) يتكون من 100 ألف توكن:

💰 تحسين التكلفة: بالنسبة للسيناريوهات التي تعيد استخدام نفس الـ system prompt، يمكنك الاستفادة الكاملة من ميزة prompt caching لتحقيق توفير يصل إلى 90% من التكلفة من خلال استدعاء Claude API بتنسيق Anthropic الأصلي عبر منصة APIYI (apiyi.com).

كود عملي لتخزين الموجهات المؤقت في Claude: الاستدعاء بتنسيق Anthropic الأصلي

فيما يلي أمثلة برمجية توضح كيفية تفعيل ميزة prompt caching في Claude بشكل صحيح.

مثال استدعاء أساسي: تنسيق Anthropic الأصلي + التفكير الممتد (Extended Thinking)

curl https://api.apiyi.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 16000,
    "stream": false,
    "thinking": {
      "type": "enabled",
      "budget_tokens": 10000
    },
    "messages": [
      {
        "role": "user",
        "content": "ما ناتج ضرب 27 في 453؟"
      }
    ]
  }'

المثال أعلاه هو استدعاء أساسي بتنسيق Anthropic الأصلي، مع استخدام ميزة التفكير الممتد (Extended Thinking). لنرى الآن كيفية تفعيل prompt caching بناءً على ذلك.

وضع التخزين المؤقت التلقائي: أسهل طريقة لتفعيل التخزين المؤقت في Claude

يعد التخزين المؤقت التلقائي أسهل طريقة لتفعيل prompt caching في Claude – ما عليك سوى إضافة حقل cache_control في المستوى الأعلى من جسم الطلب:

curl https://api.apiyi.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "cache_control": {"type": "ephemeral"},
    "system": "أنت مساعد مستندات تقنية محترف، تساعد المستخدمين على فهم كيفية استخدام نماذج الذكاء الاصطناعي وأفضل الممارسات. يجب أن تكون إجاباتك دقيقة وموجزة وعملية.",
    "messages": [
      {"role": "user", "content": "ما هي الميزات الرئيسية لـ Claude Sonnet 4.6؟"},
      {"role": "assistant", "content": "Claude Sonnet 4.6 هو نموذج عالي الأداء أطلقته شركة Anthropic..."},
      {"role": "user", "content": "ما هو حجم نافذة السياق الخاصة به؟"}
    ]
  }'

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

وضع التخزين المؤقت الصريح: تحكم دقيق في محتوى التخزين المؤقت لـ Claude

للحالات التي تتطلب تحكماً دقيقاً في سلوك التخزين المؤقت، يمكنك وضع cache_control على كتل محتوى محددة:

curl https://api.apiyi.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "system": [
      {
        "type": "text",
        "text": "أنت مساعد تحليل مستندات قانونية، بارع في تحليل بنود العقود والمخاطر القانونية."
      },
      {
        "type": "text",
        "text": "[ضع هنا النص الكامل لعقد قانوني مكون من 50 صفحة... محتوى يبلغ حوالي 100 ألف توكن]",
        "cache_control": {"type": "ephemeral"}
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "يرجى تحليل البنود الرئيسية والمخاطر المحتملة في هذا العقد."
      }
    ]
  }'

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

تخزين مؤقت طويل الأمد لمدة ساعة: تمديد مدة التخزين المؤقت في Claude

إذا كانت مدة التخزين المؤقت الافتراضية (5 دقائق) غير كافية، يمكنك اختيار التخزين المؤقت لمدة ساعة واحدة:

"cache_control": {"type": "ephemeral", "ttl": "1h"}

يعد التخزين المؤقت لمدة ساعة مناسباً لـ:

• المهام الطويلة في سير عمل الوكيل (Agent) (أكثر من 5 دقائق).
• الحالات التي قد تتجاوز فيها الفواصل الزمنية بين محادثات المستخدم 5 دقائق.
• الحالات التي تتطلب استفادة أعلى من حدود معدل الاستخدام (Rate Limit)، حيث أن إصابات التخزين المؤقت لا تُخصم من حدود معدل الاستخدام.

🚀 ابدأ الآن: نوصي باستخدام منصة APIYI (apiyi.com) لاختبار ميزة prompt caching في Claude بسرعة. تدعم المنصة بشكل كامل تنسيق Anthropic Messages API الأصلي، بما في ذلك معامل cache_control؛ يمكنك إتمام عملية التحقق من التكامل في 5 دقائق فقط.

مراقبة أداء التخزين المؤقت (Prompt Caching) في Claude وتصحيح أخطائه

بعد تفعيل التخزين المؤقت، ستحتاج إلى مراقبة فعالية التخزين من خلال حقل usage في استجابة API.

الحقول الرئيسية في استجابة التخزين المؤقت لـ Claude

{
  "usage": {
    "input_tokens": 50,
    "cache_creation_input_tokens": 100000,
    "cache_read_input_tokens": 0,
    "output_tokens": 500
  }
}

معادلة حساب إجمالي رموز الإدخال:

total_input = cache_read_input_tokens + cache_creation_input_tokens + input_tokens

استكشاف الأخطاء وإصلاحها: الأسباب الشائعة لعدم نجاح التخزين المؤقت (Cache Miss)

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

1. خطأ في تنسيق الاستدعاء: استخدام وضع التوافق مع OpenAI بدلاً من تنسيق Anthropic الأصلي.
2. عدم تطابق المحتوى: يتطلب مطابقة التخزين المؤقت تطابقاً تاماً بنسبة 100% لبادئة الموجه (prompt prefix).
3. نقص الرموز (Tokens): لم يتم الوصول إلى الحد الأدنى لعدد رموز التخزين المؤقت المطلوب للنموذج.
4. انتهاء الصلاحية: مرور أكثر من 5 دقائق دون استخدام، مما يؤدي إلى انتهاء صلاحية التخزين المؤقت.
5. تغيير المعلمات: تعديل tool_choice أو محتوى الصور أو معلمات التفكير (thinking).

الحد الأدنى لمتطلبات رموز التخزين المؤقت لكل نموذج من نماذج Claude

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

🎯 نصيحة للتصحيح: عند استدعاء Claude API عبر منصة APIYI (apiyi.com)، يمكنك التحقق بسرعة مما إذا كان التخزين المؤقت يعمل من خلال حقل usage في الاستجابة. إذا كانت قيمة cache_read_input_tokens هي 0 و cache_creation_input_tokens هي 0 أيضاً، فهذا يعني أن ميزة التخزين المؤقت لم يتم تفعيلها بشكل صحيح.

الأسئلة الشائعة حول التخزين المؤقت للموجهات (Claude Prompt Caching) FAQ

س1: هل يمكن استخدام التخزين المؤقت عند استدعاء Claude في وضع التوافق مع OpenAI؟

لا. هذا قيد صرحت به Anthropic رسميًا. وضع التوافق مع OpenAI (نقطة النهاية /v1/chat/completions) لا يدعم ميزة prompt caching. يجب عليك استخدام تنسيق Anthropic Messages API الأصلي (نقطة النهاية /v1/messages) لتتمكن من استخدام ميزة التخزين المؤقت.

من خلال منصة APIYI (apiyi.com)، يمكنك استدعاء Claude API بكلا التنسيقين في آن واحد؛ فإذا كنت بحاجة لميزة التخزين المؤقت، ما عليك سوى اختيار نقطة النهاية /v1/messages.

س2: كتابة التخزين المؤقت في Claude أغلى من الإدخال العادي، فهل لا يزال الأمر يستحق الاستخدام؟

يستحق ذلك تمامًا. كتابة التخزين المؤقت أغلى بنسبة 25% فقط من الإدخال الأساسي (مع TTL لمدة 5 دقائق)، لكن إصابة التخزين المؤقت (Cache Hit) تكلف 10% فقط من السعر. طالما يتم استخدام نفس المحتوى أكثر من مرتين، فستسترد التكلفة وتبدأ في توفير المال. لنأخذ مثالاً على موجه نظام (system prompt) بحجم 100 ألف توكن:

• بدون تخزين مؤقت: 0.30 دولار لكل مرة (Sonnet 4.6)
• كتابة التخزين المؤقت: 0.375 دولار (للمرة الأولى فقط)
• قراءة التخزين المؤقت: 0.03 دولار (لكل مرة لاحقة)
• ستبدأ في توفير المال ابتداءً من الاستدعاء الثاني.

س3: كيف يمكن الانتقال من تنسيق OpenAI إلى تنسيق Anthropic الأصلي في الكود؟

نقاط التغيير الرئيسية هي:

• نقطة النهاية: /v1/chat/completions ← /v1/messages
• رؤوس الطلب (Headers): إضافة anthropic-version: 2023-06-01
• تنسيق الرسائل: هيكل مصفوفة messages متطابق تقريبًا
• موجه النظام (System prompt): يتم استخراجه من messages إلى حقل system مستقل
• إضافة معامل cache_control

تدعم منصة APIYI (apiyi.com) كلا النقطتين، وعند الانتقال تحتاج فقط لتعديل مسار الطلب وتنسيقه، دون الحاجة لتغيير مفتاح API.

س4: هل يمكن مشاركة التخزين المؤقت لـ Claude عبر الطلبات المختلفة؟

يتم مشاركة التخزين المؤقت داخل نفس مساحة العمل (Workspace) (اعتبارًا من 5 فبراير 2026، تم تغيير العزل من مستوى المؤسسة إلى مستوى مساحة العمل). لا يتم مشاركة التخزين المؤقت أبدًا بين المؤسسات المختلفة.

س5: هل يمكن استخدام التخزين المؤقت و Batch API معًا؟

نعم، يمكن ذلك. توفر Batch API خصمًا بنسبة 50%، ويتم تطبيق مضاعفات تسعير التخزين المؤقت فوق ذلك. الجمع بينهما يحقق أقصى تحسين للتكلفة. يُنصح باستخدام TTL للتخزين المؤقت لمدة ساعة واحدة في سيناريوهات المعالجة الجماعية لزيادة معدل الإصابة.

ملخص: 3 نقاط محورية حول تسعير التخزين المؤقت في Claude

من خلال تحليلنا في هذا المقال، إليك 3 نقاط رئيسية يجب تذكرها حول تسعير prompt caching في Claude:

1. يدعم تنسيق Anthropic الأصلي فقط: ميزة التخزين المؤقت متاحة فقط في نقطة النهاية /v1/messages؛ وضع التوافق مع OpenAI (/v1/chat/completions) لا يدعمها.
2. تكلفة إصابة التخزين المؤقت 10% فقط: تدفع 25% إضافية عند الكتابة لأول مرة، ولكن كل إصابة لاحقة تكلف عُشر السعر الأساسي فقط، مما يعني استرداد التكلفة في استدعاءين فقط.
3. طريقة الاستدعاء الصحيحة هي المفتاح: استخدم معامل cache_control: {"type": "ephemeral"} لضمان استيفاء الحد الأدنى من التوكنات المطلوبة للتخزين المؤقت للنموذج.

نوصي بتجربة الوظائف الكاملة لـ Claude prompt caching عبر منصة APIYI (apiyi.com). تدعم المنصة بشكل كامل واجهة Anthropic Messages API الأصلية، مما يساعدك على استخدام نماذج Claude بأفضل تكلفة ممكنة.

المراجع

1. وثائق Anthropic الرسمية حول Prompt Caching: شرح مفصل لميزة التخزين المؤقت في واجهة برمجة تطبيقات Claude

   • الرابط: platform.claude.com/docs/en/build-with-claude/prompt-caching

2. صفحة التسعير الرسمية لشركة Anthropic: تسعير نماذج Claude والتخزين المؤقت

   • الرابط: platform.claude.com/docs/en/about-claude/pricing

3. وثائق توافق OpenAI SDK: شرح قيود ميزات وضع التوافق

   • الرابط: platform.claude.com/docs/en/api/openai-sdk

📝 المؤلف: فريق APIYI | الفريق التقني لـ APIYI، متخصصون في دمج واجهات برمجة تطبيقات نماذج اللغة الكبيرة ومشاركة الخبرات التقنية. تفضل بزيارة apiyi.com للحصول على المزيد من الشروحات التقنية.