إنشاء تجارب مختلطة في تطبيقات Android باستخدام نماذج مستضافة على الجهاز ونماذج مستضافة على السحابة الإلكترونية


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

توضّح هذه الصفحة كيفية البدء باستخدام حزمة SDK للعميل، بالإضافة إلى عرض خيارات وإمكانات إعداد إضافية، مثل درجة العشوائية.

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

حالات الاستخدام المقترَحة والإمكانات المتاحة

حالات الاستخدام المقترَحة

  • يوفّر استخدام نموذج على الجهاز فقط للاستدلال ما يلي:

    • خصوصية محسّنة
    • سياق محلي
    • استدلال بدون أي تكلفة
    • وظائف بلا إنترنت

  • يوفّر استخدام وظائف مختلطة ما يلي:

    • الوصول إلى المزيد من شرائح جمهورك من خلال توفير إمكانية استخدام النموذج على الجهاز فقط والاتصال بالإنترنت

الإمكانات والميزات المتاحة للاستنتاج على الجهاز فقط

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

يُرجى مراجعة قائمة الميزات غير المتاحة بعد للاستدلال على الجهاز فقط في أسفل هذه الصفحة.

قبل البدء

يُرجى أخذ ما يلي في الاعتبار:

أجهزة Android المتاحة ونماذجها على الجهاز فقط

بالنسبة إلى الاستنتاج على الجهاز فقط (الذي يستخدم واجهة برمجة التطبيقات Prompt API من حزمة تعلّم الآلة)، يمكنك الاطّلاع على قائمة الأجهزة المتاحة ونماذجها على الجهاز فقط في مستندات حزمة تعلّم الآلة.

البدء

توضّح خطوات البدء هذه عملية الإعداد العامة المطلوبة لأي طلب موجّه تريد إرساله.

الخطوة 1: إعداد مشروع Firebase وربط التطبيق بـ Firebase

  1. سجِّل الدخول إلى وحدة تحكّم Firebase، ثم اختَر مشروع Firebase الخاص بك.

  2. في وحدة تحكّم Firebase، انتقِل إلى خدمات الذكاء الاصطناعي > منطق الذكاء الاصطناعي.

  3. انقر على البدء لفتح سير عمل مُوجَّه يساعدك في إعداد واجهات برمجة التطبيقات المطلوبة والموارد لمشروعك.

  4. اضبط مشروعك لاستخدام مقدّم "Gemini API".

    ننصحك بالبدء باستخدام Gemini Developer API. يمكنك في أي وقت إعداد Vertex AI Gemini API (ومتطلبات الفوترة الخاصة به).

    بالنسبة إلى Gemini Developer API، ستفعِّل وحدة التحكّم واجهات برمجة التطبيقات المطلوبة وتنشئ مفتاح Gemini API في مشروعك.
    يُرجى عدم إضافة مفتاح Gemini API هذا إلى قاعدة رموز تطبيقك. مزيد من المعلومات

  5. إذا طُلب منك ذلك في سير عمل وحدة التحكّم، اتّبِع التعليمات الظاهرة على الشاشة لتسجيل تطبيقك وربطه بمنصة Firebase.

  6. انتقِل إلى الخطوة التالية في هذا الدليل لإضافة حزمة SDK إلى تطبيقك.

الخطوة 2: إضافة حِزم SDK المطلوبة

توفر Firebase AI Logic SDK لنظام التشغيل Android‏ (firebase-ai) بالإضافة إلى Firebase AI Logic On-Device SDK‏ (firebase-ai-ondevice) إمكانية الوصول إلى واجهات برمجة التطبيقات للتفاعل مع النماذج التوليدية.

في ملف Gradle للوحدة (على مستوى التطبيق) (مثل <project>/<app-module>/build.gradle.kts)، أضِف التبعيات لمكتبات Firebase AI Logic لنظام التشغيل Android:

Kotlin 

dependencies {
  // ... other androidx dependencies

  // Add the dependencies for the Firebase AI Logic libraries
  // Note that the on-device SDK is not yet included in the Firebase Android BoM
  implementation("com.google.firebase:firebase-ai:17.11.0")
  implementation("com.google.firebase:firebase-ai-ondevice:16.0.0-beta01")
}

Java

بالنسبة إلى Java، عليك إضافة مكتبتَين إضافيتَين.

dependencies {
  // ... other androidx dependencies

  // Add the dependencies for the Firebase AI Logic libraries
  // Note that the on-device SDK is not yet included in the Firebase Android BoM
  implementation("com.google.firebase:firebase-ai:17.11.0")
  implementation("com.google.firebase:firebase-ai-ondevice:16.0.0-beta01")

  // Required for one-shot operations (to use `ListenableFuture` from Guava Android)
  implementation("com.google.guava:guava:31.0.1-android")

  // Required for streaming operations (to use `Publisher` from Reactive Streams)
  implementation("org.reactivestreams:reactive-streams:1.0.4")
}

الخطوة 3: التحقّق مما إذا كان النموذج على الجهاز فقط متاحًا

باستخدام FirebaseAIOnDevice، تحقَّق مما إذا كان النموذج على الجهاز فقط متاحًا، ونزِّله إذا لم يكن متاحًا.

بعد تنزيل النموذج، سيحرص AICore تلقائيًا على إبقائه محدّثًا. يمكنك الاطّلاع على الملاحظات بعد مقتطف الرمز البرمجي لمزيد من التفاصيل حول AICore وإدارة تنزيل النموذج على الجهاز فقط.

Kotlin 

val status = FirebaseAIOnDevice.checkStatus()
when (status) {
  OnDeviceModelStatus.UNAVAILABLE -> {
    Log.w(TAG, "On-device model is unavailable")
  }

  OnDeviceModelStatus.DOWNLOADABLE -> {
    FirebaseAIOnDevice.download().collect { status ->
      when (status) {
        is DownloadStatus.DownloadStarted ->
          Log.w(TAG, "Starting download - ${status.bytesToDownload}")

        is DownloadStatus.DownloadInProgress ->
          Log.w(TAG, "Download in progress ${status.totalBytesDownloaded} bytes downloaded")

        is DownloadStatus.DownloadCompleted ->
          Log.w(TAG, "On-device model download complete")

        is DownloadStatus.DownloadFailed ->
          Log.e(TAG, "Download failed ${status}")
      }
    }
  }
  OnDeviceModelStatus.DOWNLOADING -> {
    Log.w(TAG, "On-device model is being downloaded")
  }

  OnDeviceModelStatus.AVAILABLE -> {
    Log.w(TAG, "On-device model is available")
  }
}

Java 

Checking for and downloading the model is not yet available for Java.

However, all other APIs and interactions in this guide are available for Java.

يُرجى العِلم بما يلي بشأن تنزيل النموذج على الجهاز فقط:

  • يعتمد الوقت المستغرَق لتنزيل النموذج على الجهاز فقط على العديد من العوامل، بما في ذلك شبكتك.

  • إذا كان الرمز البرمجي يستخدم نموذجًا على الجهاز فقط للاستدلال الأساسي أو الاحتياطي، تأكَّد من تنزيل النموذج في مرحلة مبكرة من مراحل نشاط تطبيقك حتى يكون النموذج على الجهاز فقط متاحًا قبل أن يواجه المستخدمون النهائيون الرمز البرمجي في تطبيقك.

  • إذا كان النموذج على الجهاز فقط غير متاح عند تقديم طلب استدلال على الجهاز فقط ، لن تؤدي حزمة تطوير البرامج (SDK) إلى تنزيل النموذج على الجهاز فقط تلقائيًا. سترجع حزمة تطوير البرامج (SDK) إما إلى النموذج المستضاف على السحابة الإلكترونية أو ستطرح استثناءً (يمكنك الاطّلاع على تفاصيل حول سلوك أوضاع الاستنتاج).

  • يدير AICore (إحدى خدمات نظام التشغيل Android) النموذج والإصدار اللذين يتم تنزيلهما، ويحرص على إبقاء النموذج محدّثًا، وما إلى ذلك. يُرجى العِلم أنّه سيتم تنزيل نموذج واحد فقط على الجهاز، لذا إذا سبق لتطبيق آخر على الجهاز تنزيل النموذج على الجهاز بنجاح، سيشير هذا التحقّق إلى أنّ النموذج متاح.

تحسين وقت الاستجابة

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

الخطوة 4: إعداد الخدمة وإنشاء نموذج

انقر على مقدّم Gemini API لعرض المحتوى الخاص بمقدّم الخدمة والرمز البرمجي على هذه الصفحة.

يُرجى إعداد ما يلي قبل إرسال طلب موجّه إلى النموذج.

  1. أعِدّ الخدمة لمقدّم واجهة برمجة التطبيقات الذي اخترته.

  2. أنشئ نموذج GenerativeModel واضبط mode على أحد الخيارَين التاليَين. الأوصاف الواردة هنا عالية المستوى جدًا، ولكن يمكنك الاطّلاع على تفاصيل حول سلوك هذَين الوضعَين في مقالة ضبط وضع الاستدلال.

    • PREFER_ON_DEVICE: حاوِل استخدام النموذج على الجهاز فقط، وإلا ارجِع إلى النموذج المستضاف على السحابة الإلكترونية.

    • ONLY_ON_DEVICE: حاوِل استخدام النموذج على الجهاز فقط، وإلا اطرح استثناءً.

    • PREFER_IN_CLOUD: حاوِل استخدام النموذج المستضاف على السحابة الإلكترونية، وإلا ارجِع إلى النموذج على الجهاز فقط.

    • ONLY_IN_CLOUD: حاوِل استخدام النموذج المستضاف على السحابة الإلكترونية، وإلا اطرح استثناءً.

Kotlin 

// Using this SDK to access on-device inference is an Experimental release and requires opt-in
@OptIn(PublicPreviewAPI::class)

// ...

// Initialize the Gemini Developer API backend service
// Create a GenerativeModel instance with a model that supports your use case
// Set the inference mode (like PREFER_ON_DEVICE to use the on-device model if available)
val model = Firebase.ai(backend = GenerativeBackend.googleAI())
    .generativeModel(
        modelName = "MODEL_NAME",
        onDeviceConfig = OnDeviceConfig(mode = InferenceMode.PREFER_ON_DEVICE)
    )

Java 

// Initialize the Gemini Developer API backend service
// Create a GenerativeModel instance with a model that supports your use case
// Set the inference mode (like PREFER_ON_DEVICE to use the on-device model if available)
GenerativeModel ai = FirebaseAI.getInstance(GenerativeBackend.googleAI())
    .generativeModel(
        "MODEL_NAME",
        new OnDeviceConfig(InferenceMode.PREFER_ON_DEVICE)
    );

// Use the GenerativeModelFutures Java compatibility layer which offers
// support for ListenableFuture and Publisher APIs
GenerativeModelFutures model = GenerativeModelFutures.from(ai);

الخطوة 5: إرسال طلب موجّه إلى نموذج

يوضّح لك هذا القسم كيفية إرسال أنواع مختلفة من الإدخالات لإنشاء أنواع مختلفة من الإخراج، بما في ذلك:

إنشاء نص من إدخال نصي فقط

قبل تجربة هذا المثال، تأكَّد من إكمال قسم البدء في هذا الدليل.

يمكنك استخدام generateContent() لإنشاء نص من طلب يتضمّن نصًا:

Kotlin 

// Imports + initialization of Gemini API backend service + creation of model instance

// Provide a prompt that contains text
val prompt = "Write a story about a magic backpack."

// To generate text output, call generateContent with the text input
val response = model.generateContent(prompt)
print(response.text)

Java 

// Imports + initialization of Gemini API backend service + creation of model instance

// Provide a prompt that contains text
Content prompt = new Content.Builder()
    .addText("Write a story about a magic backpack.")
    .build();

// To generate text output, call generateContent with the text input
ListenableFuture<GenerateContentResponse> response = model.generateContent(prompt);
Futures.addCallback(response, new FutureCallback<GenerateContentResponse>() {
    @Override
    public void onSuccess(GenerateContentResponse result) {
        String resultText = result.getText();
        System.out.println(resultText);
    }

    @Override
    public void onFailure(Throwable t) {
        t.printStackTrace();
    }
}, executor);

يُرجى العِلم أنّ Firebase AI Logic يتيح أيضًا بث الردود النصية باستخدام generateContentStream (بدلاً من generateContent).

إنشاء نص من إدخال نصي وصورة (متعدّد الوسائط)

قبل تجربة هذا المثال، تأكَّد من إكمال قسم البدء في هذا الدليل.

يمكنك استخدام generateContent() لإنشاء نص من طلب يتضمّن نصًا و ملف صورة واحد فقط (صورة نقطية فقط)، مع توفير mimeType لكل ملف إدخال والملف نفسه.

Kotlin 

// Imports + initialization of Gemini API backend service + creation of model instance

// Loads an image from the app/res/drawable/ directory
val bitmap: Bitmap = BitmapFactory.decodeResource(resources, R.drawable.sparky)

// Provide a prompt that includes the image specified above and text
val prompt = content {
  image(bitmap)
  text("What developer tool is this mascot from?")
}

// To generate text output, call generateContent with the prompt
val response = model.generateContent(prompt)
print(response.text)

Java 

// Imports + initialization of Gemini API backend service + creation of model instance

Bitmap bitmap = BitmapFactory.decodeResource(getResources(), R.drawable.sparky);

// Provide a prompt that includes the image specified above and text
Content content = new Content.Builder()
        .addImage(bitmap)
        .addText("What developer tool is this mascot from?")
        .build();

// To generate text output, call generateContent with the prompt
ListenableFuture<GenerateContentResponse> response = model.generateContent(content);
Futures.addCallback(response, new FutureCallback<GenerateContentResponse>() {
    @Override
    public void onSuccess(GenerateContentResponse result) {
        String resultText = result.getText();
        System.out.println(resultText);
    }

    @Override
    public void onFailure(Throwable t) {
        t.printStackTrace();
    }
}, executor);

يُرجى العِلم أنّ Firebase AI Logic يتيح أيضًا بث الردود النصية باستخدام generateContentStream (بدلاً من generateContent).

ما المهام الأخرى التي يمكنك تنفيذها؟

يمكنك استخدام خيارات وإمكانات إعداد إضافية مختلفة لتجاربك المختلطة:

الميزات غير المتاحة بعد للاستدلال على الجهاز فقط

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

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

  • إنشاء إخراج منظَّم (مثل JSON أو التعدادات)

  • إنشاء نص من أنواع إدخال ملفات الصور بخلاف الصورة النقطية (الصورة المحمَّلة في الذاكرة)

  • إنشاء نص من أكثر من ملف صورة واحد

  • إنشاء نص من إدخالات الصوت والفيديو والمستندات (مثل ملفات PDF)

  • إنشاء صور باستخدام نماذج Gemini أو Imagen

  • توفير الملفات باستخدام عناوين URL في الطلبات المتعدّدة الوسائط يجب توفير الملفات كبيانات مضمّنة للنماذج على الجهاز فقط

  • إرسال طلبات تتجاوز 4,000 رمز مميّز (أو حوالي 3,000 كلمة باللغة الإنجليزية)

  • محادثة متعدّدة الجولات

  • تزويد النموذج بالأدوات لمساعدته في إنشاء ردّه (مثل استدعاء الدوال وتنفيذ الرموز البرمجية وسياق عنوان URL وتحديد المصدر باستخدام "بحث Google")

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

قيود إضافية

بالإضافة إلى ما سبق، يفرض الاستدلال على الجهاز فقط القيود التالية (يمكنك الاطّلاع على مزيد من المعلومات في مستندات حزمة تعلّم الآلة):

  • يجب أن يستخدم المستخدم النهائي لتطبيقك جهازًا متاحًا للاستدلال على الجهاز.

  • لا يمكن لتطبيقك تنفيذ الاستدلال على الجهاز إلا عندما يكون في المقدّمة.

  • تم التحقّق من اللغة الإنجليزية والكورية فقط للاستدلال على الجهاز.

  • الحد الأقصى للرموز المميّزة لطلب الاستدلال على الجهاز فقط بالكامل هو 4,000 رمز مميّز. إذا كانت طلباتك قد تتجاوز هذا الحد، تأكَّد من إعداد وضع استدلال يمكنه استخدام نموذج مستضاف على السحابة الإلكترونية.

  • ننصحك بتجنُّب حالات استخدام الاستدلال على الجهاز فقط التي تتطلّب إخراجًا طويلاً (أكثر من 256 رمزًا مميّزًا).

  • AICore (خدمة تابعة لنظام التشغيل Android التي تدير النماذج على الجهاز فقط) تفرض حصة استنتاج لكل تطبيق. سيؤدي تقديم عدد كبير جدًا من طلبات واجهة برمجة التطبيقات في فترة قصيرة إلى ظهور الرد ErrorCode.BUSY. إذا ظهرت لك هذه الرسالة، ننصحك باستخدام التراجع الأسي لإعادة محاولة الطلب. يمكن أيضًا عرض ErrorCode.PER_APP_BATTERY_USE_QUOTA_EXCEEDED إذا تجاوز أحد التطبيقات حصة طويلة الأمد (على سبيل المثال، الحصة اليومية).


تقديم ملاحظات حول تجربتك مع Firebase AI Logic