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


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

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

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

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

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

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

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

  • تتضمّن وظائف الوضع المختلط ما يلي:

    • الوصول إلى المزيد من الجمهور من خلال توفير النموذج على الجهاز والاتصال بالإنترنت

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

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

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

قبل البدء

يُرجى مراعاة ما يلي:

أجهزة Android المتوافقة وطُرزها على الجهاز

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

البدء

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

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

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

  2. في وحدة تحكّم Firebase، انتقِل إلى صفحة Firebase AI Logic.

  3. انقر على Get started (البدء) لتشغيل سير عمل موجّه يساعدك في إعداد واجهات برمجة التطبيقات المطلوبة والموارد لمشروعك.

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

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

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

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

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

الخطوة 2: إضافة حِزم تطوير البرامج (SDK) المطلوبة

تتيح حزمة تطوير البرامج (SDK) لنظام التشغيل Firebase AI Logic Android (firebase-ai) مع حزمة تطوير البرامج (SDK) الخاصة بـ Firebase AI Logic On-Device (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.10.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.10.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() لإنشاء نص من طلب يحتوي على نص وما يصل إلى ملف صورة واحد (Bitmap فقط)، وذلك من خلال تقديم 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).

ما هي المهام الأخرى التي يمكن لمساعد Google تنفيذها؟

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

الميزات غير المتوفّرة بعد للاستدلال على الجهاز

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

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

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

  • إنشاء نص من أنواع إدخال ملفات الصور غير Bitmap (صورة تم تحميلها في الذاكرة)

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

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

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

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

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

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

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

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

القيود الإضافية

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

  • يجب أن يستخدم المستخدم النهائي لتطبيقك جهازًا متوافقًا لإجراء الاستدلال على الجهاز.

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

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

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

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

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


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