إنشاء تجارب مختلطة في تطبيقات 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 في مشروعك.
    لا تُضِف مفتاح API هذا إلى قاعدة رموز تطبيقك.Gemini مزيد من المعلومات

  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.12.0")
  implementation("com.google.firebase:firebase-ai-ondevice:16.0.0-beta02")
}

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.12.0")
  implementation("com.google.firebase:firebase-ai-ondevice:16.0.0-beta02")

  // 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 و Grounding with Google Search وGrounding with Google Maps)

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

قيود إضافية

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

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

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

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

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

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

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


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