إدارة الجلسات في Live API

تعالج Gemini Live API بشكل مستمر تدفقات الصوت أو النص التي تُعرف باسم الجلسات. يمكنك إدارة مراحل نشاط الجلسة، بدءًا من المصافحة الأولية وحتى الإنهاء السلس.

حدود الجلسات

بالنسبة إلى Live API، تشير الجلسة إلى اتصال دائم يتم فيه بث البيانات المدخلة والمخرجة باستمرار عبر الاتصال نفسه.

إذا تجاوزت الجلسة أيًا من الحدود التالية، سيتم إنهاء الاتصال.

  • تقتصر مدة الاتصال على 10 دقائق تقريبًا.

  • تعتمد مدة الجلسة على طرق الإدخال التالية:

    • تقتصر مدة جلسات الإدخال الصوتي فقط على 15 دقيقة.
    • تقتصر مدة الفيديو والصوت على دقيقتَين.
  • تقتصر قدرة الاستيعاب المستندة إلى سياق الجلسة على 128 ألف رمز مميز.

ستتلقّى إشعارًا بإيقاف الميزة قبل انتهاء الربط، ما يتيح لك اتّخاذ إجراءات إضافية.

بدء جلسة

يمكنك الانتقال إلى دليل البدء في Live API للحصول على مقتطف كامل يوضّح كيفية بدء جلسة.

تعديل أثناء الجلسة

تتيح نماذج Live API الإمكانات المتقدّمة التالية للتعديلات أثناء الجلسة:

إضافة تعديلات تدريجية على المحتوى

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

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

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

Swift

// Define initial turns (history/context).
let turns: [ModelContent] = [
  ModelContent(role: "user", parts: [TextPart("What is the capital of France?")]),
  ModelContent(role: "model", parts: [TextPart("Paris")]),
]

// Send history, keeping the conversational turn OPEN (false).
await session.sendContent(turns, turnComplete: false)

// Define the new user query.
let newTurn: [ModelContent] = [
  ModelContent(role: "user", parts: [TextPart("What is the capital of Germany?")]),
]

// Send the final query, CLOSING the turn (true) to trigger the model response.
await session.sendContent(newTurn, turnComplete: true)

Kotlin

Not yet supported for Android apps - check back soon!

Java

Not yet supported for Android apps - check back soon!

Web

const turns = [{ text: "Hello from the user!" }];

await session.send(
  turns,
  false // turnComplete: false
);

console.log("Sent history. Waiting for next input...");

// Define the new user query.
const newTurn [{ text: "And what is the capital of Germany?" }];

// Send the final query, CLOSING the turn (true) to trigger the model response.
await session.send(
    newTurn,
    true // turnComplete: true
);
console.log("Sent final query. Model response expected now.");

Dart

// Define initial turns (history/context).
final List turns = [
  Content(
    "user",
    [Part.text("What is the capital of France?")],
  ),
  Content(
    "model",
    [Part.text("Paris")],
  ),
];

// Send history, keeping the conversational turn OPEN (false).
await session.send(
  input: turns,
  turnComplete: false,
);

// Define the new user query.
final List newTurn = [
  Content(
    "user",
    [Part.text("What is the capital of Germany?")],
  ),
];

// Send the final query, CLOSING the turn (true) to trigger the model response.
await session.send(
  input: newTurn,
  turnComplete: true,
);

Unity

// Define initial turns (history/context).
List turns = new List {
    new ModelContent("user", new ModelContent.TextPart("What is the capital of France?") ),
    new ModelContent("model", new ModelContent.TextPart("Paris") ),
};

// Send history, keeping the conversational turn OPEN (false).
foreach (ModelContent turn in turns)
{
    await session.SendAsync(
        content: turn,
        turnComplete: false
    );
}

// Define the new user query.
ModelContent newTurn = ModelContent.Text("What is the capital of Germany?");

// Send the final query, CLOSING the turn (true) to trigger the model response.
await session.SendAsync(
    content: newTurn,
    turnComplete: true
);

تعديل تعليمات النظام أثناء الجلسة

لا تتوفّر هذه الميزة إلا عند استخدام Vertex AI Gemini API كموفّر لواجهة برمجة التطبيقات.

يمكنك تعديل تعليمات النظام أثناء جلسة نشطة. يمكنك استخدام هذا الخيار لتكييف ردود النموذج، مثلاً لتغيير لغة الردّ أو تعديل أسلوبه.

لتعديل تعليمات النظام في منتصف الجلسة، يمكنك إرسال محتوى نصي باستخدام الدور system. ستبقى تعليمات النظام المعدَّلة سارية طوال المدة المتبقية من الجلسة.

Swift

await session.sendContent(
  [ModelContent(
    role: "system",
    parts: [TextPart("new system instruction")]
  )],
  turnComplete: false
)

Kotlin

Not yet supported for Android apps - check back soon!

Java

Not yet supported for Android apps - check back soon!

Web

Not yet supported for Web apps - check back soon!

Dart

try {
  await _session.send(
    input: Content(
      'system',
      [Part.text('new system instruction')],
    ),
    turnComplete: false,
  );
} catch (e) {
  print('Failed to update system instructions: $e');
}

Unity

try
{
    await session.SendAsync(
        content: new ModelContent(
            "system",
            new ModelContent.TextPart("new system instruction")
        ),
        turnComplete: false
    );
}
catch (Exception e)
{
    Debug.LogError($"Failed to update system instructions: {e.Message}");
}

رصد وقت انتهاء الجلسة

يتم إرسال إشعار بالإغلاق إلى العميل قبل 60 ثانية من انتهاء الجلسة، ما يتيح لك اتّخاذ إجراءات إضافية.

يوضّح المثال التالي كيفية رصد إنهاء الجلسة الوشيك من خلال الاستماع إلى إشعار going away:

Swift

for try await response in session.responses {
  switch response.payload {

  case .goingAwayNotice(let goingAwayNotice):
    // Prepare for the session to close soon
    if let timeLeft = goingAwayNotice.timeLeft {
        print("Server going away in \(timeLeft) seconds")
    }
  }
}

Kotlin

for (response in session.responses) {
    when (val message = response.payload) {
        is LiveServerGoAway -> {
            // Prepare for the session to close soon
            val remaining = message.timeLeft
            logger.info("Server going away in $remaining")
        }
    }
}

Java

session.getResponses().forEach(response -> {
    if (response.getPayload() instanceof LiveServerResponse.GoingAwayNotice) {
        LiveServerResponse.GoingAwayNotice notice = (LiveServerResponse.GoingAwayNotice) response.getPayload();
        // Prepare for the session to close soon
        Duration timeLeft = notice.getTimeLeft();
    }
});

Web

for await (const message of session.receive()) {
  switch (message.type) {

  ...
  case "goingAwayNotice":
    console.log("Server going away. Time left:", message.timeLeft);
    break;
  }
}

Dart

Future _handleLiveServerMessage(LiveServerResponse response) async {
  final message = response.message;
  if (message is GoingAwayNotice) {
     // Prepare for the session to close soon
     developer.log('Server going away. Time left: ${message.timeLeft}');
  }
}

Unity

foreach (var response in session.Responses) {
    if (response.Payload is LiveSessionGoingAway notice) {
        // Prepare for the session to close soon
        TimeSpan timeLeft = notice.TimeLeft;
        Debug.Log($"Server going away notice received. Remaining: {timeLeft}");
    }
}