Gemini Live API

بالنسبة إلى التطبيقات التي تتطلّب دعمًا صوتيًا في الوقت الفعلي وبزمن انتقال منخفض، مثل برامج الدردشة الآلية أو التفاعلات المستندة إلى الوكلاء، توفّر Gemini Live API طريقة محسّنة لبث كل من الإدخال والإخراج لنموذج Gemini. باستخدام Firebase AI Logic، يمكنك طلب Gemini Live API مباشرةً من تطبيق Android بدون الحاجة إلى دمج الواجهة الخلفية. يوضّح لك هذا الدليل كيفية استخدام Gemini Live API في تطبيق Android من خلال Firebase AI Logic.

البدء

قبل البدء، تأكَّد من أنّ تطبيقك يستهدف المستوى 23 من واجهة برمجة التطبيقات أو المستويات الأعلى.

إذا لم يسبق لك إجراء ذلك، عليك إعداد مشروع على 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.

ضبط مقدّم خدمة تصحيح الأخطاء في ميزة "فحص التطبيقات" للتطوير على الجهاز المحلي

اعتبارًا من أوائل يوليو 2026، سيتم فرض ميزة "فحص التطبيقات من Firebase" تلقائيًا لحماية واجهة Gemini API، وذلك كجزء من عملية الإعداد الموجَّهة لميزة AI Logic في وحدة تحكُّم Firebase. للتطوير على الجهاز، عليك ضبط مقدّم خدمة تصحيح الأخطاء في ميزة "فحص التطبيقات" لتجاوز عملية المصادقة مع مواصلة تنفيذ ميزة "فحص التطبيقات".

  1. في الإصدار المخصص لتصحيح الأخطاء، اضبط ميزة "فحص التطبيقات" لاستخدام مصنع مقدِّم خدمة تصحيح الأخطاء:

    Kotlin

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

    Java

    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. سجِّل رمز تصحيح الأخطاء باستخدام ميزة "فحص التطبيقات":

    1. في وحدة تحكُّم Firebase، انتقِل إلى علامة التبويب الأمان > فحص التطبيقات > التطبيقات.

    2. ابحث عن تطبيقك، وانقر على قائمة الكاملة ()، ثم اختَر إدارة الرموز المميّزة لتصحيح الأخطاء.

    3. اتّبِع التعليمات الظاهرة على الشاشة لتسجيل الرمز المميّز لتصحيح الأخطاء.

لمعرفة تفاصيل عن مقدّم خدمة تصحيح الأخطاء (بما في ذلك كيفية الحصول على رمز مميّز جديد لتصحيح الأخطاء)، يُرجى الاطّلاع على مستندات ميزة "فحص التطبيقات" الرسمية.

دمج 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. يمكنك الاطّلاع على مستندات Firebase حول نماذج Live API المتاحة.

لتحديد صوت، اضبط اسم الصوت ضمن عنصر speechConfig كجزء من إعدادات النموذج. إذا لم تحدّد صوتًا، سيتم استخدام Puck تلقائيًا.

Kotlin

// 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"))
    }
)

Java

// 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
);

يمكنك اختياريًا تحديد شخصية أو دور يؤديه النموذج من خلال ضبط تعليمات النظام:

Kotlin

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,
)

Java

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() لبدء المحادثة مع النموذج:

Kotlin

val session = model.connect()
session.startAudioConversation()

Java

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 لإنشاء محتوى صوتي من أنواع مختلفة من الإدخالات:

استدعاء الدوال: ربط Gemini Live API بتطبيقك

يمكنك أيضًا تفعيل النموذج للتفاعل مباشرةً مع منطق تطبيقك باستخدام ميزة استدعاء الدوال.

استدعاء الدوال (أو استدعاء الأدوات) هو ميزة في عمليات تنفيذ الذكاء الاصطناعي التوليدي تسمح للنموذج باستدعاء الدوال من تلقاء نفسه لتنفيذ الإجراءات. إذا كانت الدالة تتضمّن مخرجات، يضيفها النموذج إلى سياقه ويستخدمها في عمليات الإنشاء اللاحقة.

مخطّط بياني يوضّح كيف تتيح Gemini Live API لطلب المستخدم أن يفسّره نموذج، ما يؤدي إلى تفعيل دالة محدّدة مسبقًا باستخدام وسيطات ذات صلة في تطبيق Android، والذي يتلقّى بعد ذلك ردّ تأكيد من النموذج.
الشكل 1: مخطّط بياني يوضّح كيف تتيح واجهة Gemini Live API لأحد النماذج تفسير طلب المستخدم، ما يؤدي إلى تفعيل دالة محدّدة مسبقًا باستخدام الوسيطات ذات الصلة في تطبيق Android، والذي يتلقّى بعد ذلك ردّ تأكيد من النموذج.

لتنفيذ ميزة "استدعاء الدوال" في تطبيقك، ابدأ بإنشاء كائن FunctionDeclaration لكل دالة تريد عرضها للنموذج.

على سبيل المثال، لإتاحة دالة addList تضيف سلسلة إلى قائمة من السلاسل في Gemini، ابدأ بإنشاء متغيّر FunctionDeclaration يحمل اسمًا ووصفًا موجزًا باللغة الإنجليزية البسيطة للدالة ومعلمتها:

Kotlin

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")
    )
)

Java

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 إلى النموذج عند إنشائه:

Kotlin

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)
)

Java

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
        );

أخيرًا، نفِّذ دالة معالِج لمعالجة طلب الأداة الذي يرسله النموذج وإرسال الردّ إليه. تتلقّى دالة المعالِج هذه التي يتم توفيرها لـ LiveSession عند استدعاء startAudioConversation مَعلمة FunctionCallPart وتعرض FunctionResponsePart:

Kotlin

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)
        }
    }
}

Java

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());

الخطوات التالية