Multimodal Live API

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

قابلیت ها

Multimodal Live API شامل قابلیت های کلیدی زیر است:

  • چندوجهی: مدل می تواند ببیند، بشنود و صحبت کند.
  • تعامل زمان واقعی با تأخیر کم: پاسخ های سریعی را ارائه می دهد.
  • حافظه جلسه: مدل تمام تعاملات را در یک جلسه حفظ می کند و اطلاعات شنیده شده یا دیده شده قبلی را به خاطر می آورد.
  • پشتیبانی از فراخوانی تابع، اجرای کد و جستجو به عنوان یک ابزار: ادغام با سرویس های خارجی و منابع داده را فعال می کند.
  • تشخیص خودکار فعالیت صوتی (VAD): این مدل می تواند به دقت تشخیص دهد که کاربر چه زمانی صحبت را شروع می کند و چه زمانی آن را متوقف می کند. این امکان تعاملات طبیعی و محاوره ای را فراهم می کند و به کاربران این امکان را می دهد که مدل را در هر زمان قطع کنند.

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

شروع کنید

Multimodal Live API یک API حالت دار است که از WebSockets استفاده می کند.

این بخش نمونه ای از نحوه استفاده از Multimodal Live API برای تولید متن به متن با استفاده از Python 3.9+ را نشان می دهد.

کتابخانه Gemini API را نصب کنید

برای نصب بسته google-genai از دستور pip زیر استفاده کنید:

!pip3 install google-genai

وابستگی های وارداتی

برای وارد کردن وابستگی ها:

from google import genai

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

import asyncio
from google import genai

client = genai.Client(api_key="GEMINI_API_KEY", http_options={'api_version': 'v1alpha'})
model_id = "gemini-2.0-flash-exp"
config = {"response_modalities": ["TEXT"]}

async def main():
    async with client.aio.live.connect(model=model_id, config=config) as session:
        while True:
            message = input("User> ")
            if message.lower() == "exit":
                break
            await session.send(message, end_of_turn=True)

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

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

راهنمای ادغام

این بخش نحوه عملکرد یکپارچه سازی با Multimodal Live API را شرح می دهد.

جلسات

یک جلسه نشان دهنده یک اتصال WebSocket واحد بین مشتری و سرور Gemini است.

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

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

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

پیکربندی نمونه زیر را ببینید:

{​​
  "model": string,
  "generation_config": {
    "candidate_count": integer,
    "max_output_tokens": integer,
    "temperature": number,
    "top_p": number,
    "top_k": integer,
    "presence_penalty": number,
    "frequency_penalty": number,
    "response_modalities": string,
    "speech_config":object
  },

  "system_instruction": "",
  "tools":[]
}

برای اطلاعات بیشتر، BidiGenerateContentSetup را ببینید.

ارسال پیام

پیام‌ها رشته‌هایی با فرمت JSON هستند که از طریق اتصال WebSocket رد و بدل می‌شوند.

برای ارسال پیام، کلاینت باید یک پیام مشتری پشتیبانی شده در یک رشته فرمت JSON با یکی از یک اتصال باز WebSocket ارسال کند.

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

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

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

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

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

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

ws.addEventListener("message", async (evt) => {
  if (evt.data instanceof Blob) {
    // Process the received data (audio, video, etc.)
  } else {
    // Process JSON response
  }
});

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

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

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

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

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

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

{
  "client_content": {
    "turns": [
      {
          "parts":[
          {
            "text": ""
          }
        ],
        "role":"user"
      },
      {
          "parts":[
          {
            "text": ""
          }
        ],
        "role":"model"
      }
    ],
    "turn_complete": true
  }
}

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

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

فراخوانی تابع

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

برای کسب اطلاعات بیشتر در مورد فراخوانی تابع ، آموزش فراخوانی تابع را ببینید.

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

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

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

فرمت های صوتی

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

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

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

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

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

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

وقفه ها

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

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

صداها

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

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

نمایش JSON زیر از یک شی speech_config را ببینید:

{
  "voice_config": {
    "prebuilt_voice_config ": {
      "voice_name": <var>VOICE_NAME</var>
    }
  }
}

محدودیت ها

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

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

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

برای برنامه‌های وب و تلفن همراه، توصیه می‌کنیم از ادغام شرکای ما در Daily استفاده کنید.

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

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

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

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

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

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

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

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

شمارش توکن

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

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

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

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

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

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

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

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

  • response_logprobs
  • response_mime_type
  • logprobs
  • response_schema
  • stop_sequence
  • routing_config
  • audio_timestamp
system_ instruction

Content

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

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

tools[]

Tool

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

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

BidiGenerateContentSetupComplete

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

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

BidiGenerateContentToolCall

از کلاینت درخواست کنید تا function_calls را اجرا کند و پاسخ‌ها را با 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 ، به تولید محتوا مراجعه کنید.