Live API - WebSockets API reference

‫Live API هي واجهة برمجة تطبيقات ذات حالة تستخدِم WebSockets. في هذا القسم، ستجد تفاصيل إضافية حول WebSockets API.

الجلسات

ينشئ اتصال WebSocket جلسة بين العميل وخادم Gemini. بعد أن يبدأ العميل عملية ربط جديدة، يمكن للجلسة تبادل الرسائل مع الخادم لتنفيذ ما يلي:

  • إرسال نص أو صوت أو فيديو إلى خادم Gemini
  • تلقّي طلبات صوتية أو نصية أو طلبات استدعاء وظائف من خادم Gemini

اتصال WebSocket

لبدء جلسة، اتّصِل بنقطة نهاية websocket هذه:

wss://generativelanguage.googleapis.com/ws/google.ai.generativelanguage.v1beta.GenerativeService.BidiGenerateContent

إعدادات الجلسة

تحدّد الرسالة الأولية المُرسَلة بعد إنشاء اتصال WebSocket إعدادات الجلسة، والتي تتضمّن النموذج ومعلَمات الإنشاء وتعليمات النظام والأدوات.

لا يمكنك تعديل الإعدادات أثناء فتح الاتصال. ومع ذلك، يمكنك تغيير مَعلمات الإعداد، باستثناء الطراز، عند الإيقاف المؤقت والاستئناف من خلال آلية استئناف الجلسة.

اطّلِع على مثال الإعداد التالي. يُرجى العِلم أنّ طريقة كتابة الاسم قد تختلف في حِزم SDK. يمكنك البحث عن خيارات إعداد حزمة تطوير البرامج (SDK) في Python هنا.


{
  "model": string,
  "generationConfig": {
    "candidateCount": integer,
    "maxOutputTokens": integer,
    "temperature": number,
    "topP": number,
    "topK": integer,
    "presencePenalty": number,
    "frequencyPenalty": number,
    "responseModalities": [string],
    "speechConfig": object,
    "mediaResolution": object,
    "translationConfig": object
  },
  "systemInstruction": string,
  "tools": [object]
}

لمزيد من المعلومات حول حقل واجهة برمجة التطبيقات، يُرجى الاطّلاع على generationConfig.

إرسال الرسائل

لتبادل الرسائل عبر اتصال WebSocket، يجب أن يرسل العميل عنصر JSON عبر اتصال WebSocket مفتوح. يجب أن يحتوي عنصر JSON على حقل واحد بالضبط من مجموعة العناصر التالية:


{
  "setup": BidiGenerateContentSetup,
  "clientContent": BidiGenerateContentClientContent,
  "realtimeInput": BidiGenerateContentRealtimeInput,
  "toolResponse": BidiGenerateContentToolResponse
}

رسائل العميل المتوافقة

اطّلِع على رسائل العميل المتوافقة في الجدول التالي:

رسالة الوصف
BidiGenerateContentSetup إعدادات الجلسة التي سيتم إرسالها في الرسالة الأولى
BidiGenerateContentClientContent تعديل المحتوى المتزايد للمحادثة الحالية التي تم إرسالها من العميل
BidiGenerateContentRealtimeInput إدخال الصوت أو الفيديو أو النص في الوقت الفعلي
BidiGenerateContentToolResponse الردّ على الخطأ ToolCallMessage الذي تم تلقّيه من الخادم

تلقي الرسائل

لتلقّي رسائل من Gemini، استمع إلى حدث WebSocket "message"، ثم حلِّل النتيجة وفقًا لتعريف رسائل الخادم المتوافقة.

يُرجى الاطّلاع على ما يلي:

async with client.aio.live.connect(model='...', config=config) as session:
    await session.send(input='Hello world!', end_of_turn=True)
    async for message in session.receive():
        print(message)

قد تحتوي رسائل الخادم على الحقل usageMetadata، ولكنها ستتضمّن حقلاً واحدًا فقط من الحقول الأخرى من رسالة BidiGenerateContentServerMessage. (لا يتم التعبير عن اتحاد messageType في JSON، لذا سيظهر الحقل في المستوى الأعلى من الرسالة).

الرسائل والأحداث

ActivityEnd

لا يتضمّن هذا النوع أي حقول.

تحدّد هذه السمة نهاية نشاط المستخدم.

ActivityHandling

الطرق المختلفة للتعامل مع نشاط المستخدم

عمليات التعداد
ACTIVITY_HANDLING_UNSPECIFIED إذا لم يتم تحديد ذلك، يكون السلوك التلقائي هو START_OF_ACTIVITY_INTERRUPTS.
START_OF_ACTIVITY_INTERRUPTS إذا كانت القيمة "صحيح"، سيؤدي بدء النشاط إلى مقاطعة ردّ النموذج (يُعرف أيضًا باسم "المقاطعة"). سيتم قطع الردّ الحالي للنموذج في لحظة المقاطعة. هذا هو السلوك التلقائي.
NO_INTERRUPTION لن يتم إيقاف ردّ النموذج.

ActivityStart

لا يتضمّن هذا النوع أي حقول.

تحدّد هذه السمة بداية نشاط المستخدِم.

AudioTranscriptionConfig

إعدادات تحويل الصوت إلى نص

الحقول
languageCodes[]

string

اختياريّ. رموز اللغة BCP-47 التي تقدّم تلميحات حول اللغات المتوفّرة في الصوت في حال عدم تحديد اللغة أو ترك الحقل فارغًا، يتم ضبط الإعدادات التلقائية على ميزة "التعرّف التلقائي على اللغة".
customVocabulary[]

string

اختياريّ. قائمة بعبارات المفردات المخصّصة لتوجيه نموذج التعرّف على الكلام نحو التعرّف على مصطلحات معيّنة (أسماء المنتجات والأسماء الصحيحة والمصطلحات الفنية).
wordTimestamp

bool

اختياريّ. تضبط هذه السمة عملية إنشاء طوابع زمنية على مستوى الكلمات.
diarization

bool

اختياريّ. تضبط هذه السياسة إعدادات ميزة "تمييز أصوات المتحدّثِين".
mode

Mode

اختياريّ. تضبط هذه السمة وضع تحويل الصوت إلى نص. القيم المسموح بها: VERBATIM وSMART. إذا لم يتم تحديدها، يتم ضبط القيمة التلقائية على VERBATIM. في SMART، يزيل النموذج أخطاء الطلاقة (مثل كلمات الحشو والتكرار والبدايات الخاطئة)، ويجري تنظيفًا نحويًا بسيطًا، وينسّق المحتوى تلقائيًا (فقرات ونقاط تعداد وقوائم مرقّمة)، ويجري تعديلات بسيطة على المحتوى (تصحيحات ذاتية مضمّنة). لا تتوافق الطوابع الزمنية والتقسيم إلى مقاطع مع الوضع SMART.

الوضع

وضع تحويل الصوت إلى نص

عمليات التعداد
MODE_UNSPECIFIED وضع تحويل الصوت إلى نص غير محدّد
VERBATIM وضع "تحويل الصوت إلى نص" بدقة
SMART وضع "التحويل الذكي للصوت إلى نص"

AutomaticActivityDetection

تضبط هذه السمة عملية الرصد التلقائي للنشاط.

الحقول
disabled

bool

اختياريّ. في حال تفعيل هذا الخيار (وهو الإعداد التلقائي)، يتم احتساب عدد عمليات إدخال الصوت والنص التي تم رصدها كنشاط. في حال إيقافها، على العميل إرسال إشارات النشاط.
startOfSpeechSensitivity

StartSensitivity

اختياريّ. تحدّد هذه السمة مدى احتمال رصد الكلام.
prefixPaddingMs

int32

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

EndSensitivity

اختياريّ. تحدّد هذه السمة مدى احتمال انتهاء الكلام الذي تم رصده.
silenceDurationMs

int32

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

BidiGenerateContentClientContent

تعديل تدريجي للمحادثة الحالية يتم إرساله من العميل يتم إلحاق كل المحتوى هنا بشكل غير مشروط بسجلّ المحادثات واستخدامه كجزء من الطلب المقدَّم إلى النموذج لإنشاء المحتوى.

ستؤدي الرسالة هنا إلى مقاطعة أي عملية إنشاء حالية للنموذج.

الحقول
turns[]

Content

اختياريّ. المحتوى الملحق بالمحادثة الحالية مع النموذج

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

bool

اختياريّ. إذا كانت القيمة true، يشير ذلك إلى أنّ إنشاء محتوى الخادم يجب أن يبدأ بالطلب المتراكم حاليًا. بخلاف ذلك، ينتظر الخادم رسائل إضافية قبل بدء عملية الإنشاء.

BidiGenerateContentRealtimeInput

بيانات أدخلها المستخدم التي يتم إرسالها في الوقت الفعلي

يتم التعامل مع الوسائط المختلفة (الصوت والفيديو والنص) كعمليات بث متزامنة. لا نضمن ترتيب المحتوى في ساحات المشاركات هذه.

تختلف هذه الميزة عن BidiGenerateContentClientContent في عدة جوانب:

  • يمكن إرسالها بشكل مستمر بدون انقطاع لإنشاء النموذج.
  • في حال الحاجة إلى دمج البيانات الموزّعة على BidiGenerateContentClientContent وBidiGenerateContentRealtimeInput، يحاول الخادم تحسين الاستجابة، ولكن لا توجد ضمانات.
  • لا يتم تحديد نهاية الدور بشكل صريح، بل يتم استنتاجها من نشاط المستخدم (على سبيل المثال، نهاية الكلام).
  • حتى قبل نهاية المحادثة، تتم معالجة البيانات بشكل تدريجي لتحسين سرعة بدء الرد من النموذج.
الحقول
mediaChunks[]

Blob

اختياريّ. بيانات بايت مضمّنة لإدخال الوسائط لا يمكن استخدام قيم mediaChunks متعددة، وسيتم تجاهل جميع القيم باستثناء القيمة الأولى.

تم إيقاف هذه السمة نهائيًا، يُرجى استخدام إحدى القيم audio أو video أو text بدلاً منها.
audio

Blob

اختياريّ. تشكّل هذه البيانات مصدر إدخال الصوت في الوقت الفعلي.
video

Blob

اختياريّ. تشكّل هذه البيانات مصدر بث الفيديو في الوقت الفعلي.
activityStart

ActivityStart

اختياريّ. تحدّد هذه السمة بداية نشاط المستخدِم. لا يمكن إرسال هذا الإجراء إلا إذا كان رصد النشاط التلقائي (أي من جهة الخادم) غير مفعّل.
activityEnd

ActivityEnd

اختياريّ. تحدّد هذه السمة نهاية نشاط المستخدم. لا يمكن إرسال هذا الإجراء إلا إذا كان رصد النشاط التلقائي (أي من جهة الخادم) غير مفعّل.
mediaResolution

MediaResolution

اختياريّ. تمثّل هذه السمة دقة الوسائط التي سيتم استخدامها. في حال عدم تحديدها، يتم استخدام setup.generationConfig.mediaResolution أو قيمة تلقائية إذا لم يتم توفير الإعداد.
audioStreamEnd

bool

اختياريّ. يشير إلى أنّ بث الصوت قد انتهى، مثلاً لأنّه تم إيقاف الميكروفون.

يجب إرسال هذا الحدث فقط عندما يكون رصد النشاط التلقائي مفعَّلاً (وهو الإعداد التلقائي).

يمكن للعميل إعادة فتح البث من خلال إرسال رسالة صوتية.
text

string

اختياريّ. تشكّل هذه الأحداث دفق إدخال النص في الوقت الفعلي.

BidiGenerateContentServerContent

تعديل الخادم التدريجي الذي تم إنشاؤه بواسطة النموذج استجابةً لرسائل العميل

يتم إنشاء المحتوى في أسرع وقت ممكن، وليس في الوقت الفعلي. يمكن للعملاء اختيار تخزينها مؤقتًا وتشغيلها في الوقت الفعلي.

الحقول
generationComplete

bool

النتائج فقط. إذا كانت القيمة true، يشير ذلك إلى أنّ النموذج قد انتهى من الإنشاء.

عند مقاطعة النموذج أثناء إنشاء الرد، لن تظهر الرسالة generation_complete في الردّ الذي تمت مقاطعته، بل سيتم الانتقال إلى interrupted > turn_complete.

عندما يفترض النموذج أنّ التشغيل يتم في الوقت الفعلي، سيحدث تأخير بين generation_complete وturn_complete بسبب انتظار النموذج لانتهاء التشغيل.
turnComplete

bool

النتائج فقط. إذا كانت القيمة true، يشير ذلك إلى أنّ النموذج قد أكمل دوره. لن يبدأ إنشاء الردود إلا استجابةً لرسائل إضافية من العميل. يُرجى العِلم أنّه عند تفعيل ميزة إعداد تقارير حالة التشغيل، لا يتم إرسال هذا الحدث إلا عندما تشير حالة التشغيل إلى اكتمال التشغيل. سيتم تجاهل حالة التشغيل المستقبلية للجيل نفسه.
interrupted

bool

النتائج فقط. إذا كانت القيمة صحيحة، يشير ذلك إلى أنّ رسالة من العميل قد أوقفت عملية إنشاء النموذج الحالية. إذا كان العميل يشغّل المحتوى في الوقت الفعلي، فهذه إشارة جيدة لإيقاف قائمة التشغيل الحالية وإفراغها.
groundingMetadata

GroundingMetadata

النتائج فقط. البيانات الوصفية الأساسية للمحتوى الذي تم إنشاؤه
inputTranscription

BidiGenerateContentTranscription

النتائج فقط. أدخِل النص المحوَّل من الصوت. يتم إرسال النص بشكل مستقل عن رسائل الخادم الأخرى، ولا يمكن ضمان ترتيبها.
interimInputTranscription

BidiGenerateContentTranscription

النتائج فقط. يتم تعديل ميزة "النسخ الصوتي بوقت استجابة منخفض" أثناء حديث المستخدم. يخضع هذا الحقل لتعديلات متكرّرة.
outputTranscription

BidiGenerateContentTranscription

النتائج فقط. إخراج نص صوتي تشكّل هذه النصوص جزءًا من ناتج عملية الإنشاء التي يجريها الخادم. يتم إرسال آخر نسخة مكتوبة من هذا الرد قبل generationComplete أو interrupted، ويتبعهما turnComplete. ليس هناك ترتيب دقيق مضمون بين النصوص المكتوبة ومصدر إخراج الصوت modelTurn الآخر، ولكن يحاول الخادم إرسال النصوص المكتوبة بالقرب من مصدر إخراج الصوت المقابل.
urlContextMetadata

UrlContextMetadata
waitingForInput

bool

النتائج فقط. إذا كانت القيمة صحيحة، يشير ذلك إلى أنّ النموذج لا ينشئ محتوًى لأنّه ينتظر المزيد من الإدخالات من المستخدم، مثلاً لأنّه يتوقّع أن يواصل المستخدم التحدّث.
speechState
(deprecated)

SpeechState

النتائج فقط. تم إيقاف هذه السمة نهائيًا: استخدِم VoiceActivity بدلاً منها.

تشير إلى الحالة الحالية لميزة "التعرّف على الكلام" على realtimeInput.audio. لا يتم ضبط القيمة أو يتم ضبطها على صفر إذا لم تتغير الحالة.
interactionStatus

InteractionStatus

النتائج فقط. تعرض هذه السمة حالة النشاط الحالية لجلسة البث المباشر. يتم إرسالها دائمًا مع turnComplete.
modelTurn

Content

النتائج فقط. المحتوى الذي أنشأه النموذج كجزء من المحادثة الحالية مع المستخدم

BidiGenerateContentServerMessage

رسالة الرد على طلب BidiGenerateContent.

الحقول
usageMetadata

UsageMetadata

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

BidiGenerateContentSetupComplete

النتائج فقط. يتم إرسالها ردًا على رسالة BidiGenerateContentSetup من العميل عند اكتمال عملية الإعداد.
serverContent

BidiGenerateContentServerContent

النتائج فقط. المحتوى الذي ينشئه النموذج ردًا على رسائل العميل
toolCall

BidiGenerateContentToolCall

النتائج فقط. طلب من العميل تنفيذ functionCalls وإرجاع الردود مع id المطابقة
toolCallCancellation

BidiGenerateContentToolCallCancellation

النتائج فقط. إشعار للعميل بأنّه يجب إلغاء ToolCallMessage تم إصداره سابقًا مع id المحدّدة.
goAway

GoAway

النتائج فقط. إشعار بأنّ الخادم سيقطع الاتصال قريبًا
sessionResumptionUpdate

SessionResumptionUpdate

النتائج فقط. تعديل حالة استئناف الجلسة

BidiGenerateContentSetup

الرسالة التي سيتم إرسالها في BidiGenerateContentClientMessage الأول (وفي الأول فقط). يحتوي على إعدادات سيتم تطبيقها طوال مدة RPC البث المباشر.

على العملاء انتظار رسالة BidiGenerateContentSetupComplete قبل إرسال أي رسائل إضافية.

الحقول
model

string

الحقل مطلوب. اسم مورد النموذج. يُستخدَم هذا المعرّف كمعرّف للنموذج.

التنسيق: models/{model}
generationConfig

GenerationConfig

اختياريّ. إعدادات الإنشاء

الحقول التالية غير متاحة:

  • responseLogprobs
  • responseMimeType
  • logprobs
  • responseSchema
  • responseJsonSchema
  • stopSequence
  • skipResponseCache
  • routingConfig
  • audioTimestamp
systemInstruction

Content

اختياريّ. قدّم المستخدم تعليمات النظام للنموذج.

ملاحظة: يجب استخدام النص فقط في الأجزاء، وسيكون المحتوى في كل جزء في فقرة منفصلة.
tools[]

Tool

اختياريّ. قائمة Tools قد يستخدمها النموذج لإنشاء الرد التالي

Tool هي جزء من الرمز البرمجي يتيح للنظام التفاعل مع أنظمة خارجية لتنفيذ إجراء أو مجموعة من الإجراءات خارج نطاق معرفة النموذج.
realtimeInputConfig

RealtimeInputConfig

اختياريّ. تضبط هذه السمة طريقة التعامل مع الإدخال في الوقت الفعلي.
sessionResumption

SessionResumptionConfig

اختياريّ. تضبط هذه السمة آلية استئناف الجلسة.

في حال تضمينها، سيرسل الخادم SessionResumptionUpdate رسائل.
contextWindowCompression

ContextWindowCompressionConfig

اختياريّ. تضبط هذه السمة آلية ضغط قدرة الاستيعاب.

في حال تضمينها، سيقلّل الخادم تلقائيًا حجم السياق عندما يتجاوز الطول الذي تم ضبطه.
inputAudioTranscription

AudioTranscriptionConfig

اختياريّ. في حال ضبط هذا الخيار، يتم تفعيل ميزة تحويل الإدخال الصوتي إلى نص. تتوافق عملية تحويل الصوت إلى نص مع لغة الصوت المُدخَل، إذا تم ضبطها.
outputAudioTranscription

AudioTranscriptionConfig

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

ProactivityConfig

اختياريّ. تضبط هذه السمة مدى استباقية النموذج.

يتيح ذلك للنموذج الاستجابة بشكل استباقي للإدخال وتجاهل الإدخال غير ذي الصلة.
historyConfig

HistoryConfig

اختياريّ. تضبط هذه السمة تبادل السجلّ بين العميل والخادم.

BidiGenerateContentSetupComplete

لا يتضمّن هذا النوع أي حقول.

يتم إرسالها ردًا على رسالة BidiGenerateContentSetup من العميل.

BidiGenerateContentToolCall

طلب من العميل تنفيذ functionCalls وإرجاع الردود مع id المطابقة

الحقول
functionCalls[]

FunctionCall

النتائج فقط. تمثّل هذه السمة استدعاء الدالة المطلوب تنفيذه.

BidiGenerateContentToolCallCancellation

إشعار للعميل بأنّه كان من المفترض عدم تنفيذ ToolCallMessage الصادر سابقًا والذي يتضمّن id المحدّدة، ويجب إلغاؤه. إذا كانت هناك آثار جانبية لعمليات استدعاء الأدوات هذه، قد تحاول البرامج التراجع عنها. لا تظهر هذه الرسالة إلا في الحالات التي تقاطع فيها الأجهزة العميلة أدوار الخادم.

الحقول
ids[]

string

النتائج فقط. معرّفات طلبات استدعاء الأدوات التي سيتم إلغاؤها.

BidiGenerateContentToolResponse

استجابة من العميل لرمز الحالة ToolCall الذي تم تلقّيه من الخادم تتم مطابقة عناصر FunctionResponse الفردية مع عناصر FunctionCall ذات الصلة من خلال الحقل id.

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

الحقول
functionResponses[]

FunctionResponse

اختياريّ. الردّ على استدعاءات الدوال

BidiGenerateContentTranscription

نسخة مكتوبة من المحتوى الصوتي (المدخل أو المخرج)

الحقول
text

string

نص التحويل إلى نص
languageCode

string

تمثّل هذه السمة رمز اللغة المستخدَمة في نص الأغنية وفق المعيار BCP-47.

ContextWindowCompressionConfig

تفعيل ضغط قدرة استيعاب النموذج — آلية لإدارة قدرة استيعاب النموذج حتى لا تتجاوز طولاً معيّنًا

الحقول
حقل الربط compressionMechanism آلية ضغط قدرة الاستيعاب المستخدَمة يمكن أن يكون التعليق compressionMechanism إحدى القيم التالية فقط:
slidingWindow

SlidingWindow

آلية النافذة المنزلقة
triggerTokens

int64

عدد الرموز المميزة (قبل تنفيذ جولة) المطلوبة لتفعيل ضغط نافذة السياق

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

إذا لم يتم ضبطها، تكون القيمة التلقائية هي% 80 من الحد الأقصى لقدرة استيعاب النموذج. يتبقى بذلك% 20 لطلب المستخدم التالي أو ردّ النموذج.

EndSensitivity

تحدّد هذه السمة كيفية رصد نهاية الكلام.

عمليات التعداد
END_SENSITIVITY_UNSPECIFIED القيمة التلقائية هي END_SENSITIVITY_HIGH.
END_SENSITIVITY_HIGH تؤدي ميزة "الرصد التلقائي" إلى إنهاء الكلام بشكل متكرّر.
END_SENSITIVITY_LOW تتوقف ميزة "الرصد التلقائي" عن رصد الكلام بمعدّل أقل.

GoAway

إشعار بأنّ الخادم سيقطع الاتصال قريبًا

الحقول
timeLeft

Duration

الوقت المتبقي قبل إنهاء الاتصال على أنّه ABORTED.

لن تقلّ هذه المدة عن الحدّ الأدنى الخاص بالنموذج، والذي سيتم تحديده مع حدود المعدّل للنموذج.

HistoryConfig

إعدادات السجلّ

يتم تضمين هذه الرسالة في إعدادات الجلسة على النحو التالي: BidiGenerateContentSetup.historyConfig. تضبط هذه السمة تبادل رسائل السجلّ.

الحقول
initialHistoryInClientContent

bool

اختياريّ. إذا كانت القيمة true، سينتظر الخادم بعد إرسال setupComplete، وسيعالج أولاً clientContent رسالة إلى أن تصبح قيمة turnComplete هي true. لن يؤدي هذا السجلّ الأوّلي إلى بدء مكالمة مع النموذج، وقد ينتهي بالدور MODEL. بعد turnComplete، يتم عرض true، ويمكن للعميل بدء المحادثة في الوقت الفعلي من خلال realtimeInput.

ProactivityConfig

إعدادات ميزات الاستباقية

الحقول
proactiveAudio

bool

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

RealtimeInputConfig

تضبط هذه السياسة سلوك الإدخال في الوقت الفعلي في BidiGenerateContent.

الحقول
automaticActivityDetection

AutomaticActivityDetection

اختياريّ. إذا لم يتم ضبط هذا الخيار، تكون ميزة "الرصد التلقائي للنشاط" مفعّلة تلقائيًا. في حال إيقاف ميزة "الرصد التلقائي للصوت"، على العميل إرسال إشارات النشاط.
activityHandling

ActivityHandling

اختياريّ. تحدّد هذه السمة تأثير النشاط.
turnCoverage

TurnCoverage

اختياريّ. تحدّد هذه السمة الإدخال الذي يتم تضمينه في رد المستخدم.

SessionResumptionConfig

إعدادات استئناف الجلسة

يتم تضمين هذه الرسالة في إعدادات الجلسة على النحو التالي: BidiGenerateContentSetup.sessionResumption. في حال ضبطه، سيرسل الخادم رسائل SessionResumptionUpdate.

الحقول
handle

string

معرّف جلسة سابقة. إذا لم يكن متوفّرًا، يتم إنشاء جلسة جديدة.

تأتي معرّفات الجلسات من قيم SessionResumptionUpdate.token في عمليات الربط السابقة.

SessionResumptionUpdate

تعديل حالة استئناف الجلسة

يتم إرسالها فقط في حال ضبط BidiGenerateContentSetup.sessionResumption.

الحقول
newHandle

string

مقبض جديد يمثّل حالة يمكن استئنافها. يكون فارغًا إذا كانت قيمة resumable هي false.
resumable

bool

تكون القيمة true إذا كان يمكن استئناف الجلسة الحالية في هذه المرحلة.

لا يمكن استئناف الجلسة في بعض المراحل. على سبيل المثال، عندما ينفّذ النموذج استدعاءات الدوال أو ينشئ المحتوى. سيؤدي استئناف الجلسة (باستخدام رمز مميّز لجلسة سابقة) في مثل هذه الحالة إلى فقدان بعض البيانات. في هذه الحالات، سيكون newHandle فارغًا وسيكون resumable بقيمة false.

SlidingWindow

تعمل طريقة SlidingWindow من خلال تجاهل المحتوى في بداية قدرة الاستيعاب. سيبدأ السياق الناتج دائمًا عند بداية دور المستخدم. ستبقى تعليمات النظام وأي BidiGenerateContentSetup.prefixTurns في بداية النتيجة دائمًا.

الحقول
targetTokens

int64

عدد الرموز المميزة المستهدَفة التي يجب الاحتفاظ بها. القيمة التلقائية هي trigger_tokens/2.

يؤدي تجاهل أجزاء من قدرة الاستيعاب إلى زيادة مؤقتة في وقت الاستجابة، لذا يجب معايرة هذه القيمة لتجنُّب عمليات الضغط المتكررة.

StartSensitivity

تحدّد هذه السمة كيفية رصد بداية الكلام.

عمليات التعداد
START_SENSITIVITY_UNSPECIFIED القيمة التلقائية هي START_SENSITIVITY_HIGH.
START_SENSITIVITY_HIGH ستتعرّف ميزة "الرصد التلقائي" على بداية الكلام بشكل متكرّر.
START_SENSITIVITY_LOW سيتم رصد بداية الكلام بشكل أقل.

TurnCoverage

خيارات بشأن الإدخال الذي يتم تضمينه في رد المستخدم

عمليات التعداد
TURN_COVERAGE_UNSPECIFIED في حال عدم تحديد ذلك، يتم اختيار سلوك تلقائي استنادًا إلى النموذج. على سبيل المثال، بالنسبة إلى Gemini 2.5، يكون الإعداد التلقائي هو TURN_INCLUDES_ONLY_ACTIVITY، بينما يكون TURN_INCLUDES_AUDIO_ACTIVITY_AND_ALL_VIDEO هو الإعداد التلقائي بالنسبة إلى Gemini 3.1 والإصدارات الأحدث.
TURN_INCLUDES_ONLY_ACTIVITY يتضمّن النشاط منذ آخر منعطف، باستثناء عدم النشاط (مثل الصمت في بث الصوت).
TURN_INCLUDES_ALL_INPUT يتضمّن جميع البيانات في الوقت الفعلي منذ آخر دورة، بما في ذلك عدم النشاط (مثل الصمت في بث الصوت).
TURN_INCLUDES_AUDIO_ACTIVITY_AND_ALL_VIDEO يتضمّن هذا السجلّ النشاط الصوتي وكل الفيديوهات منذ آخر مرة تم فيها إيقاف السجلّ مؤقتًا. باستخدام ميزة "رصد النشاط تلقائيًا"، يشير النشاط الصوتي إلى الكلام ويستثني الصمت.

TranslationConfig

إعدادات ميزات الترجمة

الحقول
targetLanguageCode

string

الحقل مطلوب. اللغة الهدف للترجمة. القيم المسموح بها هي رموز اللغة المستخدَمة في المقطع الصوتي وفق المعيار BCP-47 (مثل "en" أو "es" أو "fr").
echoTargetLanguage

bool

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

UrlContextMetadata

بيانات وصفية مرتبطة بأداة استرجاع سياق عنوان URL

الحقول
urlMetadata[]

UrlMetadata

قائمة بسياق عناوين URL

UsageMetadata

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

الحقول
promptTokenCount

int32

النتائج فقط. عدد الرموز المميزة في الطلب عند ضبط cachedContent، يظلّ هذا هو إجمالي حجم الطلب الفعّال، ما يعني أنّه يشمل عدد الرموز المميزة في المحتوى المخزّن مؤقتًا.
cachedContentTokenCount

int32

عدد الرموز المميّزة في الجزء المخزّن مؤقتًا من الطلب (المحتوى المخزّن مؤقتًا)
responseTokenCount

int32

النتائج فقط. إجمالي عدد الرموز المميزة في جميع الردود المقترَحة التي تم إنشاؤها
toolUsePromptTokenCount

int32

النتائج فقط. عدد الرموز المميزة المتوفّرة في طلبات استخدام الأدوات
thoughtsTokenCount

int32

النتائج فقط. عدد الرموز المميّزة للأفكار في نماذج التفكير
totalTokenCount

int32

النتائج فقط. إجمالي عدد الرموز المميّزة لطلب الإنشاء (الطلب + المرشّحون للاستجابة)
promptTokensDetails[]

ModalityTokenCount

النتائج فقط. قائمة بالوسائط التي تمت معالجتها في بيانات الإدخال الخاصة بالطلب
cacheTokensDetails[]

ModalityTokenCount

النتائج فقط. قائمة بأنواع المحتوى المخزّن مؤقتًا في بيانات طلب البحث.
responseTokensDetails[]

ModalityTokenCount

النتائج فقط. قائمة بالوسائط التي تم عرضها في الردّ.
toolUsePromptTokensDetails[]

ModalityTokenCount

النتائج فقط. قائمة بالوسائط التي تمت معالجتها لإدخالات طلب استخدام الأدوات

رموز المصادقة المميزة المؤقتة

يمكن الحصول على رموز المصادقة المؤقتة من خلال استدعاء AuthTokenService.CreateToken، ثم استخدامها مع GenerativeService.BidiGenerateContentConstrained، إما عن طريق تمرير الرمز المميز في مَعلمة طلب بحث access_token، أو في عنوان HTTP Authorization مع إضافة البادئة "Token" إليه.

CreateAuthTokenRequest

أنشئ رمزًا مميزًا مؤقتًا للمصادقة.

الحقول
authToken

AuthToken

الحقل مطلوب. الرمز المميّز المطلوب إنشاؤه

AuthToken

طلب لإنشاء رمز مميّز مؤقت للمصادقة

الحقول
name

string

النتائج فقط. المعرّف. الرمز المميّز نفسه
expireTime

Timestamp

اختياريّ. الإدخال فقط غير قابل للتغيير وقت اختياري يتم بعده رفض الرسائل في جلسات BidiGenerateContent عند استخدام الرمز المميّز الناتج. (قد يغلق Gemini الجلسة بشكل استباقي بعد هذا الوقت).

إذا لم يتم ضبط هذا الخيار، سيتم تلقائيًا ضبطه على 30 دقيقة في المستقبل. في حال ضبط هذا الحقل، يجب أن تكون القيمة أقل من 20 ساعة في المستقبل.
newSessionExpireTime

Timestamp

اختياريّ. الإدخال فقط غير قابل للتغيير الوقت الذي سيتم بعده رفض جلسات Live API الجديدة التي تستخدم الرمز المميز الناتج من هذا الطلب

إذا لم يتم ضبط هذا الحقل، سيتم ضبطه تلقائيًا على 60 ثانية في المستقبل. في حال ضبط هذا الحقل، يجب أن تكون القيمة أقل من 20 ساعة في المستقبل.
fieldMask

FieldMask

اختياريّ. الإدخال فقط غير قابل للتغيير إذا كانت field_mask فارغة، ولم يكن bidiGenerateContentSetup متوفّرًا، سيتم استرداد الرسالة BidiGenerateContentSetup السارية من اتصال Live API.

إذا كان field_mask فارغًا، وكان bidiGenerateContentSetup متوفّرًا، سيتم أخذ رسالة BidiGenerateContentSetup الفعّالة بالكامل من bidiGenerateContentSetup في هذا الطلب. يتم تجاهل رسالة الإعداد من عملية الربط المباشر بواجهة برمجة التطبيقات.

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

BidiGenerateContentSetup

اختياريّ. الإدخال فقط غير قابل للتغيير إعدادات خاصة بـ BidiGenerateContent
uses

int32

اختياريّ. الإدخال فقط غير قابل للتغيير عدد المرات التي يمكن فيها استخدام الرمز المميز إذا كانت هذه القيمة صفرًا، لن يتم تطبيق أي حدّ. لا يُحتسب استئناف جلسة Live API كاستخدام. إذا لم يتم تحديد قيمة، تكون القيمة التلقائية هي 1.

مزيد من المعلومات عن الأنواع الشائعة

لمزيد من المعلومات حول أنواع موارد واجهة برمجة التطبيقات الشائعة الاستخدام Blob وContent وFunctionCall وFunctionResponse وGenerationConfig وGroundingMetadata وModalityTokenCount وTool، يُرجى الاطّلاع على إنشاء المحتوى.