Multimodal Live API

Multimodal Live API تعامل صوتی و تصویری دو جهته با تأخیر کم با Gemini را امکان پذیر می کند. با استفاده از Multimodal Live API، می‌توانید تجربه مکالمات صوتی طبیعی و شبیه انسان را در اختیار کاربران نهایی قرار دهید و با استفاده از دستورات صوتی، پاسخ‌های مدل را قطع کنید. این مدل می تواند ورودی متن، صدا و تصویر را پردازش کند و می تواند متن و خروجی صدا را ارائه دهد.

می‌توانید Multimodal Live API را در Google AI Studio امتحان کنید.

از Multimodal Live API استفاده کنید

این بخش نحوه استفاده از Multimodal Live API با یکی از SDK های ما را شرح می دهد. برای اطلاعات بیشتر در مورد WebSockets API اساسی، به مرجع WebSockets API در زیر مراجعه کنید.

ارسال و دریافت متن

import asyncio
from google import genai

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

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(input=message, end_of_turn=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-exp"

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(input=message, end_of_turn=True)

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

            # Comment this out 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())

فرمت های صوتی

Multimodal Live API از فرمت های صوتی زیر پشتیبانی می کند:

• فرمت صوتی ورودی: صدای خام 16 بیتی PCM با فرکانس 16 کیلوهرتز کمی اندین
• فرمت صدای خروجی: صدای خام 16 بیتی PCM با فرکانس 24 کیلوهرتز کمی endian

پخش صدا و تصویر

دستورالعمل های سیستم

دستورالعمل های سیستم به شما امکان می دهد رفتار یک مدل را بر اساس نیازهای خاص و موارد استفاده خود هدایت کنید. دستورالعمل‌های سیستم را می‌توان در پیکربندی راه‌اندازی تنظیم کرد و برای کل جلسه قابل اجرا خواهد بود.

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"],
}

به روز رسانی افزایشی محتوا

از به‌روزرسانی‌های افزایشی برای ارسال ورودی متن، ایجاد زمینه جلسه یا بازیابی بافت جلسه استفاده کنید. برای زمینه‌های کوتاه، می‌توانید تعاملات گام به گام را برای نشان دادن توالی دقیق رویدادها ارسال کنید:

from google.genai import types

turns = [
    types.Content(parts=[types.Part(text="What is the capital of France?")], role="user"),
    types.Content(parts=[types.Part(text="Paris")], role="model")
]
await session.send(input=types.LiveClientContent(turns=turns))

turns = [types.Content(parts=[types.Part(text="What is the capital of Germany?")], role="user")]
await session.send(input=types.LiveClientContent(turns=turns, turn_complete=True))

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

برای زمینه‌های طولانی‌تر، توصیه می‌شود یک خلاصه پیام واحد ارائه کنید تا پنجره زمینه برای تعاملات بعدی آزاد شود.

صداها را تغییر دهید

Multimodal Live API از صداهای زیر پشتیبانی می کند: Aoede، Charon، Fenrir، Kore و Puck.

برای تعیین یک صدا، نام صدا را در شی 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"
    }
  }
}

از فراخوانی تابع استفاده کنید

می توانید ابزارها را با Multimodal 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(input="Turn the lights down to a romantic level", end_of_turn=True)

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

از یک اعلان واحد، مدل می تواند چندین فراخوانی تابع و کدهای لازم برای زنجیره خروجی های آنها را ایجاد کند. این کد در محیط sandbox اجرا می شود و پیام های BidiGenerateContentToolCall بعدی را ایجاد می کند. اجرا متوقف می شود تا زمانی که نتایج هر فراخوانی در دسترس باشد، که پردازش متوالی را تضمین می کند.

مشتری باید با BidiGenerateContentToolResponse پاسخ دهد.

ورودی‌ها و خروجی‌های صوتی بر توانایی مدل برای استفاده از فراخوانی تابع تأثیر منفی می‌گذارند.

وقفه ها را مدیریت کنید

کاربران می توانند خروجی مدل را در هر زمانی قطع کنند. هنگامی که تشخیص فعالیت صوتی (VAD) یک وقفه را تشخیص می‌دهد، تولید در حال انجام لغو و کنار گذاشته می‌شود. فقط اطلاعاتی که قبلاً برای مشتری ارسال شده است در تاریخچه جلسه حفظ می شود. سپس سرور یک پیام BidiGenerateContentServerContent برای گزارش وقفه ارسال می کند.

بعلاوه، سرور Gemini هرگونه تماس تابع معلق را کنار می گذارد و یک پیام BidiGenerateContentServerContent با شناسه تماس های لغو شده ارسال می کند.

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

محدودیت ها

هنگام برنامه ریزی پروژه خود، محدودیت های زیر را برای Multimodal Live API و Gemini 2.0 در نظر بگیرید.

احراز هویت مشتری

Multimodal Live API فقط احراز هویت سرور به سرور را ارائه می دهد و برای استفاده مستقیم از مشتری توصیه نمی شود. ورودی مشتری باید از طریق یک سرور برنامه میانی برای احراز هویت ایمن با Multimodal Live API هدایت شود.

تاریخچه مکالمه

در حالی که مدل تعاملات درون جلسه را پیگیری می کند، تاریخچه مکالمه ذخیره نمی شود. هنگامی که یک جلسه به پایان می رسد، زمینه مربوطه پاک می شود.

به منظور بازیابی یک جلسه قبلی یا ارائه مدل با بافت تاریخی تعاملات کاربر، برنامه باید گزارش مکالمه خود را حفظ کند و از یک پیام BidiGenerateContentClientContent برای ارسال این اطلاعات در شروع جلسه جدید استفاده کند.

حداکثر مدت زمان جلسه

مدت زمان جلسه تا 15 دقیقه برای صدا یا حداکثر 2 دقیقه صدا و تصویر محدود شده است. هنگامی که مدت زمان جلسه از حد مجاز بیشتر شود، اتصال قطع می شود.

مدل نیز با اندازه زمینه محدود شده است. ارسال تکه های بزرگ محتوا در کنار جریان های ویدیویی و صوتی ممکن است منجر به خاتمه زودتر جلسه شود.

تشخیص فعالیت صوتی (VAD)

این مدل به طور خودکار تشخیص فعالیت صوتی (VAD) را در جریان ورودی صوتی پیوسته انجام می دهد. VAD همیشه فعال است و پارامترهای آن قابل تنظیم نیستند.

شمارش توکن

شمارش رمز پشتیبانی نمی شود.

محدودیت های نرخ

محدودیت های نرخ زیر اعمال می شود:

• 3 جلسه همزمان در هر کلید API
• 4 میلیون توکن در دقیقه

مرجع WebSockets API

Multimodal Live API یک API حالت دار است که از WebSockets استفاده می کند. در این بخش، جزئیات بیشتری در مورد WebSockets API خواهید یافت.

جلسات

یک اتصال WebSocket یک جلسه بین مشتری و سرور Gemini برقرار می کند. پس از اینکه یک کلاینت یک اتصال جدید را آغاز کرد، جلسه می تواند پیام هایی را با سرور مبادله کند:

• متن، صدا یا ویدیو را به سرور جمینی ارسال کنید.
• درخواست‌های تماس صوتی، متنی یا عملکردی را از سرور Gemini دریافت کنید.

پیام اولیه پس از اتصال، پیکربندی جلسه را تنظیم می کند که شامل مدل، پارامترهای تولید، دستورالعمل های سیستم و ابزارها می شود.

پیکربندی مثال زیر را ببینید. توجه داشته باشید که پوشش نام در SDK ممکن است متفاوت باشد. می‌توانید گزینه‌های پیکربندی Python SDK را در اینجا جستجو کنید.

{
  "model": string,
  "generationConfig": {
    "candidateCount": integer,
    "maxOutputTokens": integer,
    "temperature": number,
    "topP": number,
    "topK": integer,
    "presencePenalty": number,
    "frequencyPenalty": number,
    "responseModalities": [string],
    "speechConfig": object
  },
  "systemInstruction": string,
  "tools": [object]
}

ارسال پیام

برای تبادل پیام از طریق اتصال WebSocket، مشتری باید یک شی JSON را از طریق اتصال WebSocket باز ارسال کند. شی JSON باید دقیقاً یکی از فیلدهای مجموعه اشیاء زیر را داشته باشد:

{
  "setup": BidiGenerateContentSetup,
  "clientContent": BidiGenerateContentClientContent,
  "realtimeInput": BidiGenerateContentRealtimeInput,
  "toolResponse": BidiGenerateContentToolResponse
}

پیام های مشتری پشتیبانی شده

پیام های مشتری پشتیبانی شده را در جدول زیر ببینید:

پیام ها را دریافت کنید

برای دریافت پیام از Gemini، به رویداد "پیام" WebSocket گوش دهید و سپس نتیجه را مطابق با تعریف پیام های سرور پشتیبانی شده تجزیه کنید.

موارد زیر را ببینید:

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)

پیام های سرور دقیقاً یکی از فیلدهای مجموعه اشیاء زیر را خواهند داشت:

{
  "setupComplete": BidiGenerateContentSetupComplete,
  "serverContent": BidiGenerateContentServerContent,
  "toolCall": BidiGenerateContentToolCall,
  "toolCallCancellation": BidiGenerateContentToolCallCancellation
}

پیام های سرور پشتیبانی شده

پیام های سرور پشتیبانی شده را در جدول زیر مشاهده کنید:

پیام ها و رویدادها

اطلاعات بیشتر در مورد انواع رایج

برای اطلاعات بیشتر در مورد انواع منابع API رایج Blob ، Content ، FunctionCall ، FunctionResponse ، GenerationConfig ، GroundingMetadata و Tool ، به تولید محتوا مراجعه کنید.

ادغام های شخص ثالث

برای استقرار برنامه های وب و تلفن همراه، می توانید گزینه های زیر را بررسی کنید:

• روزانه
• Livekit