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

يمكنك إنشاء تطبيقات وميزات مستندة إلى الذكاء الاصطناعي لأجهزة Apple باستخدام الاستدلال المختلط من خلال Firebase AI Logic. يتيح الاستدلال المختلط تشغيل الاستدلال باستخدام النماذج على الجهاز (وتحديدًا إطار عمل Foundation Models من 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، انتقِل إلى خدمات الذكاء الاصطناعي > منطق الذكاء الاصطناعي.

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

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

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

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

  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. عند المطالبة بذلك، أضِف مستودع حزمة Firebase SDK لمنصات Apple:

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

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

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

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

الخطوة 3: إعداد موفِّر تصحيح الأخطاء App Check لأغراض التطوير المحلي

اعتبارًا من أوائل يوليو 2026، وكجزء من سير عمل الإعداد الإرشادي لـ AI Logic في وحدة التحكّم، يتم فرض 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)

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

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

    • تزويد النموذج على الجهاز فقط بالأدوات المضمّنة لمساعدته في إنشاء ردّه (مثل تنفيذ الرموز البرمجية وسياق عنوان URL وGrounding with Google Search)

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

قيود إضافية

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


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