في Live API، تشير الجلسة إلى اتصال دائم يتم فيه بث البيانات المدخلة والمخرجة بشكل مستمر عبر الاتصال نفسه (مزيد من المعلومات حول طريقة عمله). يتيح تصميم الجلسة الفريد هذا وقت استجابة منخفضًا ويدعم ميزات فريدة، ولكن يمكن أن يطرح أيضًا تحديات، مثل حدود وقت الجلسة والإنهاء المبكر. يغطّي هذا الدليل استراتيجيات للتغلّب على التحديات المتعلقة بإدارة الجلسات التي قد تنشأ عند استخدام Live API.
مدة الجلسة
بدون ضغط، تقتصر مدة الجلسات الصوتية فقط على 15 دقيقة، بينما تقتصر مدة الجلسات الصوتية والمرئية على دقيقتين. سيؤدي تجاوز هذه الحدود إلى إنهاء الجلسة (وبالتالي، الاتصال)، ولكن يمكنك استخدام ضغط نافذة السياق لتمديد الجلسات إلى مدة غير محدودة.
مدة صلاحية الاتصال محدودة أيضًا، وتبلغ حوالي 10 دقائق. وعند انتهاء الاتصال، تنتهي الجلسة أيضًا. في هذه الحالة، يمكنك ضبط جلسة واحدة لتبقى نشطة على مدار اتصالات متعددة باستخدام استئناف الجلسة. ستتلقّى أيضًا رسالة GoAway قبل انتهاء الاتصال، ما يتيح لك اتّخاذ المزيد من الإجراءات.
ضغط قدرة الاستيعاب
لإتاحة جلسات أطول وتجنُّب إنهاء الاتصال بشكل مفاجئ، يمكنك تفعيل ميزة "ضغط نافذة السياق" من خلال ضبط الحقل contextWindowCompression كجزء من إعدادات الجلسة.
في ContextWindowCompressionConfig، يمكنك ضبط آلية النافذة المنزلقة وعدد الرموز المميزة الذي يؤدي إلى بدء عملية الضغط.
Python
from google.genai import types
config = types.LiveConnectConfig(
response_modalities=["AUDIO"],
context_window_compression=(
# Configures compression with default parameters.
types.ContextWindowCompressionConfig(
sliding_window=types.SlidingWindow(),
)
),
)
JavaScript
const config = {
responseModalities: [Modality.AUDIO],
contextWindowCompression: { slidingWindow: {} }
};
استئناف الجلسة
لمنع إنهاء الجلسة عندما يعيد الخادم ضبط اتصال WebSocket بشكل دوري، اضبط الحقل sessionResumption ضمن إعدادات الإعداد.
يؤدي تمرير هذا الإعداد إلى أن يرسل الخادم رسائل SessionResumptionUpdate، والتي يمكن استخدامها لاستئناف الجلسة من خلال تمرير رمز الاستئناف الأخير كـ SessionResumptionConfig.handle
للاتصال اللاحق.
تكون رموز الاستئناف صالحة لمدة ساعتين بعد انتهاء الجلسات الأخيرة.
Python
import asyncio
from google import genai
from google.genai import types
client = genai.Client()
model = "gemini-live-2.5-flash-preview"
async def main():
print(f"Connecting to the service with handle {previous_session_handle}...")
async with client.aio.live.connect(
model=model,
config=types.LiveConnectConfig(
response_modalities=["AUDIO"],
session_resumption=types.SessionResumptionConfig(
# The handle of the session to resume is passed here,
# or else None to start a new session.
handle=previous_session_handle
),
),
) as session:
while True:
await session.send_client_content(
turns=types.Content(
role="user", parts=[types.Part(text="Hello world!")]
)
)
async for message in session.receive():
# Periodically, the server will send update messages that may
# contain a handle for the current state of the session.
if message.session_resumption_update:
update = message.session_resumption_update
if update.resumable and update.new_handle:
# The handle should be retained and linked to the session.
return update.new_handle
# For the purposes of this example, placeholder input is continually fed
# to the model. In non-sample code, the model inputs would come from
# the user.
if message.server_content and message.server_content.turn_complete:
break
if __name__ == "__main__":
asyncio.run(main())
JavaScript
import { GoogleGenAI, Modality } from '@google/genai';
const ai = new GoogleGenAI({});
const model = 'gemini-live-2.5-flash-preview';
async function live() {
const responseQueue = [];
async function waitMessage() {
let done = false;
let message = undefined;
while (!done) {
message = responseQueue.shift();
if (message) {
done = true;
} else {
await new Promise((resolve) => setTimeout(resolve, 100));
}
}
return message;
}
async function handleTurn() {
const turns = [];
let done = false;
while (!done) {
const message = await waitMessage();
turns.push(message);
if (message.serverContent && message.serverContent.turnComplete) {
done = true;
}
}
return turns;
}
console.debug('Connecting to the service with handle %s...', previousSessionHandle)
const session = await ai.live.connect({
model: model,
callbacks: {
onopen: function () {
console.debug('Opened');
},
onmessage: function (message) {
responseQueue.push(message);
},
onerror: function (e) {
console.debug('Error:', e.message);
},
onclose: function (e) {
console.debug('Close:', e.reason);
},
},
config: {
responseModalities: [Modality.TEXT],
sessionResumption: { handle: previousSessionHandle }
// The handle of the session to resume is passed here, or else null to start a new session.
}
});
const inputTurns = 'Hello how are you?';
session.sendClientContent({ turns: inputTurns });
const turns = await handleTurn();
for (const turn of turns) {
if (turn.sessionResumptionUpdate) {
if (turn.sessionResumptionUpdate.resumable && turn.sessionResumptionUpdate.newHandle) {
let newHandle = turn.sessionResumptionUpdate.newHandle
// ...Store newHandle and start new session with this handle here
}
}
}
session.close();
}
async function main() {
await live().catch((e) => console.error('got error', e));
}
main();
تلقّي رسالة قبل قطع الاتصال بالجلسة
يرسل الخادم رسالة GoAway تشير إلى أنّه سيتم إنهاء الاتصال الحالي قريبًا. تتضمّن هذه الرسالة الحقل timeLeft، الذي يشير إلى الوقت المتبقي، ويتيح لك اتّخاذ إجراء إضافي قبل إنهاء الاتصال على أنّه ABORTED.
Python
async for response in session.receive():
if response.go_away is not None:
# The connection will soon be terminated
print(response.go_away.time_left)
JavaScript
const turns = await handleTurn();
for (const turn of turns) {
if (turn.goAway) {
console.debug('Time left: %s\n', turn.goAway.timeLeft);
}
}
تلقّي رسالة عند اكتمال عملية الإنشاء
يرسل الخادم رسالة generationComplete تشير إلى أنّ النموذج انتهى من إنشاء الردّ.
Python
async for response in session.receive():
if response.server_content.generation_complete is True:
# The generation is complete
JavaScript
const turns = await handleTurn();
for (const turn of turns) {
if (turn.serverContent && turn.serverContent.generationComplete) {
// The generation is complete
}
}
الخطوات التالية
يمكنك استكشاف المزيد من الطرق لاستخدام Live API في دليل الإمكانات الكامل أو صفحة استخدام الأدوات أو كتاب وصفات Live API.