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[] | اختیاری. محتوا به مکالمه فعلی با مدل اضافه شده است. برای پرس و جوهای تک نوبتی، این یک نمونه است. برای جستجوهای چند نوبتی، این یک فیلد تکراری است که حاوی تاریخچه مکالمه و آخرین درخواست است. |
turn_ complete | اختیاری. اگر درست باشد، نشان می دهد که تولید محتوای سرور باید با درخواست انباشته شده فعلی شروع شود. در غیر این صورت، سرور قبل از شروع تولید منتظر پیام های اضافی است. |
BidiGenerateContentRealtimeInput
ورودی کاربر که در زمان واقعی ارسال می شود.
این از چند جهت با BidiGenerateContentClientContent
متفاوت است:
- می تواند به طور مداوم بدون وقفه به تولید مدل ارسال شود.
- اگر نیاز به ترکیب دادههای به هم پیوسته در
BidiGenerateContentClientContent
وBidiGenerateContentRealtimeInput
وجود داشته باشد، سرور تلاش میکند تا بهترین پاسخ را بهینه کند، اما هیچ تضمینی وجود ندارد. - پایان نوبت به صراحت مشخص نشده است، بلکه بیشتر از فعالیت کاربر مشتق شده است (مثلاً پایان گفتار).
- حتی قبل از پایان نوبت، داده ها به صورت تدریجی پردازش می شوند تا برای شروع سریع پاسخ از مدل بهینه شود.
- همیشه ورودی مستقیم کاربر است که در زمان واقعی ارسال می شود. امکان ارسال مداوم و بدون وقفه مدل به طور خودکار شروع و پایان گفتار کاربر را تشخیص میدهد و بر این اساس جریان پاسخ را شروع یا خاتمه میدهد. داده ها با رسیدن به تدریج پردازش می شوند و تاخیر را به حداقل می رساند.
فیلدها | |
---|---|
media_ chunks[] | اختیاری. داده بایت های خطی برای ورودی رسانه. |
BidiGenerateContentServerContent
به روز رسانی افزایشی سرور که توسط مدل در پاسخ به پیام های مشتری ایجاد می شود.
محتوا در سریع ترین زمان ممکن و نه در زمان واقعی تولید می شود. مشتریان ممکن است انتخاب کنند که بافر کنند و آن را در زمان واقعی پخش کنند.
فیلدها | |
---|---|
turn_ complete | فقط خروجی اگر درست باشد، نشان می دهد که تولید مدل انجام شده است. تولید فقط در پاسخ به پیام های مشتری اضافی شروع می شود. می تواند در کنار |
interrupted | فقط خروجی اگر درست باشد، نشان می دهد که پیام مشتری تولید مدل فعلی را قطع کرده است. اگر مشتری در حال پخش محتوا در زمان واقعی است، این سیگنال خوبی برای توقف و خالی کردن صف پخش فعلی است. |
grounding_ metadata | فقط خروجی متاداده پایه برای محتوای تولید شده. |
model_ turn | فقط خروجی محتوایی که مدل به عنوان بخشی از مکالمه فعلی با کاربر تولید کرده است. |
BidiGenerateContentSetup
پیامی که باید در اولین و تنها اولین پیام مشتری ارسال شود. حاوی پیکربندی است که برای مدت جلسه پخش جریانی اعمال می شود.
مشتریان باید قبل از ارسال هرگونه پیام اضافی منتظر یک پیام BidiGenerateContentSetupComplete
باشند.
فیلدها | |
---|---|
model | مورد نیاز. نام منبع مدل این به عنوان شناسه ای برای استفاده از مدل عمل می کند. قالب: |
generation_ config | اختیاری. پیکربندی نسل فیلدهای زیر پشتیبانی نمی شوند:
|
system_ instruction | اختیاری. کاربر دستورالعمل های سیستمی را برای مدل ارائه کرد. توجه: فقط متن باید در قسمت ها استفاده شود و محتوا در هر قسمت در یک پاراگراف جداگانه خواهد بود. |
tools[] | اختیاری. فهرستی از |
BidiGenerateContentSetupComplete
این نوع هیچ فیلدی ندارد.
در پاسخ به یک پیام BidiGenerateContentSetup
از مشتری ارسال شد.
BidiGenerateContentToolCall
از کلاینت درخواست کنید تا function_calls
را اجرا کند و پاسخها را با id
منطبق برگرداند.
فیلدها | |
---|---|
function_ calls[] | فقط خروجی فراخوانی تابعی که باید اجرا شود. |
BidiGenerateContentToolCallCancellation
اعلان برای سرویس گیرنده مبنی بر اینکه یک ToolCallMessage
قبلاً صادر شده با id
های مشخص شده باید اجرا نشده باشد و باید لغو شود. اگر این تماسهای ابزار عوارض جانبی داشت، مشتریان ممکن است تلاش کنند تا تماسهای ابزار را لغو کنند. این پیام تنها در مواردی رخ میدهد که کلاینتها چرخش سرور را قطع کنند.
فیلدها | |
---|---|
ids[] | فقط خروجی شناسههای ابزار تماسهای لغو میشوند. |
BidiGenerateContentToolResponse
مشتری پاسخی به ToolCall
دریافت شده از سرور ایجاد کرد. اشیاء فردی FunctionResponse
با فیلد id
با اشیاء FunctionCall
مربوطه مطابقت داده می شوند.
توجه داشته باشید که در APIهای GenerateContent یکپارچه و جریان سرور، فراخوانی تابع با مبادله قسمتهای Content
انجام میشود، در حالی که در bidi GenerateContent API فراخوانی روی این مجموعه پیامهای اختصاصی انجام میشود.
فیلدها | |
---|---|
function_ responses[] | اختیاری. پاسخ به فراخوانی تابع. |
اطلاعات بیشتر در مورد انواع رایج
برای اطلاعات بیشتر در مورد انواع منابع API رایج Blob
، Content
، FunctionCall
، FunctionResponse
، GenerationConfig
، GroundingMetadata
و Tool
، به تولید محتوا مراجعه کنید.