برای برنامه‌هایی که به پشتیبانی صوتی بی‌درنگ و با تأخیر کم نیاز دارند، مانند روبات‌های گپ یا تعاملات عامل‌محور، Gemini Live API روشی بهینه‌سازی‌شده برای جاری‌سازی ورودی و خروجی برای مدل Gemini ارائه می‌دهد. بااستفاده از Firebase AI Logic، می‌توانید Gemini Live API را مستقیماً از برنامه Android خود بدون نیاز به یکپارچه‌سازی پس‌بک فراخوانی کنید. این راهنما به شما نشان می‌دهد که چگونه از Gemini Live API در برنامه Android خود با Firebase AI Logic استفاده کنید.
شروع کنید
قبل‌از شروع، مطمئن شوید که برنامه‌تان سطح میانای برنامه‌سازی کاربردی ۲۳ یا بالاتر را هدف‌یابی می‌کند.
اگر قبلاً این کار را نکرده‌اید، پروژه Firebase راه‌اندازی کنید و برنامه‌تان را به Firebase متصل کنید. برای جزئیات، به مستندات Firebase AI Logic مراجعه کنید.
راه‌اندازی پروژه Android
کتابخانه Firebase AI Logic و وابستگی‌های «بررسی برنامه» را به فایل build.gradle.kts یا build.gradle در سطح برنامه اضافه کنید. از
فهرست مواد اولیه Firebase Android برای مدیریت نسخه‌های کتابخانه استفاده کنید.
dependencies {
// Import the Firebase BoM
implementation(platform("com.google.firebase:firebase-bom:35.1.0"))
// Add the dependencies for the Firebase AI Logic and App Check libraries
// When using the BoM, you don't specify versions in Firebase library dependencies
implementation("com.google.firebase:firebase-ai")
implementation("com.google.firebase:firebase-appcheck-debug")
}
پس‌از افزودن وابستگی‌ها، پروژه Android خود را با Gradle همگام‌سازی کنید.
پیکربندی ارائه‌دهنده اشکال‌زدایی «بررسی برنامه» برای توسعه محلی
از اوایل ژوئیه ۲۰۲۶، به‌عنوان بخشی از گردش کار راه‌اندازی راهنمایی‌شده برای AI Logic در کنسول Firebase، «بررسی برنامه Firebase» به‌طور خودکار برای محافظت از Gemini API اعمال می‌شود. برای توسعه محلی، باید ارائه‌کننده اشکال‌زدایی «بررسی برنامه» را پیکربندی کنید تا تصدیق را دور بزنید و درعین‌حال اجرای «بررسی برنامه» را حفظ کنید.
در ساخت اشکال‌زدایی، «بررسی برنامه» را برای استفاده از کارخانه ارائه‌کننده اشکال‌زدایی پیکربندی کنید:
کاتلین
Firebase.initialize(context = this) Firebase.appCheck.installAppCheckProviderFactory( DebugAppCheckProviderFactory.getInstance(), )جاوا
FirebaseApp.initializeApp(/*context=*/ this); FirebaseAppCheck firebaseAppCheck = FirebaseAppCheck.getInstance(); firebaseAppCheck.installAppCheckProviderFactory( DebugAppCheckProviderFactory.getInstance());دریافت کردن کد اشکال‌زدایی:
برنامه‌تان را در شبیه‌ساز یا در دستگاه آزمایشی‌تان اجرا کنید.
در گزارش‌هایتان، به‌دنبال کد تصدیق اشکال‌زدایی «بررسی برنامه» بگردید. برای مثال:
D DebugAppCheckProvider: Enter this debug secret into the allow list in the Firebase Console for your project: 123a4567-b89c-12d3-e456-789012345678کد را کپی کنید (برای مثال،
123a4567-b89c-12d3-e456-789012345678).
ثبت کردن کد اشکال‌زدایی با «بررسی برنامه»:
در کنسول Firebase، به Security (امنیت) > App Check (بررسی برنامه) > Apps (برنامه‌ها) بروید.
برنامه‌تان را پیدا کنید، روی منوِ سرریز () کلیک کنید، و سپس مدیریت کردن کدهای اشکال‌زدایی را انتخاب کنید.
دستورالعمل‌های روی صفحه را برای ثبت کردن کد اشکال‌زدایی دنبال کنید.
برای جزئیات مربوط به ارائه‌دهنده اشکال‌زدایی (ازجمله نحوه دریافت یک توکن اشکال‌زدایی جدید)، اسناد رسمی «بررسی برنامه» را بررسی کنید.
یکپارچه‌سازی Firebase AI Logic و مقداردهی اولیه مدل زایا
اجازه RECORD_AUDIO را به فایل AndroidManifest.xml
برنامه‌تان اضافه کنید:
<uses-permission android:name="android.permission.RECORD_AUDIO" />
سرویس پسای Gemini Developer API را مقداردهی اولیه کنید و به LiveModel دسترسی پیدا کنید.
از مدلی استفاده کنید که از Live API پشتیبانی می‌کند، مثل
gemini-2.5-flash-native-audio-preview-12-2025.
برای مدل‌های Live API دردسترس، به اسناد Firebase مراجعه کنید.
برای مشخص کردن صدا، نام صدا را در شیء speechConfig به‌عنوان بخشی از پیکربندی مدل تنظیم کنید. اگر
صدایی را مشخص نکنید، صدای پیش‌فرض Puck است.
کاتلین
// Initialize the `LiveModel` val model = Firebase.ai(backend = GenerativeBackend.googleAI()).liveModel( modelName = "gemini-2.5-flash-native-audio-preview-12-2025", generationConfig = liveGenerationConfig { responseModality = ResponseModality.AUDIO speechConfig = SpeechConfig(voice = Voice("FENRIR")) } )
جاوا
// Initialize the `LiveModel`
LiveGenerativeModel model = FirebaseAI
.getInstance(GenerativeBackend.googleAI())
.liveModel(
"gemini-2.5-flash-native-audio-preview-12-2025",
new LiveGenerationConfig.Builder()
.setResponseModality(ResponseModality.AUDIO)
.setSpeechConfig(new SpeechConfig(new Voice("FENRIR"))
).build(),
null,
null
);
می‌توانید با تنظیم دستورالعمل سیستم، به‌طور اختیاری شخصیت یا نقشی را که مدل ایفا می‌کند تعریف کنید:
کاتلین
val systemInstruction = content { text("You are a helpful assistant, you main role is [...]") } val model = Firebase.ai(backend = GenerativeBackend.googleAI()).liveModel( modelName = "gemini-2.5-flash-native-audio-preview-12-2025", generationConfig = liveGenerationConfig { responseModality = ResponseModality.AUDIO speechConfig = SpeechConfig(voice = Voice("FENRIR")) }, systemInstruction = systemInstruction, )
جاوا
Content systemInstruction = new Content.Builder()
.addText("You are a helpful assistant, you main role is [...]")
.build();
LiveGenerativeModel model = FirebaseAI
.getInstance(GenerativeBackend.googleAI())
.liveModel(
"gemini-2.5-flash-native-audio-preview-12-2025",
new LiveGenerationConfig.Builder()
.setResponseModality(ResponseModality.AUDIO)
.setSpeechConfig(new SpeechConfig(new Voice("FENRIR"))
).build(),
tools, // null if you don't want to use function calling
systemInstruction
);
بااستفاده از دستورالعمل‌های سیستم برای ارائه بافت مختص برنامه‌تان (برای مثال، سابقه فعالیت درون‌برنامه کاربر)، می‌توانید مکالمه با مدل را تخصصی‌تر کنید.
مقداردهی اولیه جلسه Live API
پس‌از ایجاد نمونه LiveModel، model.connect() را فراخوانی کنید تا شیء LiveSession ایجاد شود و اتصال پایداری با مدل با جاری‌سازی با تأخیر کم برقرار شود. LiveSession به شما امکان می‌دهد با شروع و توقف جلسه صوتی و همچنین ارسال و دریافت نوشتار، با مدل تعامل برقرار کنید.
سپس می‌توانید startAudioConversation() را فراخوانی کنید تا مکالمه با مدل را شروع کنید:
کاتلین
val session = model.connect() session.startAudioConversation()
جاوا
LiveModelFutures model = LiveModelFutures.from(liveModel);
ListenableFuture<LiveSession> sessionFuture = model.connect();
Futures.addCallback(sessionFuture, new FutureCallback<LiveSession>() {
@Override
public void onSuccess(LiveSession ses) {
LiveSessionFutures session = LiveSessionFutures.from(ses);
session.startAudioConversation();
}
@Override
public void onFailure(Throwable t) {
// Handle exceptions
}
}, executor);
در مکالمه‌هایتان با مدل، توجه داشته باشید که مدل نمی‌تواند وقفه‌ها را مدیریت کند. همچنین، Live API دوجهتی است، بنابراین از همان اتصال برای ارسال و دریافت محتوا استفاده می‌کنید.
همچنین می‌توانید از Gemini Live API برای تولید صدا از حالت‌های ورودی مختلف استفاده کنید:
- ارسال ورودی نوشتاری و صوتی.
- ورودی ویدیو ارسال کنید (برنامه شروع سریع Firebase را بررسی کنید).
فراخوانی تابع: Gemini Live API را به برنامه‌تان متصل کنید
برای برداشتن گامی فراتر، می‌توانید مدل را فعال کنید تا بااستفاده از فراخوانی تابع مستقیماً با منطق برنامه‌تان تعامل برقرار کند.
فراخوانی تابع (یا فراخوانی ابزار) یکی از ویژگی‌های پیاده‌سازی‌های هوش مصنوعی زایا است که به مدل اجازه می‌دهد تا توابع را به ابتکار خود برای انجام کنش‌ها فراخوانی کند. اگر تابع خروجی داشته باشد، مدل آن را به بافت خود اضافه می‌کند و از آن برای تولیدهای بعدی استفاده می‌کند.
برای پیاده‌سازی فراخوانی تابع در برنامه‌تان، ابتدا یک شیء FunctionDeclaration برای هر تابعی که می‌خواهید دراختیار مدل قرار دهید ایجاد کنید.
برای مثال، برای نمایش دادن تابع addList که رشته‌ای را به فهرستی از رشته‌ها به Gemini اضافه می‌کند، با ایجاد متغیر FunctionDeclaration با نام و شرح کوتاهی به زبان انگلیسی ساده از تابع و پارامتر آن شروع کنید:
کاتلین
val itemList = mutableListOf<String>() fun addList(item: String) { itemList.add(item) } val addListFunctionDeclaration = FunctionDeclaration( name = "addList", description = "Function adding an item the list", parameters = mapOf( "item" to Schema.string("A short string describing the item to add to the list") ) )
جاوا
HashMap<String, Schema> addListParams = new HashMap<String, Schema>(1);
addListParams.put("item", Schema.str("A short string describing the item to add to the list"));
FunctionDeclaration addListFunctionDeclaration = new FunctionDeclaration(
"addList",
"Function adding an item the list",
addListParams,
Collections.emptyList()
);
سپس، این FunctionDeclaration را به‌عنوان Tool به مدل منتقل کنید وقتی
آن را نمونه‌سازی می‌کنید:
کاتلین
val addListTool = Tool.functionDeclarations(listOf(addListFunctionDeclaration)) val model = Firebase.ai(backend = GenerativeBackend.googleAI()).liveModel( modelName = "gemini-2.5-flash-native-audio-preview-12-2025", generationConfig = liveGenerationConfig { responseModality = ResponseModality.AUDIO speechConfig = SpeechConfig(voice = Voice("FENRIR")) }, systemInstruction = systemInstruction, tools = listOf(addListTool) )
جاوا
LiveGenerativeModel model = FirebaseAI.getInstance(
GenerativeBackend.googleAI()).liveModel(
"gemini-2.5-flash-native-audio-preview-12-2025",
new LiveGenerationConfig.Builder()
.setResponseModality(ResponseModality.AUDIO)
.setSpeechConfig(new SpeechConfig(new Voice("FENRIR")))
.build(),
List.of(Tool.functionDeclarations(List.of(addListFunctionDeclaration))),
null,
systemInstruction
);
درنهایت، یک تابع کنترل‌کننده را برای رسیدگی به فراخوانی ابزاری که مدل انجام می‌دهد پیاده‌سازی کنید
و پاسخ را به آن برگردانید. این تابع گرداننده که هنگام فراخوانی startAudioConversation به
LiveSession ارائه می‌شود، پارامتر FunctionCallPart
را می‌گیرد و FunctionResponsePart را برمی‌گرداند:
کاتلین
session.startAudioConversation(::functionCallHandler) // ... fun functionCallHandler(functionCall: FunctionCallPart): FunctionResponsePart { return when (functionCall.name) { "addList" -> { // Extract function parameter from functionCallPart val itemName = functionCall.args["item"]!!.jsonPrimitive.content // Call function with parameter addList(itemName) // Confirm the function call to the model val response = JsonObject( mapOf( "success" to JsonPrimitive(true), "message" to JsonPrimitive("Item $itemName added to the todo list") ) ) FunctionResponsePart(functionCall.name, response) } else -> { val response = JsonObject( mapOf( "error" to JsonPrimitive("Unknown function: ${functionCall.name}") ) ) FunctionResponsePart(functionCall.name, response) } } }
جاوا
Futures.addCallback(sessionFuture, new FutureCallback<LiveSessionFutures>() {
@RequiresPermission(Manifest.permission.RECORD_AUDIO)
@Override
@OptIn(markerClass = PublicPreviewAPI.class)
public void onSuccess(LiveSessionFutures ses) {
ses.startAudioConversation(::handleFunctionCallFuture);
}
@Override
public void onFailure(Throwable t) {
// Handle exceptions
}
}, executor);
// ...
ListenableFuture<JsonObject> handleFunctionCallFuture = Futures.transform(response, result -> {
for (FunctionCallPart functionCall : result.getFunctionCalls()) {
if (functionCall.getName().equals("addList")) {
Map<String, JsonElement> args = functionCall.getArgs();
String item =
JsonElementKt.getContentOrNull(
JsonElementKt.getJsonPrimitive(
locationJsonObject.get("item")));
return addList(item);
}
}
return null;
}, Executors.newSingleThreadExecutor());
مراحل بعدی
- با Gemini Live API در برنامه نمونه کاتالوگ هوش مصنوعی Android بازی کنید.
- در سند Firebase AI Logic درباره Gemini Live API بیشتر بخوانید.
- درباره مدل‌های Gemini دردسترس بیشتر بدانید.
- درباره فراخوانی تابع بیشتر بدانید.
- استراتژی‌های طراحی پیام‌واره را کاوش کنید.