Prompt Caching

قلّل تكاليف وزمن استجابة Venice API بتخزين محتوى prompt المتكرر مثل system prompts وسجل المحادثة وسياق المستندات عبر الطلبات.

يخزّن prompt caching الـ input tokens المعالجة بحيث يمكن للطلبات اللاحقة ذات البادئات المتطابقة إعادة استخدامها بدلًا من إعادة معالجتها. هذا يقلل من زمن الاستجابة (حتى 80% للـ prompts الطويلة) والتكاليف (خصم يصل إلى 90% على الـ tokens المُخزَّنة).

تتعامل Venice مع التخزين المؤقت تلقائيًا للنماذج المدعومة، لكن فهم كيفية تنفيذ كل مزود للتخزين المؤقت يساعدك على زيادة معدلات إصابات الذاكرة المؤقتة وتقليل التكاليف.

​

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

يعمل التخزين المؤقت على مطابقة البادئات: يخزن النظام الـ tokens المعالجة ويعيد استخدامها عندما تبدأ الطلبات اللاحقة بنفس المحتوى.

ضع في اعتبارك chatbot بـ system prompt مكون من 2,000 token:

1. الطلب 1

   System prompt (2,000 token) + رسالة المستخدم (50 token)

   معالجة: 2,050 token · من الذاكرة المؤقتة: 0 token

   البادئة مكتوبة في الذاكرة المؤقتة.

2. الطلب 2

   System prompt (2,000 token) + رسالة المستخدم (80 token)

   معالجة: 80 token · من الذاكرة المؤقتة: 2,000 token

3. الطلب 3

   System prompt (2,000 token) + رسالة المستخدم (120 token)

   معالجة: 120 token · من الذاكرة المؤقتة: 2,000 token

الإجمالي بدون تخزين مؤقت: 2,050 + 2,080 + 2,120 = 6,250 token بالسعر الكامل

الإجمالي مع التخزين المؤقت: 2,050 + 80 + 120 = 2,250 token بالسعر الكامل، و 4,000 token بسعر مخفض

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

​

النماذج المدعومة والتسعير

Loading…

يفرض Claude Opus 4.5 سعرًا مميزًا لكتابات الذاكرة المؤقتة ($7.50/1M token مقابل $6.00 للإدخال العادي). الطلب الأول الذي يملأ الذاكرة المؤقتة يكلف أكثر، لكن إصابات الذاكرة المؤقتة اللاحقة توفر 90%. النماذج الأخرى لا تفرض رسومًا إضافية لكتابات الذاكرة المؤقتة.

​

السلوك الخاص بكل مزود

تُطبّع Venice التخزين المؤقت عبر المزودين. بالنسبة لمعظم النماذج، التخزين المؤقت تلقائي. فقط أرسل طلباتك وتحقق من الاستجابة للحصول على إحصائيات الذاكرة المؤقتة. يتطلب Claude علامات ذاكرة مؤقتة صريحة على مستوى البروتوكول، لكن Venice يضيفها تلقائيًا لـ system prompts وتاريخ المحادثة.

سلوك التخزين المؤقت يتم التحكم فيه في النهاية من قبل كل مزود وقد يتغير، لذا تحقق من مستندات المزود للحصول على آخر التفاصيل.

النموذج	المزود	الحد الأدنى للـ Tokens	عمر الذاكرة المؤقتة	تكلفة الكتابة	خصم القراءة	علامات صريحة
Claude Opus 4.5	Anthropic	~4,000	5 دقائق	+25%	90%	مطلوبة
GPT-5.2	OpenAI	1,024	5-10 دقائق	لا شيء	90%	غير مطلوبة
Gemini	Google	~1,024	ساعة واحدة	لا شيء	75-90%	غير مطلوبة
Grok	xAI	~1,024	5 دقائق	لا شيء	75-88%	غير مطلوبة
DeepSeek	DeepSeek	~1,024	5 دقائق	لا شيء	50%	غير مطلوبة
MiniMax	MiniMax	~1,024	5 دقائق	لا شيء	90%	غير مطلوبة
Kimi	Moonshot	~1,024	5 دقائق	لا شيء	50%	غير مطلوبة

​

Claude Opus 4.5 (Anthropic)

يتطلب Claude نقاط فاصلة صريحة للذاكرة المؤقتة على مستوى البروتوكول. تتعامل Venice مع هذا تلقائيًا:

• يتم تخزين System prompts تلقائيًا
• يتم تخزين تاريخ المحادثة بوضع نقطة فاصلة على رسالة المستخدم قبل الأخيرة

هذا يعني أن تاريخ المحادثة الخاص بك يُقرأ من الذاكرة المؤقتة، ويتم معالجة آخر دور فقط كإدخال جديد:

الدور	Prompt Tokens	قراءة الذاكرة المؤقتة	كتابة الذاكرة المؤقتة	التوفير
1	10,979	0	10,938	أول كتابة
2	11,031	10,938	31	99.7% مخزَّن
3	11,062	10,969	52	99.5% مخزَّن

تفاصيل إضافية:

• حتى 4 نقاط فاصلة لكل طلب: يستخدم النظام أطول بادئة متطابقة
• مفتاح الذاكرة المؤقتة دقيق بايتيًا: تغييرات المسافات البيضاء، أو ترميزات الصور المختلفة، أو إعادة ترتيب الأدوات يكسر إصابات الذاكرة المؤقتة
• حدود معدلات تراعي الذاكرة المؤقتة: الـ tokens المخزَّنة لا تحتسب ضد حد ITPM الخاص بك، مما يتيح إنتاجية فعالة أعلى
• علاوة كتابة 25%: الطلب الأول يكلف أكثر، لكن توفير 90% على القراءات اللاحقة

​

التحكم اليدوي بالذاكرة المؤقتة

للحالات الخاصة مثل تخزين مستند كبير في الدور الأول، يمكنك إضافة نقاط فاصلة صريحة:

{
  "messages": [
    {
      "role": "system",
      "content": [{
        "type": "text",
        "text": "You are a legal assistant...",
        "cache_control": { "type": "ephemeral" }
      }]
    },
    {
      "role": "user", 
      "content": [{
        "type": "text",
        "text": "[Long contract document...]",
        "cache_control": { "type": "ephemeral" }
      }]
    },
    { "role": "assistant", "content": "I've reviewed the contract." },
    { "role": "user", "content": "What are the termination clauses?" }
  ]
}

هذا يضمن تخزين كل من system prompt والمستند من الطلب الأول. للمحادثات النموذجية، لا تحتاج إلى علامات يدوية.

​

جميع النماذج الأخرى

التخزين المؤقت تلقائي. لا حاجة لمعاملات خاصة. فقط تأكد من أن الـ prompts تتجاوز ~1,024 token واستخدم prompt_cache_key للتوجيه المتسق.

​

معاملات الطلب

المعامل	النوع	النماذج	الوصف
prompt_cache_key	string	الكل	تلميح توجيه لتقارب الذاكرة المؤقتة. الطلبات بنفس المفتاح من المرجح أكثر أن تصيب نفس الخادم بذاكرة مؤقتة دافئة.
cache_control	object	Claude	تحدد كتل المحتوى للتخزين المؤقت. انظر قسم Claude Opus 4.5.

​

prompt_cache_key

للمحادثات أو سير عمل الوكلاء، استخدم prompt_cache_key متسق لتحسين معدلات إصابات الذاكرة المؤقتة:

{
  "model": "claude-opus-4-5",
  "prompt_cache_key": "session-abc-123",
  "messages": [...]
}

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

​

حقول الاستجابة

يتضمن كائن usage في الاستجابة إحصائيات الذاكرة المؤقتة:

{
  "usage": {
    "prompt_tokens": 5500,
    "completion_tokens": 200,
    "total_tokens": 5700,
    "prompt_tokens_details": {
      "cached_tokens": 5000,
      "cache_creation_input_tokens": 0
    }
  }
}

الحقل	الوصف
prompt_tokens	إجمالي input tokens في الطلب
prompt_tokens_details.cached_tokens	Tokens المقدَّمة من الذاكرة المؤقتة (تُفوتر بسعر مخفض)
prompt_tokens_details.cache_creation_input_tokens	Tokens المكتوبة في الذاكرة المؤقتة (قد تتكبد علاوة على Claude)

تفصيل الفوترة (باستخدام Claude Opus 4.5 كمثال):

• 5000 token مخزَّن × $0.60/1M = $0.003
• 500 token غير مخزَّن × $6.00/1M = $0.003
• الإجمالي: $0.006 (مقابل $0.033 بدون تخزين مؤقت، توفير 82%)

​

أفضل الممارسات

​

هيكلة الـ prompts للتخزين المؤقت

ضع المحتوى الثابت في البداية، والمحتوى الديناميكي في النهاية.

هيكلة جيدة

الموضع	المحتوى	مخزَّن؟
1	تعليمات النظام	نعم
2	المستندات المرجعية	نعم
3	أمثلة Few-shot	نعم
4	استعلام المستخدم	لا

هيكلة سيئة

الموضع	المحتوى	مخزَّن؟
1	الطابع الزمني الحالي	لا (يبطل كل شيء بعده)
2	تعليمات النظام	لا
3	استعلام المستخدم	لا

​

حافظ على البادئات متطابقة بايتيًا

تُحسب مفاتيح الذاكرة المؤقتة من تسلسلات بايتات دقيقة. حتى الاختلافات التافهة تكسر إصابات الذاكرة المؤقتة:

• مسافات بيضاء أو أسطر جديدة مختلفة
• طوابع زمنية أو معرفات طلب في الـ prompts
• ترتيب عشوائي لأمثلة few-shot
• تنسيقات مختلفة لنفس المحتوى

​

اجتز عتبات الحد الأدنى من الـ tokens

إذا كانت prompts أقل من الحد الأدنى (عادةً 1,024 token)، فلن يتم تنشيط التخزين المؤقت. للـ prompts الصغيرة، فكر في:

• إضافة المزيد من السياق أو الأمثلة للوصول إلى العتبة
• تجميع طلبات صغيرة متعددة في prompts مجمعة
• قبول أن التخزين المؤقت لن يطبَّق للاستعلامات البسيطة

​

استخدم prompt_cache_key للمحادثات

للمحادثات الجارية، عيّن prompt_cache_key متسق:

// الدور 1
{ "prompt_cache_key": "conv-xyz", "messages": [...] }

// الدور 2
{ "prompt_cache_key": "conv-xyz", "messages": [...] }

// الدور 3
{ "prompt_cache_key": "conv-xyz", "messages": [...] }

هذا يحسن احتمال أن جميع الأدوار تصيب نفس الخادم بذاكرة مؤقتة دافئة.

​

راقب أداء الذاكرة المؤقتة

تتبع هذه المقاييس:

• معدل إصابة الذاكرة المؤقتة: cached_tokens / prompt_tokens
• توفير التكلفة: قارن التكلفة الفعلية بالتكلفة دون تخزين مؤقت
• تقليل زمن الاستجابة: الوقت حتى أول token مع إصابات الذاكرة المؤقتة مقابل بدونها

إذا كان cached_tokens صفرًا باستمرار:

1. قد تكون الـ prompts أقل من الحد الأدنى لعدد الـ tokens
2. قد تتغير الـ prompts بين الطلبات
3. قد تصيب الطلبات خوادم مختلفة (استخدم prompt_cache_key)
4. قد تكون الذاكرة المؤقتة قد انتهت صلاحيتها (الطلبات نادرة جدًا)

​

ضع في الاعتبار اقتصاديات الذاكرة المؤقتة

علاوة كتابة الذاكرة المؤقتة لـ Claude Opus 4.5: الطلب الأول يكلف 25% أكثر، لكن توفير 90% على القراءات اللاحقة.

السيناريو	هل تستحق علاوة كتابة الذاكرة المؤقتة؟
طلب واحد بهذا الـ prompt	لا (تدفع 25% أكثر، بدون فائدة)
2+ طلبات بنفس البادئة	نعم (التعادل عند الطلب الثاني)
Prompts تتغير بسرعة	لا (تكاليف كتابة ثابتة)
system prompt مستقر، استعلامات كثيرة	نعم (مُستهلَك عبر قراءات كثيرة)

​

عمر الذاكرة المؤقتة

تنتهي صلاحية الذاكرات المؤقتة بعد فترة من عدم النشاط (عادةً 5-10 دقائق). هذا يعني:

نمط حركة المرور	فائدة التخزين المؤقت
طلبات مستمرة (< 5 دقائق فجوات)	عالية: الذاكرة المؤقتة تبقى دافئة
حركة مرور متقطعة (فجوات > 10 دقائق)	محدودة: الذاكرة المؤقتة تنتهي بين الموجات
طلبات متفرقة (ساعات بينها)	لا شيء: الذاكرة المؤقتة دائمًا باردة

​

التخزين المؤقت مع الأدوات والوظائف

يمكن تخزين تعريفات الوظائف مع system prompts:

{
  "model": "claude-opus-4-5",
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "search_database",
        "description": "Search the product database",
        "parameters": { ... }
      }
    }
  ],
  "messages": [
    {
      "role": "system",
      "content": [
        {
          "type": "text",
          "text": "You are a shopping assistant...",
          "cache_control": { "type": "ephemeral" }
        }
      ]
    },
    ...
  ]
}

تصبح تعريفات الأدوات جزءًا من البادئة المخزَّنة. إذا كان لديك أدوات كثيرة، يمكن أن يقلل هذا بشكل كبير من التكاليف لكل طلب.

​

التخزين المؤقت مع الصور والمستندات

لنماذج الرؤية، يمكن تضمين الصور في المحتوى المخزَّن:

{
  "model": "claude-opus-4-5",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "image_url",
          "image_url": { "url": "data:image/png;base64,..." }
        },
        {
          "type": "text",
          "text": "This is the floor plan. I'll ask several questions about it.",
          "cache_control": { "type": "ephemeral" }
        }
      ]
    },
    {
      "role": "assistant",
      "content": "I can see the floor plan. What would you like to know?"
    },
    {
      "role": "user",
      "content": "How many bedrooms are there?"
    }
  ]
}

يتم تخزين الصورة والسياق الأولي، لذا فإن الأسئلة المتابعة حول نفس الصورة لا تعيد معالجتها.

​

استكشاف الأخطاء وإصلاحها

cached_tokens دائمًا 0

السبب	الحل
Prompt قصير جدًا	تأكد من أن الـ prompt يتجاوز ~1,024 token (4,000 لـ Claude)
تغيرت البادئة	تحقق من وجود محتوى ديناميكي في بداية الـ prompt
الطلب الأول	متوقع: الطلب الأول يكتب في الذاكرة المؤقتة، الطلبات اللاحقة تقرأ
انتهت صلاحية الذاكرة المؤقتة	قلل الوقت بين الطلبات إلى أقل من 5 دقائق
خوادم مختلفة	أضف prompt_cache_key لتوجيه الطلبات بشكل متسق

cache_creation_input_tokens في كل طلب

السبب	الحل
الـ prompt يتغير	أزل الطوابع الزمنية أو معرفات الطلب أو أي محتوى ديناميكي آخر من البادئة
cache_control مفقود	لـ Claude، تأكد من وجود علامة cache_control على كتل المحتوى
أقل من العتبة	الـ prompts أقل من الحد الأدنى لعدد الـ tokens لا تُحفز التخزين المؤقت
رسالة مستخدم وحيدة	متوقع للدور الأول. تنمو الذاكرة المؤقتة مع تاريخ المحادثة.

تكاليف أعلى من المتوقع

السبب	الحل
علاوة كتابة الذاكرة المؤقتة	يفرض Claude 25% أكثر للكتابات. تستحق فقط إذا كنت تعيد استخدام الـ prompt.
إعادة استخدام منخفضة	إذا كان كل prompt فريدًا، تدفع تكاليف الكتابة دون فوائد القراءة
هيكلة سيئة للـ prompt	انقل المحتوى الديناميكي إلى النهاية لتبقى البادئة مستقرة