تفسير كامل لـ TTL التخزين المؤقت للموجه في Claude Code: 5 دقائق مقابل ساعة واحدة، أيهما تختار؟ مع مقارنة فواتير 3 منصات

ملاحظة من المؤلف: شرح مفصل لآلية TTL (زمن البقاء) في ذاكرة التخزين المؤقت للموجهات (Prompt Caching) في Claude Code، الفرق بين خياري 5 دقائق وساعة واحدة، مقارنة تكاليف التخزين المؤقت بين Anthropic API وAWS Bedrock، مع نصائح عملية لتوفير التكاليف.

"هل يمكنني تغيير TTL الخاص بذاكرة التخزين المؤقت للموجهات في Claude Code؟ ما الفرق بين 5 دقائق وساعة واحدة؟ وأيهما أكثر توفيراً؟" — هذه من أكثر الأسئلة شيوعاً بين مستخدمي Claude Code عند محاولتهم التحكم في التكاليف.

الخلاصة أولاً: لا يمكن للمستخدم حالياً تعديل TTL التخزين المؤقت في Claude Code مباشرة، حيث يتم تحديده بناءً على خطة اشتراكك. يحصل مشتركو خطة Max تلقائياً على TTL لمدة ساعة واحدة، بينما يحصل مشتركو خطة Pro ومستخدمو مفتاح API على TTL افتراضي لمدة 5 دقائق. ولكن، إذا كنت تستخدم Claude API مباشرة، يمكنك اختيار 5 دقائق أو ساعة واحدة بحرية عبر معامل cache_control.

القيمة الجوهرية: بعد قراءة هذا المقال، ستفهم تماماً آلية TTL في ذاكرة التخزين المؤقت لـ Claude، وستدرك الفروقات في تكاليف التخزين بين واجهة برمجة تطبيقات Anthropic الرسمية وAWS Bedrock، مما سيمكنك من اختيار استراتيجية التخزين الأكثر توفيراً لحالات استخدامك.

النقاط الجوهرية لآلية التخزين المؤقت (TTL) في Claude

يُعد التخزين المؤقت للموجه (Prompt Caching) أحد أهم آليات توفير التكاليف في نماذج Claude. حيث يقوم بتخزين بادئة الموجه التي أرسلتها مسبقاً (مثل تعليمات النظام، تعريفات الأدوات، وسجل المحادثة) على الخادم، وفي حال كانت البادئة مطابقة في الطلب التالي، يتم قراءتها مباشرة من الذاكرة المؤقتة، مما يجعلك تدفع فقط 10% من سعر الإدخال العادي.

هل يمكن تعديل الـ TTL في Claude Code؟

هذا هو السؤال الأكثر شيوعاً. الإجابة تعتمد على حالتين:

Claude Code (أداة سطر الأوامر التفاعلية): لا يمكن تعديله يدوياً. يتم التحكم في التخزين المؤقت لـ Claude Code من جانب الخادم؛ حيث يحصل مشتركو Max على TTL لمدة ساعة واحدة (عبر ميزة tengu_prompt_cache_1h_config في الخادم)، بينما يحصل مشتركو Pro ومستخدمو مفتاح API على TTL لمدة 5 دقائق. يمكنك فقط إيقاف التخزين المؤقت تماماً عبر متغير البيئة DISABLE_PROMPT_CACHING=1، ولكن لا يمكنك تغيير فئة الـ TTL.

Claude API (الاستدعاء المباشر): يمكنك الاختيار بحرية. عند الاستدعاء عبر API، يمكنك تحديد الـ TTL في معامل cache_control:

// تخزين مؤقت لمدة 5 دقائق (افتراضي)
{ "cache_control": { "type": "ephemeral" } }

// تخزين مؤقت لمدة 1 ساعة
{ "cache_control": { "type": "ephemeral", "ttl": "1h" } }

🎯 نصيحة للاختيار: إذا كنت تستخدم Claude Code CLI، فإن الـ TTL يعتمد على خطة اشتراكك. أما إذا كنت تستخدم استدعاء API (مثل عبر منصة APIYI apiyi.com)، فيمكنك الاختيار بمرونة بين 5 دقائق أو ساعة واحدة بناءً على سيناريو الاستخدام، لتحقيق تحكم أدق في التكاليف.

شرح مفصل لقواعد فوترة التخزين المؤقت للموجه (Prompt Caching) في Claude

5 دقائق مقابل ساعة واحدة: مقارنة التكاليف

يكمن الاختلاف الجوهري بين فترتي الـ TTL (زمن البقاء) في تكلفة الكتابة. أما تكلفة القراءة فهي متطابقة تماماً، حيث تبلغ 0.1 من السعر الأساسي للإدخال:

أسعار التخزين المؤقت للموجه لكل نموذج

فيما يلي جدول فوترة التخزين المؤقت الكامل لنماذج Anthropic عبر API الرسمي (مارس 2026):

اكتشاف رئيسي: الخصم على قراءة التخزين المؤقت مذهل. لنأخذ Claude Opus 4.6 كمثال:

• الإدخال العادي لمليون توكن = $5.00
• قراءة التخزين المؤقت لمليون توكن = $0.50 (توفير $4.50، خصم 90%)
• هذا هو السبب في أن اشتراك Claude Code Pro بقيمة $20 شهرياً يعتبر مجدياً اقتصادياً؛ فبدون التخزين المؤقت قد تكلف 100 جولة محادثة مع Opus ما بين $50-$100، بينما مع التخزين المؤقت تنخفض التكلفة إلى $10-$19 فقط.

الحد الأدنى لعدد التوكنز المطلوب للتخزين المؤقت

لا يمكن تخزين كل المحتوى مؤقتاً. هناك حد أدنى لعدد التوكنز لكل نموذج، وإذا كان المحتوى أقصر من ذلك، فلن يتم تفعيل التخزين المؤقت:

🎯 نصيحة عملية: إذا كان الموجه الخاص بنظامك قصيراً (أقل من 2,048 توكن)، فلن يتم تفعيل التخزين المؤقت عند استخدام Claude Sonnet 4.6. يمكنك الوصول إلى الحد الأدنى عبر إثراء محتوى موجه النظام أو دمج تعريفات الأدوات. عند الاستدعاء عبر خدمة APIYI (apiyi.com)، يتم دعم التخزين المؤقت أيضاً مع أسعار أكثر تنافسية.

Anthropic API مقابل AWS Bedrock: مقارنة فوترة التخزين المؤقت

مقارنة دعم التخزين المؤقت عبر المنصات الثلاث الكبرى

يتم دعم التخزين المؤقت للموجه في Claude عبر كل من API الرسمي لـ Anthropic، وAWS Bedrock، وGoogle Vertex AI، ولكن مع وجود اختلافات في التفاصيل:

توضيح الاختلافات الرئيسية بين المنصات

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

AWS Bedrock: أعلنت في يناير 2026 عن دعم TTL لمدة ساعة واحدة، ولكن يقتصر ذلك على نماذج معينة مثل Claude Opus 4.5 وSonnet 4.5 وHaiku 4.5. بالنسبة لأحدث نماذج Claude Sonnet 4.6 وOpus 4.6، يجب التأكد من دعمها لـ TTL لمدة ساعة على Bedrock. إذا كنت تتصل بـ Bedrock عبر Claude Code، انتبه لإعداد التوافق CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1.

Google Vertex AI: وظائف التخزين المؤقت متطابقة تقريباً مع الـ API الرسمي، ولكنها تتطلب المصادقة والفوترة عبر مشاريع Google Cloud.

🎯 نصيحة لاختيار المنصة: إذا كنت لا ترغب في القلق بشأن اختلافات المنصات وإعدادات التوافق، فإن استخدام واجهة موحدة عبر APIYI (apiyi.com) هو الحل الأبسط؛ حيث يدعم ميزات التخزين المؤقت بالكامل دون الحاجة إلى إعدادات منفصلة لـ AWS IAM أو Google Cloud.

دليل البدء السريع لـ Claude Code Prompt Caching

مثال مبسط: إعداد ذاكرة تخزين مؤقت بمدة TTL قدرها ساعة واحدة

import anthropic

client = anthropic.Anthropic(
    api_key="YOUR_API_KEY",
    base_url="https://vip.apiyi.com/v1"
)

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    system=[{
        "type": "text",
        "text": "أنت مساعد مدرس فيزياء محترف، مسؤول عن الإجابة على أسئلة الفيزياء للمرحلة الثانوية...(هنا موجه نظام طويل)",
        "cache_control": {"type": "ephemeral", "ttl": "1h"}
    }],
    messages=[{"role": "user", "content": "اشرح قانون نيوتن الثالث"}]
)
print(f"رموز قراءة الذاكرة المؤقتة: {response.usage.cache_read_input_tokens}")
print(f"رموز كتابة الذاكرة المؤقتة: {response.usage.cache_creation_input_tokens}")

import anthropic

client = anthropic.Anthropic(
    api_key="YOUR_API_KEY",
    base_url="https://vip.apiyi.com/v1"
)

# TTL مختلط: موجه النظام لمدة ساعة (لا يتغير كثيراً)، سياق المحادثة لمدة 5 دقائق (يتغير بشكل متكرر)
response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=2048,
    system=[
        {
            "type": "text",
            "text": "أنت مستشار تقني محترف في مجال الذكاء الاصطناعي...(موجه نظام طويل، أكثر من 2000 رمز)",
            "cache_control": {"type": "ephemeral", "ttl": "1h"}  # موجه النظام لمدة ساعة
        },
        {
            "type": "text",
            "text": "فيما يلي سياق المحادثة السابقة للمستخدم...(سجل المحادثة)",
            "cache_control": {"type": "ephemeral"}  # سياق المحادثة لمدة 5 دقائق (افتراضي)
        }
    ],
    messages=[{"role": "user", "content": "قارن بين قدرات الاستنتاج لدى Claude و GPT"}]
)

# عرض حالة استخدام الذاكرة المؤقتة
usage = response.usage
print(f"رموز الإدخال العادية: {usage.input_tokens}")
print(f"رموز قراءة الذاكرة المؤقتة: {usage.cache_read_input_tokens}")
print(f"رموز كتابة الذاكرة المؤقتة: {usage.cache_creation_input_tokens}")

# حساب التوفير (باستخدام Sonnet 4.6 كمثال)
base_cost = (usage.input_tokens / 1_000_000) * 3
cache_cost = (usage.cache_read_input_tokens / 1_000_000) * 0.3
saved = (usage.cache_read_input_tokens / 1_000_000) * 2.7
print(f"التوفير في هذه العملية: ${saved:.4f}")

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

نصيحة: عند استدعاء Claude API عبر خدمة وكيل API الخاص بـ APIYI (apiyi.com)، يتم دعم معامل cache_control بالكامل، مما يتيح لك حرية الاختيار بين TTL لمدة 5 دقائق أو ساعة واحدة.

TTL لمدة 5 دقائق مقابل ساعة واحدة: أيهما تختار؟

جدول اتخاذ القرار

معادلة حساب التكلفة

لتحديد ما إذا كانت الذاكرة المؤقتة مجدية، استخدم المعادلة الأساسية:

شرط استرداد تكلفة TTL لمدة 5 دقائق: قراءة المحتوى مرة واحدة على الأقل خلال 5 دقائق

• تكلفة الكتابة: 1.25 ضعف → زيادة 0.25 ضعف
• توفير القراءة: توفير 0.9 ضعف في كل مرة
• قراءة واحدة تكفي لاسترداد التكلفة (0.9 > 0.25)

شرط استرداد تكلفة TTL لمدة ساعة واحدة: قراءة المحتوى مرتين على الأقل خلال ساعة

• تكلفة الكتابة: 2.0 ضعف → زيادة 1.0 ضعف
• توفير القراءة: توفير 0.9 ضعف في كل مرة
• قراءتان لاسترداد التكلفة (0.9 × 2 = 1.8 > 1.0)

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

ملخص

النقاط الجوهرية حول ذاكرة التخزين المؤقت (TTL) في Claude Prompt:

1. خياران لـ TTL: 5 دقائق (تكلفة كتابة 1.25 ضعف، استرداد التكلفة بعد قراءة واحدة) وساعة واحدة (تكلفة كتابة 2 ضعف، استرداد التكلفة بعد قراءتين)، بينما تظل تكلفة القراءة 0.1 ضعف.
2. لا يمكن تغيير TTL في Claude Code CLI: يحصل مشتركو Max على ساعة واحدة تلقائيًا، بينما يظل مستخدمو Pro/مفتاح API ثابتين على 5 دقائق، ولا يمكن التبديل بينهما.
3. حرية الاختيار عبر Claude API: يمكنك ضبط TTL عبر معامل cache_control.ttl، ويمكنك حتى دمج نوعي TTL في نفس الطلب.
4. اختر 5 دقائق للمحادثات عالية التردد: يتم تجديد الذاكرة تلقائيًا عند كل وصول، مما يقلل تكاليف الكتابة. اختر ساعة واحدة للاستخدام المتقطع لتجنب انتهاء الصلاحية.

الوصول إلى ذاكرة التخزين المؤقت (Cache Hit) يعني خفض تكلفة الإدخال بنسبة 90%، وهي آلية توفير التكاليف الأساسية في Claude. نوصي باستخدام APIYI (apiyi.com) للوصول الموحد، حيث يوفر دعمًا كاملاً لإعدادات ذاكرة التخزين المؤقت، مما يتيح لك اختبار فروق التكلفة الفعلية لاستراتيجيات TTL المختلفة باستخدام مفتاح واحد فقط.

📚 المراجع

1. وثائق Anthropic الرسمية – التخزين المؤقت للموجه (Prompt Caching): المصدر الموثوق لإعدادات TTL، وقواعد الفوترة، وصيغة cache_control.

   • الرابط: platform.claude.com/docs/en/build-with-claude/prompt-caching
   • الوصف: معادلات الفوترة الكاملة وأمثلة برمجية لـ TTL لمدة 5 دقائق/ساعة واحدة.

2. وثائق Anthropic الرسمية – التسعير: الأسعار الأساسية وأسعار التخزين المؤقت لجميع النماذج.

   • الرابط: platform.claude.com/docs/en/about-claude/pricing
   • الوصف: معدلات رسوم الكتابة والقراءة للتخزين المؤقت لنماذج Opus/Sonnet/Haiku.

3. وثائق AWS الرسمية – التخزين المؤقت للموجه في Bedrock: تفاصيل دعم التخزين المؤقت على منصة Bedrock.

   • الرابط: docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html
   • الوصف: نطاقات دعم TTL ومعايير الفوترة للنماذج المختلفة على Bedrock.

4. Claude Code Camp – آلية عمل التخزين المؤقت للموجه: تحليل معمق لكيفية تنفيذ التخزين المؤقت في Claude Code.

   • الرابط: claudecodecamp.com/p/how-prompt-caching-actually-works-in-claude-code
   • الوصف: تعرف على كيفية إدارة Claude Code لنقاط التوقف (breakpoints) في التخزين المؤقت تلقائيًا.

5. GitHub Issue #19436 – طلب ميزة التخزين المؤقت متعدد الطبقات TTL: نقاشات المجتمع حول إعدادات TTL أكثر مرونة.

   • الرابط: github.com/anthropics/claude-code/issues/19436
   • الوصف: مقترحات المجتمع لحلول TTL متعددة الطبقات بناءً على وتيرة تغير المحتوى.

المؤلف: فريق APIYI التقني
التواصل التقني: نرحب بمناقشة تجاربكم في إعداد التخزين المؤقت لـ Claude في قسم التعليقات، ولمزيد من دروس استدعاء النموذج يمكنكم زيارة مركز توثيق APIYI عبر الرابط docs.apiyi.com.