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:34.19.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، وكجزء من عملية الإعداد الموجّه لميزة AI Logic في وحدة تحكّم Firebase، سيتم تلقائيًا فرض استخدام ميزة "فحص التطبيقات من Firebase" لحماية Gemini API. للتطوير على الجهاز المحلي، عليك ضبط موفّر تصحيح الأخطاء في App Check لتجاوز عملية إثبات صحة الجهاز مع الحفاظ على فرض استخدام App Check.

  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 لمعرفة نماذج واجهة برمجة التطبيقات المباشرة المتاحة.

لتحديد صوت، اضبط اسم الصوت ضمن العنصر 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 بتطبيقك

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

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

مخطّط توضيحي يبيّن كيف تتيح واجهة برمجة التطبيقات Gemini Live تفسير طلب المستخدم من خلال نموذج، ما يؤدي إلى تشغيل دالة محدّدة مسبقًا مع وسيطات ذات صلة في تطبيق Android، والذي يتلقّى بعد ذلك رد تأكيد من النموذج.
الشكل 1: رسم بياني يوضّح كيف تتيح واجهة برمجة التطبيقات Gemini Live للمستخدم إدخال طلب تتم معالجته من خلال نموذج، ما يؤدي إلى تشغيل دالة محدّدة مسبقًا مع وسيطات ذات صلة في تطبيق 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());

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