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
}

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

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

پیام توضیحات
BidiGenerateContentSetup تنظیمات جلسه در اولین پیام ارسال می شود
BidiGenerateContentClientContent به روز رسانی افزایشی محتوای مکالمه فعلی که از مشتری ارائه می شود
BidiGenerateContentRealtimeInput ورودی صوتی یا تصویری در زمان واقعی
BidiGenerateContentToolResponse پاسخ به ToolCallMessage دریافت شده از سرور

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

برای دریافت پیام از 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
}

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

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

پیام توضیحات
BidiGenerateContentSetupComplete یک پیام BidiGenerateContentSetup از مشتری که پس از تکمیل راه‌اندازی ارسال می‌شود
BidiGenerateContentServerContent محتوای تولید شده توسط مدل در پاسخ به پیام مشتری
BidiGenerateContentToolCall از مشتری درخواست کنید تا فراخوانی های تابع را اجرا کند و پاسخ ها را با شناسه های منطبق برگرداند
BidiGenerateContentToolCallCancellation زمانی ارسال می‌شود که یک تماس تابع به دلیل قطع شدن خروجی مدل توسط کاربر لغو شود

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

BidiGenerateContentClientContent

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

پیامی در اینجا هر نسل مدل فعلی را قطع می کند.

فیلدها
turns[]

Content

اختیاری. محتوا به مکالمه فعلی با مدل اضافه شده است.

برای پرس و جوهای تک نوبتی، این یک نمونه است. برای جستجوهای چند نوبتی، این یک فیلد تکراری است که حاوی تاریخچه مکالمه و آخرین درخواست است.

turn_ complete

bool

اختیاری. اگر درست باشد، نشان می دهد که تولید محتوای سرور باید با درخواست انباشته شده فعلی شروع شود. در غیر این صورت، سرور قبل از شروع تولید منتظر پیام های اضافی است.

BidiGenerateContentRealtimeInput

ورودی کاربر که در زمان واقعی ارسال می شود.

این از چند جهت با BidiGenerateContentClientContent متفاوت است:

  • می تواند به طور مداوم بدون وقفه به تولید مدل ارسال شود.
  • اگر نیاز به ترکیب داده‌های به هم پیوسته در BidiGenerateContentClientContent و BidiGenerateContentRealtimeInput وجود داشته باشد، سرور تلاش می‌کند تا بهترین پاسخ را بهینه کند، اما هیچ تضمینی وجود ندارد.
  • پایان نوبت به صراحت مشخص نشده است، بلکه بیشتر از فعالیت کاربر مشتق شده است (مثلاً پایان گفتار).
  • حتی قبل از پایان نوبت، داده ها به صورت تدریجی پردازش می شوند تا برای شروع سریع پاسخ از مدل بهینه شود.
  • همیشه به عنوان ورودی کاربر در نظر گرفته می شود (نمی توان از آن برای پر کردن تاریخچه مکالمه استفاده کرد). امکان ارسال مداوم و بدون وقفه مدل به طور خودکار شروع و پایان گفتار کاربر را تشخیص می‌دهد و بر این اساس جریان پاسخ را شروع یا خاتمه می‌دهد. داده ها با رسیدن به تدریج پردازش می شوند و تاخیر را به حداقل می رساند.
فیلدها
media_ chunks[]

Blob

اختیاری. داده بایت های خطی برای ورودی رسانه.

BidiGenerateContentServerContent

به روز رسانی افزایشی سرور که توسط مدل در پاسخ به پیام های مشتری ایجاد می شود.

محتوا در سریع ترین زمان ممکن و نه در زمان واقعی تولید می شود. مشتریان ممکن است انتخاب کنند که بافر کنند و آن را در زمان واقعی پخش کنند.

فیلدها
turn_ complete

bool

فقط خروجی اگر درست باشد، نشان می دهد که تولید مدل انجام شده است. تولید فقط در پاسخ به پیام های مشتری اضافی شروع می شود. می تواند در کنار content تنظیم شود، که نشان می دهد content در نوبت آخر است.

interrupted

bool

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

grounding_ metadata

GroundingMetadata

فقط خروجی متاداده پایه برای محتوای تولید شده.

model_ turn

Content

فقط خروجی محتوایی که مدل به عنوان بخشی از مکالمه فعلی با کاربر تولید کرده است.

BidiGenerateContentSetup

پیامی که باید در اولین و تنها اولین پیام مشتری ارسال شود. حاوی پیکربندی است که برای مدت جلسه پخش جریانی اعمال می شود.

مشتریان باید قبل از ارسال هرگونه پیام اضافی منتظر یک پیام BidiGenerateContentSetupComplete باشند.

فیلدها
model

string

مورد نیاز. نام منبع مدل این به عنوان شناسه ای برای استفاده از مدل عمل می کند.

قالب: models/{model}

generation_ config

GenerationConfig

اختیاری. پیکربندی نسل

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

  • responseLogprobs
  • responseMimeType
  • logprobs
  • responseSchema
  • stopSequence
  • routingConfig
  • audioTimestamp
system_ instruction

Content

اختیاری. کاربر دستورالعمل های سیستمی را برای مدل ارائه کرد.

توجه: فقط متن باید در قسمت ها استفاده شود. محتوای هر قسمت در یک پاراگراف جداگانه خواهد بود.

tools[]

Tool

اختیاری. فهرستی از Tools مدل ممکن است برای ایجاد پاسخ بعدی استفاده کند.

Tool قطعه ای از کد است که سیستم را قادر می سازد تا با سیستم های خارجی برای انجام یک عمل یا مجموعه ای از اقدامات خارج از دانش و محدوده مدل تعامل داشته باشد.

BidiGenerateContentSetupComplete

این نوع هیچ فیلدی ندارد.

در پاسخ به یک پیام BidiGenerateContentSetup از مشتری ارسال شد.

BidiGenerateContentToolCall

از کلاینت درخواست کنید تا فراخوانی های تابع را اجرا کند و پاسخ ها را با id منطبق برگرداند.

فیلدها
function_ calls[]

FunctionCall

فقط خروجی فراخوانی تابعی که باید اجرا شود.

BidiGenerateContentToolCallCancellation

اعلان برای مشتری مبنی بر اینکه یک ToolCallMessage قبلا صادر شده با id مشخص شده نباید اجرا شده باشد و باید لغو شود. اگر این تماس‌های ابزار عوارض جانبی داشت، مشتریان ممکن است تلاش کنند تا تماس‌های ابزار را لغو کنند. این پیام تنها در مواردی رخ می‌دهد که کلاینت‌ها چرخش سرور را قطع کنند.

فیلدها
ids[]

string

فقط خروجی شناسه‌های ابزار تماس‌های لغو می‌شوند.

BidiGenerateContentToolResponse

مشتری پاسخی به ToolCall دریافت شده از سرور ایجاد کرد. اشیاء فردی FunctionResponse با فیلد id با اشیاء FunctionCall مربوطه مطابقت داده می شوند.

توجه داشته باشید که در APIهای GenerateContent یکپارچه و جریان سرور، فراخوانی تابع با مبادله قسمت‌های Content انجام می‌شود، در حالی که در bidi GenerateContent API فراخوانی روی این مجموعه پیام‌های اختصاصی انجام می‌شود.

فیلدها
function_ responses[]

FunctionResponse

اختیاری. پاسخ به فراخوانی تابع.

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

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

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

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