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

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

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

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

عند مقاطعة النموذج أثناء إنشاء الرد، لن تظهر الرسالة 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

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

InteractionStatus

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

Content

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

BidiGenerateContentServerMessage

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

الحقول
usageMetadata

UsageMetadata

النتائج فقط. البيانات الوصفية للاستخدام حول الردود
voiceActivity

VoiceActivity

النتائج فقط. تم رصد نشاط صوتي في بث الصوت.
حقل الربط 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

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

map<string, string>

اختيارية: تصنيفات تتضمّن بيانات وصفية يحدّدها المستخدم للطلب

اختيارية: يجب أن تتّبع التصنيفات متطلبات التصنيفات الموحّدة العادية في السحابة الإلكترونية: - يجب أن تبدأ مفاتيح التصنيفات بحرف. - يجب ألا يزيد طول مفاتيح التصنيفات وقيمها عن 63 حرفًا (نقاط الترميز Unicode)، ويمكن أن تحتوي فقط على أحرف صغيرة وأحرف رقمية وشرطات سفلية وشرطات عادية. - يُسمح باستخدام الأحرف الدولية.

الاستخدام: - معرّفات السلامة من جهات التجميع: استخدِم المفتاح safety_identifier (مثلاً {"safety_identifier": "user_session_123"})

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.
startOffset

Duration

اختيارية: إزاحة البدء في وقت تحويل الصوت إلى نص بالنسبة إلى بداية الصوت
endOffset

Duration

اختيارية: إزاحة نهاية النص المكتوب عن بداية الصوت

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

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

InteractionStatus

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

عمليات التعداد
INTERACTION_STATUS_UNSPECIFIED حالة التفاعل غير محدَّدة.
IN_PROGRESS لا يزال الخادم يعالج بنشاط إدخال المستخدم أو ينفّذ عملية استدلال في الخلفية. قد يتبع ذلك المزيد من مخرجات النموذج.
REQUIRES_ACTION

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

ProactivityConfig

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

الحقول
proactiveAudio

bool

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

RealtimeInputConfig

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

الحقول
automaticActivityDetection

AutomaticActivityDetection

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

ActivityHandling

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

TurnCoverage

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

bool

اختيارية: تضبط هذه السمة الطوابع الزمنية للنصوص المؤقتة.

SessionResumptionConfig

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

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

الحقول
handle

string

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

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

SessionResumptionUpdate

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

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

الحقول
newHandle

string

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

bool

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

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

SlidingWindow

تعمل طريقة SlidingWindow من خلال تجاهل المحتوى في بداية نافذة السياق. سيبدأ السياق الناتج دائمًا عند بداية دور USER. ستبقى تعليمات النظام وأي 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، بينما يكون الإعداد التلقائي لـ Gemini 3.1 والإصدارات الأحدث هو TURN_INCLUDES_AUDIO_ACTIVITY_AND_ALL_VIDEO.
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

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

VoiceActivity

تم رصد نشاط صوتي في بث الصوت.

الحقول
type

Type

النتائج فقط. تمثّل هذه السمة نوع إشارة VAD(رصد النشاط الصوتي).
audioOffset

Duration

النتائج فقط. الوقت الذي تم فيه رصد النشاط الصوتي في وقت الصوت، مقارنةً ببداية بث الصوت

النوع

تمثّل هذه السمة نوع إشارة VAD.

عمليات التعداد
TYPE_UNSPECIFIED القيمة التلقائية هي UNSPECIFIED.
ACTIVITY_START إشارة بداية الجملة
ACTIVITY_END إشارة نهاية الجملة

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

يمكن الحصول على رموز مميّزة مؤقتة للمصادقة من خلال استدعاء AuthTokenService.CreateToken، ثم استخدامها مع GenerativeService.BidiGenerateContentConstrained، إما عن طريق تمرير الرمز المميّز في مَعلمة طلب بحث access_token، أو في عنوان Authorization HTTP مع إضافة البادئة "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 is متوفّرًا، سيتم أخذ رسالة BidiGenerateContentSetup الفعّالة بالكامل من bidiGenerateContentSetup في هذا الطلب. يتم تجاهل رسالة الإعداد من عملية الربط المباشر بواجهة برمجة التطبيقات.

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

BidiGenerateContentSetup

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

int32

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

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

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