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

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

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

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

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

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

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

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

    • توفير تجربة تطبيق مماثلة لجميع العملاء بغض النظر عن جهاز المستخدم النهائي
    • تحسين توفّر ميزات الذكاء الاصطناعي التوليدي، بغض النظر عن إمكانية الاتصال بالإنترنت أو قيود الحصة أو إمكانات الجهاز

الإمكانات وواجهات برمجة التطبيقات والأجهزة المتوافقة

قبل تنفيذ الاستنتاج المختلط والاستنتاج على الجهاز فقط باستخدام Firebase AI Logic، راجِع هذا القسم للتعرّف على الميزات المتوافقة مع تطبيقات Apple.

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

تتيح الاستدلال على الجهاز فقط إنشاء النصوص، وتحديدًا إمكانات إنشاء النصوص التالية:

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

واجهات برمجة التطبيقات والأجهزة المتوافقة

البدء

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

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

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

استخدِم Swift Package Manager (SPM) لتثبيت ملحقات Xcode وإدارتها. لا يتوفّر الدعم المختلط إلا عند استخدام SPM.

تتيح مكتبة Firebase AI Logic الوصول إلى واجهات برمجة التطبيقات للتفاعل مع النماذج التوليدية. يتم تضمين المكتبة كجزء من Firebase SDK لأجهزة Apple (firebase-ios-sdk).

إذا كنت تستخدم Firebase حاليًا، تأكَّد من أنّ حزمة Firebase هي الإصدار 12.13.0 أو إصدار أحدث.

  1. في Xcode، بعد فتح مشروع تطبيقك، انتقِل إلى ملف > إضافة موارد الاعتمادية للحزمة (File > Add Package Dependencies).

  2. عندما يُطلب منك ذلك، أضِف مستودع حزمة تطوير البرامج (SDK) لمنصة Firebase على أجهزة Apple:

    https://github.com/firebase/firebase-ios-sdk

  3. اختَر أحدث إصدار من حزمة SDK.

  4. اختَر مكتبتَي FirebaseAILogic وFirebaseAppCheck.

عند الانتهاء، سيبدأ Xcode تلقائيًا في حلّ التبعيات وتنزيلها في الخلفية.

الخطوة 3: ضبط مقدّم خدمة تصحيح الأخطاء App Check للتطوير المحلي

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

في ما يلي كيفية استخدام مقدّم خدمة تصحيح الأخطاء أثناء تشغيل تطبيقك في محاكي بشكل تفاعلي (على سبيل المثال، أثناء التطوير المحلي):

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

    import SwiftUI
import FirebaseCore
import FirebaseAppCheck

@main
struct YourApp: App {
  init() {
    let providerFactory = AppCheckDebugProviderFactory()
    AppCheck.setAppCheckProviderFactory(providerFactory)
    FirebaseApp.configure()
  }

  var body: some Scene {
    WindowGroup {
      NavigationView {
        ContentView()
      }
    }
  }
}

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

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

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

      <Warning> [AppCheckCore][I-GAC004001] App Check debug token: '123a4567-b89c-12d3-e456-789012345678'.

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

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

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

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

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

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

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

انقر على مقدّم خدمة Gemini API لعرض المحتوى والرمز الخاصين بمقدّم الخدمة على هذه الصفحة.

يجب إعداد ما يلي قبل إرسال طلب إلى النموذج.

  1. ابدأ الخدمة لمقدّم خدمة Gemini API الذي اخترته.

  2. أنشئ مثيلاً من GenerativeModelSession باستخدام HybridModel.

  3. اضبط طرازَي primary وsecondary استنادًا إلى إعداداتك المفضّلة. يمكنك ضبط ترتيب الاستنتاج الذي يتمّ محاولة تنفيذه:

    • محاولة الاستدلال على الجهاز أولاً، ولكن السماح بالرجوع إلى السحابة الإلكترونية: اضبط primary على نموذج "نظام" وsecondary على نموذج سحابة إلكترونية.

    • محاولة الاستدلال في السحابة الإلكترونية أولاً، ولكن السماح بالرجوع إلى الاستدلال على الجهاز فقط: اضبط قيمة primary على نموذج سحابي وقيمة secondary على نموذج "نظام".

    يُرجى العِلم أنّ حزمة تطوير البرامج (SDK) تتيح ضبط سمة واحدة فقط من model، ما يعني أنّ حزمة تطوير البرامج (SDK) ستحاول فقط إجراء الاستنتاج إما على الجهاز أو في السحابة الإلكترونية. ومع ذلك، للحصول على تجربة هجينة، عليك إنشاء HybridModel وضبط كل من نموذجي primary وsecondary.

    يمكنك الاطّلاع على مزيد من المعلومات حول سلوك "أوضاع الاستدلال" (ترتيب محاولات الاستدلال) في خيارات الإعداد.

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

// Initialize the Gemini Developer API backend service.
let ai = FirebaseAI.firebaseAI(backend: .googleAI())

// Initialize a cloud model that supports your use case.
let cloudModel = ai.geminiModel(name: "GEMINI_MODEL_NAME")
// Initialize an on-device model that supports your use case.
let systemModel = FirebaseAI.SystemLanguageModel.default

// Create a Hybrid Model.
// Provide your preferred model as `primary` and your fallback model as `secondary`.
// In this example, attempt to use on-device model; otherwise, fall back to cloud.
let hybridModel = HybridModel(
  primary: systemModel,
  secondary: cloudModel
)

// Create a GenerativeModelSession with the HybridModel created earlier.
let session = firebaseAI.generativeModelSession(
  model: hybridModel,
)

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

يوضّح لك هذا القسم كيفية إجراء ما يلي:

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

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

لإنشاء نص من طلب يحتوي على نص، استخدِم respond(to:) على النحو التالي:

// Imports + initialization of Gemini API backend service + creation of model session

// Provide a prompt that contains text
let prompt = "Write a story about a magic backpack."

// To generate text output, call `respond(to:)` with the text input
let response = try await session.respond(to: prompt)
print(response.content)

بث نص من إدخال نصي فقط

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

يمكنك تحقيق تفاعلات أسرع من خلال عدم انتظار النتيجة الكاملة من عملية إنشاء النموذج، واستخدام البث المباشر بدلاً من ذلك للتعامل مع النتائج الجزئية. لـ بث نص تم إنشاؤه من طلب يحتوي على نص، استخدِم streamResponse(to:) على النحو التالي:

// Imports + initialization of Gemini API backend service + creation of model session

// Provide a prompt that contains text
let prompt = "Write a story about a magic backpack."

// To stream generated text output, call `streamResponse(to:)` with the text input
let stream = session.streamResponse(to: prompt)
for try await snapshot in stream {
  print(snapshot.content)
}

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

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

الميزات التي لا تتوافق بعد مع الاستدلال الهجين أو الاستدلال على الجهاز

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

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

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

    • إنشاء نصوص من مدخلات متعدّدة الوسائط، مثل الصور والمقاطع الصوتية والفيديوهات والمستندات (ملفات PDF)

    • إنشاء وسائط، مثل الصور أو الملفات الصوتية أو الفيديوهات

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

    • تزويد النموذج الذي يعمل على الجهاز فقط بأدوات مدمجة لمساعدته في إنشاء الرد (مثل تطبيق الرموز البرمجية وسياق عناوين URL وتحديد المصدر من خلال "بحث Search")

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

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

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


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