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


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

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

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

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

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

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

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

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

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

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

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

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

قبل البدء

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

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

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

البدء

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

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

  1. سجِّل الدخول إلى Firebase وحدة التحكّم، ثم اختَر مشروع 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).

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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


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