Live API

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

يمكنك تجربة Live API في Google AI Studio.

الميزات الجديدة

تتضمّن واجهة برمجة التطبيقات Live API ميزات وإمكانات جديدة.

الإمكانات الجديدة:

• صوتان جديدان و30 لغة جديدة، مع إمكانية ضبط لغة الإخراج
• دقة الصور القابلة للضبط 66/256 رمزًا مميزًا
• تغطية قابلة للضبط: إرسال جميع الإدخالات طوال الوقت أو فقط عندما يتحدث العميل
• ضبط ما إذا كان يجب أن تقاطع الإدخال عمل النموذج أم لا
• ميزة "رصد التفاعل الصوتي مع الجهاز" القابلة للضبط وأحداث العميل الجديدة للإشارة إلى نهاية المحادثة
• أعداد الرموز المميّزة
• حدث العميل للإشارة إلى نهاية البث
• بث النص
• استئناف الجلسة القابل للضبط، مع تخزين بيانات الجلسة على الخادم لمدة 24 ساعة
• إتاحة جلسات أطول باستخدام نافذة سياق قابلة للانزلاق

أحداث العميل الجديدة:

• نهاية بث الصوت / الميكروفون مغلق
• أحداث بدء/إنهاء النشاط للتحكّم يدويًا في انتقال الانعطاف

أحداث الخادم الجديدة:

• إشعار يشير إلى ضرورة إعادة تشغيل جلسة
• اكتملت عملية الإنشاء

استخدام واجهة برمجة التطبيقات Live API

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

إرسال الرسائل النصية واستلامها

import asyncio
from google import genai

client = genai.Client(api_key="GEMINI_API_KEY")
model = "gemini-2.0-flash-live-001"

config = {"response_modalities": ["TEXT"]}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        while True:
            message = input("User> ")
            if message.lower() == "exit":
                break
            await session.send_client_content(
                turns={"role": "user", "parts": [{"text": message}]}, turn_complete=True
            )

            async for response in session.receive():
                if response.text is not None:
                    print(response.text, end="")

if __name__ == "__main__":
    asyncio.run(main())

تلقّي الصوت

يوضّح المثال التالي كيفية تلقّي بيانات صوتية وكتابتها في ملف .wav.

import asyncio
import wave
from google import genai

client = genai.Client(api_key="GEMINI_API_KEY", http_options={'api_version': 'v1alpha'})
model = "gemini-2.0-flash-live-001"

config = {"response_modalities": ["AUDIO"]}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        wf = wave.open("audio.wav", "wb")
        wf.setnchannels(1)
        wf.setsampwidth(2)
        wf.setframerate(24000)

        message = "Hello? Gemini are you there?"
        await session.send_client_content(
            turns={"role": "user", "parts": [{"text": message}]}, turn_complete=True
        )

        async for idx,response in async_enumerate(session.receive()):
            if response.data is not None:
                wf.writeframes(response.data)

            # Un-comment this code to print audio data info
            # if response.server_content.model_turn is not None:
            #      print(response.server_content.model_turn.parts[0].inline_data.mime_type)

        wf.close()

if __name__ == "__main__":
    asyncio.run(main())

تنسيقات الصوت

تتيح واجهة برمجة التطبيقات Live API تنسيقات الصوت التالية:

• تنسيق الصوت الذي يتم إدخاله: صوت PCM خام بترميز 16 بت بمعدّل 16 كيلوهرتز بترتيب الوحدات الأقل أهمية أولاً
• تنسيق الصوت الذي يتم إخراجه: صوت PCM خام بترميز 16 بت بمعدّل 24 كيلوهرتز بترتيب الوحدات الأقل أهمية أولاً

بث الصوت والفيديو

تعليمات النظام

تتيح لك تعليمات النظام توجيه سلوك النموذج استنادًا إلى احتياجاتك وحالات الاستخدام المحدّدة. يمكن ضبط تعليمات النظام في إعدادات الإعداد وستظل سارية طوال الجلسة.

from google.genai import types

config = {
    "system_instruction": types.Content(
        parts=[
            types.Part(
                text="You are a helpful assistant and answer in a friendly tone."
            )
        ]
    ),
    "response_modalities": ["TEXT"],
}

تعديلات المحتوى المتزايدة

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

turns = [
    {"role": "user", "parts": [{"text": "What is the capital of France?"}]},
    {"role": "model", "parts": [{"text": "Paris"}]},
]

await session.send_client_content(turns=turns, turn_complete=False)

turns = [{"role": "user", "parts": [{"text": "What is the capital of Germany?"}]}]

await session.send_client_content(turns=turns, turn_complete=True)

{
  "clientContent": {
    "turns": [
      {
        "parts":[
          {
            "text": ""
          }
        ],
        "role":"user"
      },
      {
        "parts":[
          {
            "text": ""
          }
        ],
        "role":"model"
      }
    ],
    "turnComplete": true
  }
}

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

تغيير الأصوات

تتيح واجهة برمجة التطبيقات Live API الأصوات التالية: Puck وCharon وKore وFenrir وAoede وLeda وOrus وZephyr.

لتحديد صوت، اضبط اسم الصوت ضمن عنصر speechConfig كجزء من إعدادات الجلسة:

from google.genai import types

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    speech_config=types.SpeechConfig(
        voice_config=types.VoiceConfig(
            prebuilt_voice_config=types.PrebuiltVoiceConfig(voice_name="Kore")
        )
    )
)

{
  "voiceConfig": {
    "prebuiltVoiceConfig": {
      "voiceName": "Kore"
    }
  }
}

استخدام استدعاء الدالة

يمكنك تحديد الأدوات باستخدام Live API. اطّلِع على الدليل التعليمي لاستدعاء الدوالّ للحصول على مزيد من المعلومات عن استدعاء الدوالّ.

يجب تحديد الأدوات كجزء من إعداد الجلسة:

config = types.LiveConnectConfig(
    response_modalities=["TEXT"],
    tools=[set_light_values]
)

async with client.aio.live.connect(model=model, config=config) as session:
    await session.send_client_content(
        turns={
            "role": "user",
            "parts": [{"text": "Turn the lights down to a romantic level"}],
        },
        turn_complete=True,
    )

    async for response in session.receive():
        print(response.tool_call)

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

يجب أن يردّ العميل باستخدام BidiGenerateContentToolResponse.

تؤثر مصادر إدخال الصوت ومصادر إخراج الصوت سلبًا في قدرة النموذج على استخدام طلبات الدالة.

التعامل مع المقاطعات

يمكن للمستخدمين إيقاف إخراج النموذج في أي وقت. عندما يرصد نظام رصد أنشطة التعرّف على الصوت (VAD) انقطاعًا، يتم إلغاء عملية التعرّف الجارية ووضعها في المهملات. لا يتم الاحتفاظ في سجلّ الجلسات إلا بالمعلومات التي تم إرسالها إلى العميل من قبل. يُرسِل الخادم بعد ذلك رسالة BidiGenerateContentServerContent لتسجيل انقطاع الاتصال.

بالإضافة إلى ذلك، يتخلّص خادم Gemini من أيّ طلبات وظائف في انتظار المراجعة ويُرسِل رسالة BidiGenerateContentServerContent تتضمّن أرقام تعريف المكالمات المُلغاة.

async for response in session.receive():
    if response.server_content.interrupted is not None:
        # The generation was interrupted

ضبط ميزة "رصد النشاط الصوتي" (VAD)

ويعمل النموذج تلقائيًا على رصد النشاط الصوتي (VAD) في بث صوتي مستمر. يمكن ضبط ميزة "توقُّف الصوت أثناء الصمت" باستخدام الحقل realtimeInputConfig.automaticActivityDetection إعداد الضبط.

عند إيقاف بث الصوت مؤقتًا لأكثر من ثانية (على سبيل المثال، بسبب إيقاف المستخدم للميكروفون)، يجب إرسال حدث audioStreamEnd لحذف أي صوت محفوظ مؤقتًا. يمكن للعميل استئناف إرسال data الصوتية في أي وقت.

بدلاً من ذلك، يمكن إيقاف ميزة "توقُّف الصوت التلقائي" عن طريق ضبط realtimeInputConfig.automaticActivityDetection.disabled على true في رسالة الإعداد. في هذه الإعدادات، يكون العميل مسؤولاً عن رصد حديث المستخدم وإرسال رسائل activityStart وactivityEnd في الأوقات المناسبة. لا يتم إرسال audioStreamEnd في هذه الإعدادات. بدلاً من ذلك، يتم وضع علامة على أي انقطاع في البث باستخدام رسالة activityEnd.

ستتوفّر هذه الميزة في حِزم تطوير البرامج (SDK) خلال الأسابيع المقبلة.

الحصول على عدد الرموز المميّزة

يمكنك العثور على إجمالي عدد الرموز المستهلكة في الحقل usageMetadata لرسالة الخادم المعروضة.

from google.genai import types

async with client.aio.live.connect(
    model='gemini-2.0-flash-live-001',
    config=types.LiveConnectConfig(
        response_modalities=['AUDIO'],
    ),
) as session:
    # Session connected
    while True:
        await session.send_client_content(
            turns=types.Content(role='user', parts=[types.Part(text='Hello world!')])
        )
        async for message in session.receive():
            # The server will periodically send messages that include
            # UsageMetadata.
            if message.usage_metadata:
                usage = message.usage_metadata
                print(
                    f'Used {usage.total_token_count} tokens in total. Response token'
                    ' breakdown:'
                )
            for detail in usage.response_tokens_details:
                match detail:
                  case types.ModalityTokenCount(modality=modality, token_count=count):
                      print(f'{modality}: {count}')

            # 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

ضبط استئناف الجلسة

لمنع إنهاء الجلسة عندما يعيد الخادم ضبط اتصال WebSocket بشكل دوري، عليك ضبط الحقل sessionResumption ضمن إعدادات الإعداد.

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

from google.genai import types

print(f"Connecting to the service with handle {previous_session_handle}...")
async with client.aio.live.connect(
    model="gemini-2.0-flash-live-001",
    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:
    # Session connected
    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

تلقّي رسالة قبل انقطاع الاتصال بالجلسة

يُرسِل الخادم رسالة GoAway التي تشير إلى أنّه سيتم قريبًا إنهاء الربط الحالي. تتضمّن هذه الرسالة timeLeft، التي تشير إلى الوقت المتبقّي وتتيح لك اتّخاذ إجراء آخر قبل إنهاء الاتصال على أنّه تم إلغاؤه.

تلقّي رسالة عند اكتمال عملية الإنشاء

يُرسِل الخادم رسالة generationComplete تشير إلى أنّ النموذج قد أنهى إنشاء الاستجابة.

تفعيل ضغط نافذة السياق

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

في ContextWindowCompressionConfig، يمكنك ضبط آلية النافذة المتحركة وعدد الرموز المميّزة التي تؤدي إلى بدء الضغط.

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(),
        )
    ),
)

تغيير درجة دقة الوسائط

يمكنك تحديد درجة دقة الوسائط لوسائط الإدخال من خلال ضبط الحقل mediaResolution كجزء من إعدادات الجلسة:

from google.genai import types

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    media_resolution=types.MediaResolution.MEDIA_RESOLUTION_LOW,
)

القيود

ضَع في اعتبارك القيود التالية في Live API وGemini 2.0 عند التخطيط لمشروعك.

مصادقة العميل

لا توفّر واجهة برمجة التطبيقات Live API سوى مصادقة بين الخوادم ولا يُنصح باستخدامها مباشرةً من قِبل العميل. يجب توجيه إدخال العميل من خلال خادم تطبيق وسيط للمصادقة الآمنة باستخدام واجهة برمجة التطبيقات Live API.

مدة الجلسة

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

قدرة الاستيعاب

تبلغ قدرة استيعاب الجلسة 32 ألف رمز مميّز.

عمليات الدمج مع منتجات تابعة لجهات خارجية

بالنسبة إلى عمليات نشر تطبيقات الويب والتطبيقات المتوافقة مع الأجهزة الجوّالة، يمكنك استكشاف الخيارات من:

• يوميًا
• Livekit