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

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

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

يُرجى العِلم أنّ الاستدلال على الجهاز من خلال خدمة Firebase AI Logic متاح لتطبيقات Apple التي تستخدم حزمة تطوير البرامج (SDK) لخدمة Firebase AI Logic الإصدار 12.13.0 أو إصدار أحدث، والتي تعمل على الأجهزة التي تم تفعيل ميزة 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، افتح مشروع تطبيقك وانتقِل إلى ملف > إضافة موارد الاعتمادية للحزمة.

  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 أو النماذج المستضافة على السحابة الإلكترونية.

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

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

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

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

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

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

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

قيود إضافية

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


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