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[] | اختیاری. محتوا به مکالمه فعلی با مدل اضافه شده است. برای پرس و جوهای تک نوبتی، این یک نمونه است. برای جستجوهای چند نوبتی، این یک فیلد تکراری است که حاوی تاریخچه مکالمه و آخرین درخواست است. |
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
از کلاینت درخواست کنید تا فراخوانی های تابع را اجرا کند و پاسخ ها را با 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
، به تولید محتوا مراجعه کنید.
ادغام های شخص ثالث
برای استقرار برنامه های وب و تلفن همراه، می توانید گزینه های زیر را بررسی کنید: