Gemini Live API

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

البدء

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

إذا لم يسبق لك إجراء ذلك، عليك إعداد مشروع على Firebase وربط تطبيقك به. لمزيد من التفاصيل، يُرجى الاطّلاع على مستندات "منطق الذكاء الاصطناعي" في Firebase.

إعداد مشروع Android

أضِف تبعية مكتبة Firebase AI Logic إلى ملف build.gradle.kts أو build.gradle على مستوى التطبيق. استخدِم قائمة مواد Firebase لنظام التشغيل Android لإدارة إصدارات المكتبة.

dependencies {
  // Import the Firebase BoM
  implementation(platform("com.google.firebase:firebase-bom:34.1.0"))
  // Add the dependency for the Firebase AI Logic library
  // When using the BoM, you don't specify versions in Firebase library dependencies
  implementation("com.google.firebase:firebase-ai")
}

بعد إضافة التبعية، زامِن مشروع Android مع Gradle.

دمج Firebase AI Logic وإعداد نموذج توليدي

أضِف إذن RECORD_AUDIO إلى ملف AndroidManifest.xml في تطبيقك:

<uses-permission android:name="android.permission.RECORD_AUDIO" />

ابدأ خدمة الخلفية لواجهة Gemini Developer API واطّلِع على LiveModel. استخدِم نموذجًا يتوافق مع Live API، مثل gemini-2.0-flash-live-preview-04-09. راجِع مستندات Firebase للاطّلاع على النماذج المتاحة.

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

Kotlin

// Initialize the `LiveModel`
val model = Firebase.ai(backend = GenerativeBackend.googleAI()).liveModel(
       modelName = "gemini-2.0-flash-live-preview-04-09",
       generationConfig = liveGenerationConfig {
          responseModality = ResponseModality.AUDIO
          speechConfig = SpeechConfig(voice= Voice("FENRIR"))
       })

Java

// Initialize the `LiveModel`
LiveGenerativeModel model = FirebaseAI
       .getInstance(GenerativeBackend.googleAI())
       .liveModel(
              "gemini-2.0-flash-live-preview-04-09",
              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.0-flash-live-preview-04-09",
       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.0-flash-live-preview-04-09",
              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);

يُرجى أيضًا العِلم أنّ النموذج لا يتعامل مع المقاطعات في محادثاتك معه. ونحن نخطّط لإضافة هذه الميزة في المستقبل.

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

استدعاء الدوال البرمجية: ربط واجهة برمجة التطبيقات Gemini Live بتطبيقك

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

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

مخطّط توضيحي يبيّن كيف تتيح واجهة برمجة التطبيقات Gemini Live API تفسير طلب المستخدم من خلال نموذج، ما يؤدي إلى تشغيل وظيفة محدّدة مسبقًا مع وسيطات ذات صلة في تطبيق 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.0-flash-live-preview-04-09",
       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.0-flash-live-preview-04-09",
  new LiveGenerationConfig.Builder()
        .setResponseModalities(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());

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