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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

البدء

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

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

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

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

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

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

استخدِم 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) لمنصات Apple في Firebase:

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

  3. اختَر أحدث إصدار من حزمة تطوير البرامج (SDK).

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

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

الخطوة 3: ضبط مقدّم خدمة تصحيح الأخطاء في App Check للتطوير على الجهاز

اعتبارًا من أوائل يوليو 2026، سيتم فرض Firebase App Check تلقائيًا لحماية Gemini API كجزء من عملية الإعداد الموجَّهة لـ AI Logic في وحدة التحكّم. للتطوير على الجهاز، عليك ضبط 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 أو النماذج المستضافة على السحابة الإلكترونية.

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

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

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

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

    • إرسال طلبات تتجاوز 4096 رمزًا مميزًا (أو ما يقرب من 3000 كلمة باللغة الإنجليزية)

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

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

قيود إضافية

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


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