Live API - WebSockets API reference

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

الجلسات

ينشئ اتصال 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
  },
  "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

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

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

AutomaticActivityDetection

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

الحقول
`disabled`	`bool` اختياريّ. في حال تفعيل هذا الخيار (وهو الإعداد التلقائي)، يتم احتساب عدد المرات التي تم فيها رصد الصوت وإدخال النصوص كنشاط. في حال إيقافها، على العميل إرسال إشارات النشاط.
`startOfSpeechSensitivity`	`StartSensitivity` اختياريّ. يحدّد هذا الإعداد مدى احتمال رصد الكلام.
`prefixPaddingMs`	`int32` اختياريّ. المدة المطلوبة للكلام الذي تم رصده قبل بدء الكلام كلما انخفضت هذه القيمة، زادت حساسية ميزة رصد بداية الكلام، وأصبح بإمكانها التعرّف على الكلام الأقصر. ومع ذلك، يؤدي ذلك أيضًا إلى زيادة احتمال ظهور نتائج إيجابية خاطئة.
`endOfSpeechSensitivity`	`EndSensitivity` اختياريّ. تحدّد هذه السمة مدى احتمال انتهاء الكلام الذي تم رصده.
`silenceDurationMs`	`int32` اختياريّ. المدة المطلوبة لرصد صوت غير كلامي (مثل الصمت) قبل إكمال الكلام كلما زادت هذه القيمة، زادت مدة فجوات الكلام التي يمكن أن تحدث بدون مقاطعة نشاط المستخدم، ولكن سيؤدي ذلك إلى زيادة وقت الاستجابة للنموذج.

BidiGenerateContentClientContent

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

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

الحقول

الحقول
`turns[]`	`Content` اختياريّ. المحتوى الملحق بالمحادثة الحالية مع النموذج بالنسبة إلى طلبات البحث ذات الدورة الواحدة، يكون هذا مثيلاً واحدًا. بالنسبة إلى الاستعلامات المتعددة الأدوار، هذا حقل متكرّر يحتوي على سجلّ المحادثات وأحدث طلب.
`turnComplete`	`bool` اختياريّ. إذا كانت القيمة صحيحة، يشير ذلك إلى أنّ إنشاء محتوى الخادم يجب أن يبدأ بالطلب المتراكم حاليًا. بخلاف ذلك، ينتظر الخادم رسائل إضافية قبل بدء عملية الإنشاء.

turns[]

Content

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

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

turnComplete

bool

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

BidiGenerateContentRealtimeInput

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

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

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

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

الحقول
`mediaChunks[]`	`Blob` اختياريّ. بيانات وحدات البايت المضمّنة لإدخال الوسائط لا يمكن استخدام عدة `mediaChunks`، وسيتم تجاهل جميعها باستثناء الأولى. تم إيقاف هذه السمة نهائيًا، يُرجى استخدام إحدى القيم `audio` أو `video` أو `text` بدلاً منها.
`audio`	`Blob` اختياريّ. تشكّل هذه البيانات دفق الإدخال الصوتي في الوقت الفعلي.
`video`	`Blob` اختياريّ. تشكّل هذه البيانات مصدر بث الفيديو في الوقت الفعلي.
`activityStart`	`ActivityStart` اختياريّ. تحدّد هذه السمة بداية نشاط المستخدِم. لا يمكن إرسال هذا الحدث إلا إذا كان رصد النشاط التلقائي (أي من جهة الخادم) غير مفعّل.
`activityEnd`	`ActivityEnd` اختياريّ. تحدّد هذه السمة نهاية نشاط المستخدم. لا يمكن إرسال هذا الحدث إلا إذا كان رصد النشاط التلقائي (أي من جهة الخادم) غير مفعّل.
`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` النتائج فقط. أدخِل النص المحوَّل من الصوت. يتم إرسال النص بشكل مستقل عن رسائل الخادم الأخرى، ولا يمكن ضمان ترتيبها.
`outputTranscription`	`BidiGenerateContentTranscription` النتائج فقط. إخراج نص مُحوَّل من مقطع صوتي يتم إرسال النص المحوّل بشكل مستقل عن رسائل الخادم الأخرى، ولا يمكن ضمان ترتيبها، خاصةً بين `serverContent` و`outputTranscription`.
`urlContextMetadata`	`UrlContextMetadata`
`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` `stopSequence` `routingConfig` `audioTimestamp`
`systemInstruction`	`Content` اختياريّ. قدّم المستخدم تعليمات النظام للنموذج. ملاحظة: يجب استخدام النص فقط في الأجزاء، وسيكون المحتوى في كل جزء في فقرة منفصلة.
`tools[]`	`Tool` اختياريّ. قائمة `Tools` قد يستخدمها النموذج لإنشاء الرد التالي `Tool` هي جزء من الرمز البرمجي يتيح للنظام التفاعل مع أنظمة خارجية لتنفيذ إجراء أو مجموعة من الإجراءات خارج نطاق معرفة النموذج.
`realtimeInputConfig`	`RealtimeInputConfig` اختياريّ. تضبط هذه السمة طريقة التعامل مع الإدخال في الوقت الفعلي.
`sessionResumption`	`SessionResumptionConfig` اختياريّ. تضبط هذه السمة آلية استئناف الجلسة. في حال تضمينها، سيرسل الخادم `SessionResumptionUpdate` رسائل.
`contextWindowCompression`	`ContextWindowCompressionConfig` اختياريّ. تضبط هذه السمة آلية ضغط قدرة الاستيعاب. في حال تضمينها، سيقلّل الخادم تلقائيًا حجم السياق عندما يتجاوز الطول الذي تم ضبطه.
`inputAudioTranscription`	`AudioTranscriptionConfig` اختياريّ. في حال ضبط هذا الخيار، يتم تفعيل تحويل الإدخال الصوتي إلى نص. تتوافق الترجمة مع لغة الصوت المُدخَل، إذا تم ضبطها.
`outputAudioTranscription`	`AudioTranscriptionConfig` اختياريّ. في حال ضبط هذا الخيار، يتم تفعيل تحويل الصوت إلى نص في مخرجات النموذج الصوتية. تتوافق النسخة المكتوبة مع رمز اللغة المحدّد للصوت الناتج، إذا تم ضبطه.
`proactivity`	`ProactivityConfig` اختياريّ. تضبط هذه السمة مدى استباقية النموذج. يتيح ذلك للنموذج الاستجابة بشكل استباقي للإدخال وتجاهل الإدخالات غير ذات الصلة.

BidiGenerateContentSetupComplete

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

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

BidiGenerateContentToolCall

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

الحقول

الحقول
`functionCalls[]`	`FunctionCall` النتائج فقط. استدعاء الدالة المطلوب تنفيذه

functionCalls[]

FunctionCall

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

BidiGenerateContentToolCallCancellation

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

الحقول

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

ids[]

string

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

BidiGenerateContentToolResponse

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

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

الحقول

الحقول
`functionResponses[]`	`FunctionResponse` اختياريّ. تمثّل هذه السمة الردّ على استدعاءات الدوال.

functionResponses[]

FunctionResponse

اختياريّ. تمثّل هذه السمة الردّ على استدعاءات الدوال.

BidiGenerateContentTranscription

نص المحتوى الصوتي (المدخل أو الناتج)

الحقول

الحقول
`text`	`string` نص تحويل الصوت إلى نص

text

string

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

ContextWindowCompressionConfig

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

الحقول

الحقول
حقل الدمج `compressionMechanism` آلية ضغط نافذة السياق المستخدَمة يمكن أن تكون `compressionMechanism` إحدى القيم التالية فقط:
`slidingWindow`	`SlidingWindow` آلية النافذة المنزلقة
`triggerTokens`	`int64` عدد الرموز المميزة (قبل تنفيذ دورة) المطلوبة لتفعيل ضغط نافذة السياق يمكن استخدام هذه السمة لتحقيق التوازن بين الجودة ووقت الاستجابة، لأنّ قدرات الاستيعاب الأقصر قد تؤدي إلى استجابات أسرع من النموذج. ومع ذلك، ستؤدي أي عملية ضغط إلى زيادة مؤقتة في وقت الاستجابة، لذلك يجب عدم تشغيلها بشكل متكرر. إذا لم يتم ضبطها، تكون القيمة التلقائية هي% 80 من الحد الأقصى لقدرة استيعاب النموذج. ويتبقى% 20 لطلب المستخدم التالي أو ردّ النموذج.

حقل الدمج 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. لن تقلّ هذه المدة عن الحدّ الأدنى الخاص بالنموذج، والذي سيتم تحديده مع حدود المعدّل للنموذج.

timeLeft

Duration

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

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

ProactivityConfig

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

الحقول

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

proactiveAudio

bool

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

RealtimeInputConfig

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

الحقول

الحقول
`automaticActivityDetection`	`AutomaticActivityDetection` اختياريّ. إذا لم يتم ضبط هذا الخيار، تكون ميزة "الرصد التلقائي للنشاط" مفعَّلة تلقائيًا. في حال إيقاف ميزة "الرصد التلقائي للصوت"، على العميل إرسال إشارات النشاط.
`activityHandling`	`ActivityHandling` اختياريّ. تحدّد هذه السمة تأثير النشاط.
`turnCoverage`	`TurnCoverage` اختياريّ. تحدّد هذه السمة الإدخال الذي يتم تضمينه في رد المستخدم.

automaticActivityDetection

AutomaticActivityDetection

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

activityHandling

ActivityHandling

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

turnCoverage

TurnCoverage

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

SessionResumptionConfig

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

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

الحقول

الحقول
`handle`	`string` معرّف جلسة سابقة. إذا لم يكن متوفّرًا، يتم إنشاء جلسة جديدة. تأتي معرّفات الجلسات من قيم `SessionResumptionUpdate.token` في عمليات الربط السابقة.

handle

string

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

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

SessionResumptionUpdate

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

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

الحقول

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

newHandle

string

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

resumable

bool

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

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

SlidingWindow

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

الحقول

الحقول
`targetTokens`	`int64` عدد الرموز المميزة المستهدَفة التي يجب الاحتفاظ بها. القيمة التلقائية هي trigger_tokens/2. يؤدي تجاهل أجزاء من قدرة الاستيعاب إلى زيادة مؤقتة في وقت الاستجابة، لذا يجب ضبط هذه القيمة لتجنُّب عمليات الضغط المتكرّرة.

targetTokens

int64

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

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

StartSensitivity

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

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

TurnCoverage

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

عمليات التعداد
`TURN_COVERAGE_UNSPECIFIED`	إذا لم يتم تحديد ذلك، يكون السلوك التلقائي هو `TURN_INCLUDES_ONLY_ACTIVITY`.
`TURN_INCLUDES_ONLY_ACTIVITY`	يتضمّن دور المستخدم النشاط منذ آخر دور، باستثناء عدم النشاط (مثل الصمت في بث الصوت). هذا هو السلوك التلقائي.
`TURN_INCLUDES_ALL_INPUT`	يتضمّن دور المستخدم جميع المدخلات في الوقت الفعلي منذ الدور الأخير، بما في ذلك عدم النشاط (مثل الصمت في بث الصوت).

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، أو في عنوان Authorization لبروتوكول HTTP مع إضافة البادئة "Token" إليه.

CreateAuthTokenRequest

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

الحقول

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

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` في هذا الطلب. يتم تجاهل رسالة الإعداد من اتصال Live API. إذا لم يكن field_mask فارغًا، ستؤدي الحقول المقابلة من `bidiGenerateContentSetup` إلى الكتابة فوق الحقول من رسالة الإعداد في عملية الربط المباشر بواجهة برمجة التطبيقات.
حقل الدمج `config` إعدادات خاصة بطريقة الحصول على الرمز المميز الناتج. يمكن أن تكون `config` إحدى القيم التالية فقط:
`bidiGenerateContentSetup`	`BidiGenerateContentSetup` اختياريّ. الإدخال فقط غير قابل للتغيير إعدادات خاصة بـ `BidiGenerateContent`
`uses`	`int32` اختياريّ. الإدخال فقط غير قابل للتغيير عدد المرات التي يمكن فيها استخدام الرمز المميّز إذا كانت هذه القيمة صفرًا، لن يتم تطبيق أي حدّ. لا يُحتسب استئناف جلسة Live API كاستخدام. إذا لم يتم تحديد قيمة، تكون القيمة التلقائية هي 1.

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

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