رابط برنامه‌نویسی نرم‌افزار Gemini Live امکان تعامل دوطرفه و بلادرنگ با مدل‌های Gemini را فراهم می‌کند و از ورودی‌های صوتی، تصویری و متنی و خروجی‌های صوتی بومی پشتیبانی می‌کند. این راهنما نحوه ادغام با API را با استفاده از Google GenAI SDK روی سرور شما توضیح می‌دهد.
نمای کلی
رابط برنامه‌نویسی نرم‌افزار Gemini Live از WebSockets برای ارتباط بلادرنگ استفاده می‌کند. google-genai SDK یک رابط کاربری ناهمزمان سطح بالا برای مدیریت این ارتباطات فراهم می‌کند.
مفاهیم کلیدی:
- جلسه (Session) : یک اتصال پایدار به مدل.
- پیکربندی : تنظیم روش‌ها (صوتی/متنی)، صدا و دستورالعمل‌های سیستم.
- ورودی بلادرنگ : ارسال فریم‌های صوتی و تصویری به صورت حباب.
اتصال به API زنده
شروع یک جلسه API زنده با یک کلید API:
پایتون
import asyncio
from google import genai
client = genai.Client(api_key="YOUR_API_KEY")
model = "gemini-3.8-live"
config = {"response_modalities": ["AUDIO"]}
async def main():
async with client.aio.live.connect(model=model, config=config) as session:
print("Session started")
# Send content...
if __name__ == "__main__":
asyncio.run(main())
جاوا اسکریپت
import { GoogleGenAI, Modality } from '@google/genai';
const ai = new GoogleGenAI({ apiKey: "YOUR_API_KEY"});
const model = 'gemini-3.8-live';
const config = { responseModalities: [Modality.AUDIO] };
async function main() {
const session = await ai.live.connect({
model: model,
callbacks: {
onopen: function () {
console.debug('Opened');
},
onmessage: function (message) {
console.debug(message);
},
onerror: function (e) {
console.debug('Error:', e.message);
},
onclose: function (e) {
console.debug('Close:', e.reason);
},
},
config: config,
});
console.debug("Session started");
// Send content...
session.close();
}
main();
ارسال متن
متن را می‌توان با استفاده از send_realtime_input (پایتون) یا sendRealtimeInput (جاوااسکریپت) ارسال کرد.
پایتون
await session.send_realtime_input(text="Hello, how are you?")
جاوا اسکریپت
session.sendRealtimeInput({
text: 'Hello, how are you?'
});
ارسال صدا
صدا باید به صورت داده‌های خام PCM (صدای خام PCM شانزده بیتی، ۱۶ کیلوهرتز، little-endian) ارسال شود.
پایتون
# Assuming 'chunk' is your raw PCM audio bytes
await session.send_realtime_input(
audio=types.Blob(
data=chunk,
mime_type="audio/pcm;rate=16000"
)
)
جاوا اسکریپت
// Assuming 'chunk' is a Buffer of raw PCM audio
session.sendRealtimeInput({
audio: {
data: chunk.toString('base64'),
mimeType: 'audio/pcm;rate=16000'
}
});
برای مثالی از نحوه دریافت صدا از دستگاه کلاینت (مثلاً مرورگر)، به مثال سرتاسری در GitHub مراجعه کنید.
ارسال ویدیو
فریم‌های ویدیویی به صورت تصاویر مجزا (مثلاً JPEG یا PNG) با نرخ فریم مشخص (حداکثر ۱ فریم در ثانیه) ارسال می‌شوند.
پایتون
# Assuming 'frame' is your JPEG-encoded image bytes
await session.send_realtime_input(
video=types.Blob(
data=frame,
mime_type="image/jpeg"
)
)
جاوا اسکریپت
// Assuming 'frame' is a Buffer of JPEG-encoded image data
session.sendRealtimeInput({
video: {
data: frame.toString('base64'),
mimeType: 'image/jpeg'
}
});
برای مثالی از نحوه دریافت ویدیو از دستگاه کلاینت (مثلاً مرورگر)، به مثال سرتاسری در GitHub مراجعه کنید.
دریافت صدا
پاسخ‌های صوتی مدل به صورت تکه‌هایی از داده دریافت می‌شوند.
پایتون
async for response in session.receive():
if response.server_content and response.server_content.model_turn:
for part in response.server_content.model_turn.parts:
if part.inline_data:
audio_data = part.inline_data.data
# Process or play the audio data
جاوا اسکریپت
// Inside the onmessage callback
const content = response.serverContent;
if (content?.modelTurn?.parts) {
for (const part of content.modelTurn.parts) {
if (part.inlineData) {
const audioData = part.inlineData.data;
// Process or play audioData (base64 encoded string)
}
}
}
برای یادگیری نحوه دریافت صدا روی سرور و پخش آن در مرورگر ، به برنامه نمونه در GitHub مراجعه کنید.
دریافت متن
رونوشت‌های مربوط به ورودی کاربر و خروجی مدل در محتوای سرور موجود است.
پایتون
async for response in session.receive():
content = response.server_content
if content:
if content.input_transcription:
print(f"User: {content.input_transcription.text}")
if content.output_transcription:
print(f"Gemini: {content.output_transcription.text}")
جاوا اسکریپت
// Inside the onmessage callback
const content = response.serverContent;
if (content?.inputTranscription) {
console.log('User:', content.inputTranscription.text);
}
if (content?.outputTranscription) {
console.log('Gemini:', content.outputTranscription.text);
}
مدیریت فراخوانی‌های ابزار
API از فراخوانی ابزار (فراخوانی تابع) پشتیبانی می‌کند. وقتی مدل درخواست فراخوانی ابزار را می‌دهد، شما باید تابع را اجرا کرده و پاسخ را ارسال کنید.
پایتون
async for response in session.receive():
if response.tool_call:
function_responses = []
for fc in response.tool_call.function_calls:
# 1. Execute the function locally
result = my_tool_function(**fc.args)
# 2. Prepare the response
function_responses.append(types.FunctionResponse(
name=fc.name,
id=fc.id,
response={"result": result}
))
# 3. Send the tool response back to the session
await session.send_tool_response(function_responses=function_responses)
جاوا اسکریپت
// Inside the onmessage callback
if (response.toolCall) {
const functionResponses = [];
for (const fc of response.toolCall.functionCalls) {
const result = myToolFunction(fc.args);
functionResponses.push({
name: fc.name,
id: fc.id,
response: { result }
});
}
session.sendToolResponse({ functionResponses });
}
قدم بعدی چیست؟
- برای آشنایی با قابلیت‌ها و پیکربندی‌های کلیدی، راهنمای کامل قابلیت‌های Live API را مطالعه کنید؛ از جمله تشخیص فعالیت صوتی و ویژگی‌های صوتی بومی.
- برای یادگیری نحوه ادغام Live API با ابزارها و فراخوانی توابع، راهنمای استفاده از ابزار را مطالعه کنید.
- برای مدیریت مکالمات طولانی مدت، راهنمای مدیریت جلسه را مطالعه کنید.
- برای احراز هویت امن در برنامه‌های کلاینت به سرور، راهنمای توکن‌های زودگذر را مطالعه کنید.
- برای اطلاعات بیشتر در مورد API مربوط به WebSockets، به مرجع API مربوط به WebSockets مراجعه کنید.