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


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

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

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

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

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

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

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

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

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

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

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

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

قبل البدء

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

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

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

البدء

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

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

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

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

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

  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 المطلوبة

توفر حزمة 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 و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.14.0")
  implementation("com.google.firebase:firebase-ai-ondevice:16.0.0-beta03")
  implementation("com.google.firebase:firebase-appcheck-debug:19.3.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.14.0")
  implementation("com.google.firebase:firebase-ai-ondevice:16.0.0-beta03")
  implementation("com.google.firebase:firebase-appcheck-debug:19.3.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 في وحدة التحكّم، يتم فرض 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 و 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