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


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

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

يُرجى العِلم أنّ ميزة "الاستدلال على الجهاز فقط" من خلال Firebase AI Logic متاحة لتطبيقات Android التي تستخدم الإصدار 17.10.0 أو إصدارًا أحدث من حزمة تطوير البرامج (SDK) الخاصة بـ Firebase AI Logic (الإصدار 34.10.0 أو إصدارًا أحدث من BoM) والتي تعمل على أجهزة معيّنة. وتخضع هذه الميزة لبنود خدمة ML Kit والبنود الخاصة بجوانب الذكاء الاصطناعي التوليدي في ML Kit.

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

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

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

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

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

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

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

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

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

قبل البدء

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

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

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

البدء

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

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

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

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

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

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

  5. عندما يُطلب منك اختيار "مقدّم خدمة Gemini API"، ننصحك باختيار Gemini Developer API، ما يتيح لك البدء بسرعة بدون أي تكلفة.

    في أي وقت لاحق، يمكنك إعداد Agent Platform Gemini API (formerly Vertex AI) (ومتطلباته المتعلقة بالفوترة).

  6. واصِل العمل في سير العمل لإعداد واجهات برمجة التطبيقات والخدمات المرتبطة المطلوبة لتطبيق Firebase AI Logic.

    اعتبارًا من أوائل يوليو 2026، ستفرض هذه المرحلة من سير العمل تلقائيًا استخدام Firebase App Check مع AI Logic، وهي خدمة مهمة تساعد في حماية Gemini API عند الوصول إليه مباشرةً من تطبيقك. وكجزء من خطوات البدء (راجِع الخطوات لاحقًا في هذا الدليل)، عليك ضبط App Check مقدّم خدمة تصحيح الأخطاء لتطوير التطبيق محليًا عند فرض استخدام App Check.

  7. انتقِل إلى الخطوة التالية في هذا الدليل لإضافة حِزم 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 وApp Check لنظام التشغيل Android:

Kotlin 

dependencies {
  // ... other androidx dependencies

  // Add the dependencies for the Firebase AI Logic and App Check libraries
  // Note that the on-device SDK is not yet included in the Firebase Android BoM
  implementation("com.google.firebase:firebase-ai:17.15.0")
  implementation("com.google.firebase:firebase-ai-ondevice:16.0.0-beta04")
  implementation("com.google.firebase:firebase-appcheck-debug:19.4.0")
}

Java

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

dependencies {
  // ... other androidx dependencies

  // Add the dependencies for the Firebase AI Logic and App Check libraries
  // Note that the on-device SDK is not yet included in the Firebase Android BoM
  implementation("com.google.firebase:firebase-ai:17.15.0")
  implementation("com.google.firebase:firebase-ai-ondevice:16.0.0-beta04")
  implementation("com.google.firebase:firebase-appcheck-debug:19.4.0")

  // 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: ضبط مقدّم خدمة تصحيح الأخطاء App Check للتطوير المحلي

اعتبارًا من أوائل يوليو 2026، وكجزء من آلية الإعداد الموجّه لميزة AI Logic في Play Console، سيتم فرض استخدام Firebase App Check تلقائيًا لحماية Gemini API. للتطوير على الجهاز، عليك ضبط App Check موفر تصحيح الأخطاء لتجاوز عملية التصديق مع الحفاظ على فرض App Check.

  1. في إصدار مخصص لتصحيح الأخطاء، اضبط App Check لاستخدام مصنع مقدّم خدمة تصحيح الأخطاء:

    Kotlin

    Firebase.initialize(context = this)
Firebase.appCheck.installAppCheckProviderFactory(
    DebugAppCheckProviderFactory.getInstance(),
)

    Java

    FirebaseApp.initializeApp(/*context=*/ this);
FirebaseAppCheck firebaseAppCheck = FirebaseAppCheck.getInstance();
firebaseAppCheck.installAppCheckProviderFactory(
        DebugAppCheckProviderFactory.getInstance());

  2. احصل على رمز تصحيح الأخطاء:

    1. شغِّل تطبيقك في المحاكي أو على جهاز الاختبار.

    2. ابحث عن رمز تصحيح الأخطاء App Check في سجلاتك. على سبيل المثال:

      D DebugAppCheckProvider: Enter this debug secret into the allow list
in the Firebase Console for your project: 123a4567-b89c-12d3-e456-789012345678

    3. انسخ الرمز المميّز (مثلاً، 123a4567-b89c-12d3-e456-789012345678).

  3. سجِّل رمز تصحيح الأخطاء في App Check باتّباع الخطوات التالية:

    1. في Firebase، انتقِل إلى علامة التبويب الأمان > فحص التطبيقات > التطبيقات.

    2. ابحث عن تطبيقك، وانقر على القائمة الكاملة ()، ثم اختَر إدارة رموز تصحيح الأخطاء.

    3. اتّبِع التعليمات الظاهرة على الشاشة لتسجيل رمز تصحيح الأخطاء.

للحصول على تفاصيل حول مقدّم خدمة تصحيح الأخطاء (بما في ذلك كيفية الحصول على رمز تصحيح أخطاء جديد)، يُرجى الاطّلاع على مستندات App Check الرسمية.

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

استخدِم 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(). يؤدي ذلك إلى تحميل النموذج على الجهاز فقط في الذاكرة وتهيئة مكوّنات وقت التشغيل.

الخطوة 5: تهيئة الخدمة وإنشاء مثيل نموذج

انقر على موفّر 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);

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

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

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

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

يمكنك استخدام 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، وتحديد المصدر باستخدام Google Search، وتحديد المصدر باستخدام Google Maps)

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

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

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

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

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

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

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

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

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


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