Gemini Live API

برای برنامه‌هایی که به پشتیبانی صوتی هم‌زمان و با تأخیر کم نیاز دارند، مانند روبوت‌های گپ یا تعامل‌های کارگزاری، میانای برنامه‌سازی کاربردی Gemini Live روشی بهینه‌سازی‌شده برای جاری‌سازی ورودی و خروجی برای مدل Gemini ارائه می‌دهد. بااستفاده از Firebase AI Logic، می‌توانید Gemini Live API را مستقیماً از برنامه Android خود بدون نیاز به یکپارچه‌سازی زیرینه فراخوانی کنید. این راهنما نحوه استفاده از Gemini Live API را در برنامه Android با Firebase AI Logic به شما نشان می‌دهد.

شروع کنید

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

اگر قبلاً این کار را انجام نداده‌اید، پروژه Firebase راه‌اندازی کنید و برنامه‌تان را به Firebase متصل کنید. برای جزئیات بیشتر، مستندات Firebase AI Logic را ببینید.

راه‌اندازی پروژه Android

کتابخانه «منطق هوش مصنوعی Firebase» و وابستگی‌های «بررسی برنامه» را به فایل build.gradle.kts یا build.gradle سطح برنامه اضافه کنید. برای مدیریت نسخه‌های کتابخانه، از فهرست مواد اولیه Firebase Android استفاده کنید.

dependencies {
  // Import the Firebase BoM
  implementation(platform("com.google.firebase:firebase-bom:35.0.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 همگام‌سازی کنید.

پیکربندی ارائه‌دهنده اشکال‌زدایی «بررسی برنامه» برای توسعه محلی

از اوایل ژوئیه ۲۰۲۶، به‌عنوان بخشی از گردش کار راه‌اندازی هدایت‌شده برای «منطق هوش مصنوعی» در کنسول Firebase، «بررسی برنامه Firebase» به‌طور خودکار برای محافظت از ‫Gemini API اعمال می‌شود. برای توسعه محلی، باید ارائه‌دهنده اشکال‌زدایی App Check را پیکربندی کنید تا گواهی را دور بزنید و درعین‌حال اجرای App Check را حفظ کنید.

  1. در ساخت اشکال‌زدایی، App Check را پیکربندی کنید تا از کارخانه ارائه‌دهنده اشکال‌زدایی استفاده کند:

    کاتلین

    Firebase.initialize(context = this)
    Firebase.appCheck.installAppCheckProviderFactory(
        DebugAppCheckProviderFactory.getInstance(),
    )
    

    جاوا

    FirebaseApp.initializeApp(/*context=*/ this);
    FirebaseAppCheck firebaseAppCheck = FirebaseAppCheck.getInstance();
    firebaseAppCheck.installAppCheckProviderFactory(
            DebugAppCheckProviderFactory.getInstance());
    
  2. نمودار اشکال‌زدایی خود را دریافت کنید:

    1. برنامه‌تان را در شبیه‌ساز یا در دستگاه آزمایشی‌تان اجرا کنید.

    2. در گزارش‌هایتان به‌دنبال نشان اشکال‌زدایی «بررسی برنامه» بگردید. برای مثال:

      D DebugAppCheckProvider: Enter this debug secret into the allow list
      in the Firebase Console for your project: 123a4567-b89c-12d3-e456-789012345678
      
    3. کد را کپی کنید (برای مثال، 123a4567-b89c-12d3-e456-789012345678).

  3. ثبت کردن کد اشکال‌زدایی با App Check:

    1. در کنسول Firebase، به امنیت > بررسی برنامه > برگه برنامه‌ها بروید.

    2. برنامه‌تان را پیدا کنید، روی منو سرریز () کلیک کنید، و سپس مدیریت نشان‌های اشکال‌زدایی را انتخاب کنید.

    3. برای ثبت کردن کد اشکال‌زدایی، دستورالعمل‌های روی صفحه را دنبال کنید.

برای جزئیات مربوط به ارائه‌دهنده اشکال‌زدایی (ازجمله نحوه دریافت کد اشکال‌زدایی جدید)، اسناد رسمی App Check را بررسی کنید.

یکپارچه کردن 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. برای مدل‌های 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
);

بااستفاده از دستورالعمل‌های سیستم می‌توانید مکالمه با مدل را تخصصی‌تر کنید و زمینه‌ای مختص برنامه‌تان ارائه دهید (برای مثال، سابقه فعالیت درون‌برنامه‌ای کاربر).

راه‌اندازی جلسه «میانای برنامه‌سازی کاربردی پخش زنده»

پس‌از ایجاد نمونه 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);

در مکالمه‌هایتان با مدل، توجه داشته باشید که مدل نمی‌تواند وقفه‌ها را مدیریت کند. همچنین، «میانای برنامه‌سازی کاربردی زنده» دوطرفه است، بنابراین از همان اتصال برای ارسال و دریافت محتوا استفاده می‌کنید.

همچنین می‌توانید از Gemini Live API برای تولید صدا از روش‌های ورودی مختلف استفاده کنید:

فراخوانی تابع: اتصال Gemini Live API به برنامه شما

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

فراخوانی تابع (یا فراخوانی ابزار) ویژگی پیاده‌سازی‌های هوش مصنوعی زایا است که به مدل امکان می‌دهد توابع را به ابتکار خود فراخوانی کند تا کنش‌ها را انجام دهد. اگر تابع برونداد داشته باشد، مدل آن را به زمینه‌اش اضافه می‌کند و از آن برای تولیدات بعدی استفاده می‌کند.

نموداری که نشان می‌دهد چگونه Gemini Live API به پیام‌واره کاربر اجازه می‌دهد
       توسط مدل تفسیر شود و تابع ازپیش‌تعریف‌شده‌ای را با
       استدلال‌های مربوط در برنامه Android راه‌اندازی کند، که سپس پاسخ تأییدیه‌ای
       از مدل دریافت می‌کند.
شکل ۱: نموداری که نشان می‌دهد چگونه «میانای برنامه کاربردی Gemini Live» اجازه می‌دهد پیام‌واره کاربر توسط مدل تفسیر شود و تابع ازپیش‌تعریف‌شده‌ای با آرگومان‌های مربوطه در برنامه Android را راه‌اندازی کند، که سپس پاسخ تأییدی از مدل دریافت می‌کند.

برای پیاده‌سازی فراخوانی تابع در برنامه‌تان، با ایجاد یک 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());

مراحل بعدی