التخزين المؤقت للسياق

في سير عمل نموذجي للذكاء الاصطناعي، قد يتم تمرير رموز الإدخال نفسها مرارًا وتكرارًا إلى أحد النماذج. يوفّر Gemini API آليتَي تخزين مؤقت مختلفتَين:

  • التخزين المؤقت الضمني (مفعّل تلقائيًا في نماذج Gemini 2.5، ولا نضمن توفير التكاليف)
  • التخزين المؤقت الصريح (يمكن تفعيله يدويًا على معظم النماذج، وضمان توفير التكلفة)

يكون التخزين المؤقت الصريح مفيدًا في الحالات التي تريد فيها ضمان توفير التكاليف، ولكن مع بعض العمل الإضافي من المطوّر.

التخزين المؤقت الضمني

يكون التخزين المؤقت الضمني مفعَّلاً تلقائيًا لجميع نماذج Gemini 2.5. ننقل تلقائيًا أي توفير في التكاليف إذا وصل طلبك إلى ذاكرات التخزين المؤقت. ليس عليك اتخاذ أي إجراء لتفعيل هذه الميزة. تسري هذه السياسة اعتبارًا من 8 مايو 2025. الحد الأدنى لعدد الرموز المميزة اللازمة لتخزين السياق مؤقتًا هو 1,024 في 2.5 Flash و4,096 في 2.5 Pro.

لزيادة فرصة الوصول إلى ذاكرة التخزين المؤقت الضمنية، اتّبِع الخطوات التالية:

  • جرِّب وضع المحتوى الكبير والشائع في بداية الطلب
  • محاولة إرسال طلبات تتضمّن بادئة مشابهة في فترة زمنية قصيرة

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

التخزين المؤقت الصريح

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

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

يفترض هذا القسم أنّك ثبّت حزمة تطوير برامج (SDK) خاصة بـ Gemini (أو ثبّت curl) وأنّك أعددت مفتاح واجهة برمجة تطبيقات، كما هو موضّح في دليل البدء السريع.

التخزين المؤقت الصريح باستخدام مكتبة OpenAI

إذا كنت تستخدم مكتبة OpenAI، يمكنك تفعيل التخزين المؤقت الصريح باستخدام السمة cached_content في extra_body.

حالات استخدام التخزين المؤقّت الواضح

تكون ميزة التخزين المؤقت للسياق مناسبة بشكل خاص للحالات التي تتم فيها الإشارة بشكل متكرر إلى سياق أولي كبير من خلال طلبات أقصر. يمكنك استخدام التخزين المؤقت للسياق في حالات الاستخدام التالية:

  • روبوتات الدردشة التي تتضمّن تعليمات نظام شاملة
  • التحليل المتكرّر لملفات الفيديو الطويلة
  • الاستعلامات المتكرّرة عن مجموعات المستندات الكبيرة
  • تحليل مستودع الرموز البرمجية أو إصلاح الأخطاء بشكل متكرّر

كيفية تقليل التكاليف باستخدام التخزين المؤقت الصريح

ميزة "التخزين المؤقت للسياق" هي ميزة مدفوعة مصمَّمة لتقليل التكاليف التشغيلية الإجمالية. تستند الفوترة إلى العوامل التالية:

  1. عدد الرموز المميزة المخزّنة مؤقتًا: عدد الرموز المميزة للإدخال المخزّنة مؤقتًا، والتي تتم فوترتها بسعر مخفّض عند تضمينها في الطلبات اللاحقة.
  2. مدة التخزين: هي المدة الزمنية التي يتم فيها تخزين الرموز المميّزة المخزَّنة مؤقتًا (مدة البقاء)، ويتم إصدار الفواتير استنادًا إلى مدة البقاء لعدد الرموز المميّزة المخزَّنة مؤقتًا. ليس هناك حد أدنى أو أقصى لقيمة TTL.
  3. عوامل أخرى: يتم تطبيق رسوم أخرى، مثل رسوم الرموز المميزة للإدخال غير المخزّنة مؤقتًا والرموز المميزة للإخراج.

للاطّلاع على تفاصيل الأسعار الحديثة، يُرجى الرجوع إلى صفحة الأسعار الخاصة بواجهة Gemini API. للتعرّف على كيفية احتساب الرموز المميزة، اطّلِع على دليل الرموز المميزة.

اعتبارات أخرى

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

  • الحد الأدنى لعدد الرموز المميزة للإدخال من أجل التخزين المؤقت للسياق هو 1,024 لـ 2.5 Flash و2,048 لـ 2.5 Pro. الحد الأقصى هو نفسه الحد الأقصى للنموذج المحدّد. (لمزيد من المعلومات حول احتساب الرموز المميزة، يُرجى الاطّلاع على دليل الرموز المميزة).
  • لا يميّز النموذج بين الرموز المميزة المخزّنة مؤقتًا ورموز الإدخال العادية. المحتوى المخزّن مؤقتًا هو بادئة للطلب.
  • لا توجد حدود خاصة للمعدّل أو الاستخدام في ما يتعلق بالتخزين المؤقت للسياق، بل تنطبق حدود المعدّل العادية الخاصة بـ GenerateContent، وتشمل حدود الرموز المميزة الرموز المميزة المخزّنة مؤقتًا.
  • يتم عرض عدد الرموز المميزة المخزّنة مؤقتًا في usage_metadata من عمليات الإنشاء والحصول على البيانات وعرض القائمة الخاصة بخدمة التخزين المؤقت، وكذلك في GenerateContent عند استخدام التخزين المؤقت.