البدء: الوصول إلى Gemini API من خلال إطار عمل Foundation Models من Apple


في مؤتمر WWDC 2026، أتاحت Apple إطار عمل Foundation Models لمحوّلات النماذج الخارجية ، ما يعني أنّه يمكنك الوصول إلى النماذج المستضافة على السحابة الإلكترونية (مثل Gemini) من خلال إطار عمل Foundation Models باستخدام واجهة برمجة التطبيقات نفسها التي تستخدمها للوصول إلى النماذج على الجهاز.

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

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

يمكنك الوصول إلى نماذج Gemini المستضافة على السحابة الإلكترونية من خلال إطار عمل Foundation Models من Apple باستخدام حزمة Firebase SDK لمنصات Apple، وتحديدًا مكتبة Firebase AI Logic. يوضّح لك هذا الدليل كيفية بدء استخدامها.

لحماية إمكانية الوصول إلى نماذج Gemini، يوضّح لك هذا الدليل أيضًا كيفية إعداد Firebase App Check، وهي ميزة ضرورية حتى أثناء التطوير.

المتطلبات الأساسية

  • تثبيت أحدث إصدار تجريبي من Xcode 27.

  • محاكي لمنصة Apple أو جهاز فعلي، وكلاهما يعملان بالإصدار التجريبي المقابل من نظام التشغيل (على سبيل المثال، الإصدار التجريبي من iOS 27)

  • مشروع جديد في Xcode لتطبيق على منصات Apple يستخدم واجهة SwiftUI

النماذج المتوافقة Gemini

يتوافق التكامل مع إطار عمل Foundation Models من Apple مع النماذج التالية Gemini.

  • النماذج ذات الغرض العام

    • gemini-3.1-pro-preview
    • gemini-3.6-flash (والإصدار الأقدم gemini-3.5-flash)
    • gemini-3.5-flash-lite (والإصدار الأقدم gemini-3.1-flash-lite)

  • النماذج التي تنشئ الصور

    • gemini-3-pro-image (المعروف أيضًا باسم "Nano Banana Pro")
    • gemini-3.1-flash-image (المعروف أيضًا باسم "Nano Banana 2")
    • gemini-3.1-flash-lite-image (المعروف أيضًا باسم "Nano Banana 2 Lite")

Gemini Live API النماذج وImagen النماذج لا تتوافق. يُرجى العِلم أنّه يمكن من الناحية الفنية استخدام نماذج Gemini 2.5، ولكن لا يُنصح بها للمشاريع الجديدة وتتطلّب إعدادًا خاصًا لا يتم تناوله في هذه الأدلة.

الخطوة 1: إنشاء مشروع Firebase

ننصحك بالبدء بمشروع جديد على Firebase لاستكشاف هذا التكامل.

  1. سجِّل الدخول إلى Firebase وحدة تحكُّم.

  2. انقر على إنشاء مشروع جديد على Firebase.

  3. اتّبِع التعليمات الظاهرة على الشاشة. ليس عليك تفعيل "إحصاءات Google".

الخطوة 2: ربط تطبيقك بمنصة Firebase

لربط تطبيقك بمنصة Firebase، عليك تسجيله في مشروع Firebase وإضافة ملف إعداد إلى قاعدة الرموز البرمجية.

  1. في منتصف صفحة نظرة عامة على المشروع ، انقر على رمز iOS+ لبدء سير عمل الإعداد.

  2. سجِّل تطبيقك:

    1. أدخِل رقم تعريف الحزمة لتطبيقك. تأكَّد من أنّه يطابق رقم تعريف الحزمة للمشروع الذي تنشئه في Xcode.

    2. انقر على تسجيل التطبيق.

  3. أضِف ملف إعداد Firebase. يحتوي هذا الملف على إعدادات حزمة Firebase SDK للاتصال بمشروع Firebase.

    1. انقر على تنزيل GoogleService-Info.plist للحصول على ملف الإعداد.

    2. انقِل ملف GoogleService-Info.plist إلى جذر مشروع Xcode وأضِفه إلى كل الأهداف.

    3. انقر على التالي في وحدة تحكُّم Firebase.

  4. يقدّم سير العمل في وحدة التحكّم تعليمات عامة لإضافة حزمة Firebase SDK إلى تطبيقك، لذا انتقِل إلى الخطوة التالية في هذا الدليل للحصول على تعليمات محدّدة بشأن Firebase AI Logic.

الخطوة 3: إضافة مكتبات Firebase وإعداد Firebase في تطبيقك

  1. استخدِم Swift Package Manager لإضافة مكتبات Firebase المطلوبة:

    1. في Xcode، افتح مشروع تطبيقك، ثم انقر على ملف > إضافة حِزم.

    2. أدخِل عنوان URL لمستودع Firebase Apple SDK:

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

    3. اختَر الفرع كقاعدة الاعتمادية وأدخِل wwdc26-preview.

    4. انقر على إضافة حزمة. سيحلّ Xcode التبعيات وينزّلها.

    5. عندما يُطلب منك ذلك، أضِف مكتبتَي FirebaseAILogic وFirebaseAppCheck إلى هدف تطبيقك.

  2. أعِدّ Firebase عند بدء تشغيل تطبيقك من خلال إضافة الرمز البرمجي التالي إلى نقطة الدخول الرئيسية لتطبيقك:

    import SwiftUI
import FirebaseCore

@main
struct YourApp: App {
  init() {
    FirebaseApp.configure()
  }

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

الخطوة 4: تفعيل خدمات Firebase وتأمينها

بعد ضبط تطبيقك لاستخدام Firebase، عليك تفعيل خدمة Firebase AI Logic وحماية إمكانية الوصول إلى واجهات برمجة التطبيقات المرتبطة بها باستخدام Firebase App Check.

الخطوة 4أ: إعداد Firebase AI Logic في مشروعك على Firebase

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

  2. انقر على البدء لبدء سير عمل الإعداد الموجَّه.

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

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

  4. تابِع سير العمل لإعداد واجهات برمجة التطبيقات المطلوبة والخدمات المرتبطة بها لـ Firebase AI Logic.

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

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

للتطوير المحلي، عليك ضبط 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ميزة "التحقّق من التطبيق" الرسمية.

الخطوة 5: إعداد خدمة AI Logic في تطبيقك

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

بعد ضبط Firebase وميزة App Check، يمكنك الآن إعداد خدمة Firebase AI Logic في تطبيقك.

import FoundationModels
import FirebaseCore
import FirebaseAILogic

// Initialize the Gemini Developer API backend service.
let ai = FirebaseAI.firebaseAI(backend: .googleAI())
// Initialize a `geminiLanguageModel` with a Gemini model that supports your use case.
let model = ai.geminiLanguageModel(name: "gemini-3.6-flash")

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

بعد إعداد Firebase AI Logic وحمايته وإعداده في تطبيقك، أنت مستعد لإرسال طلب إلى نموذج Gemini.

يوضّح المثال التالي أبسط أنواع الطلبات، وهو إنشاء نص من طلب نصي فقط:

import FoundationModels
import FirebaseCore
import FirebaseAILogic

// Initialize the Gemini Developer API backend service.
let ai = FirebaseAI.firebaseAI(backend: .googleAI())
// Initialize a `geminiLanguageModel` with a Gemini model that supports your use case.
let model = ai.geminiLanguageModel(name: "gemini-3.6-flash")


// Create a session by injecting the model into Apple's `LanguageModelSession`.
let session = LanguageModelSession(model: model)

// Generate a text response to a prompt.
let response = try await session.respond(to: "Write a story about a magic backpack.")
print(response.content)

تتيح نماذج Gemini أيضًا أنواعًا أخرى من الطلبات، مثل تحليل الصور وملفات PDF ، و إنشاء ناتج JSON منظَّم ، و إنشاء الصور (باستخدام نماذج "Nano Banana"). يمكنك الاطّلاع على أمثلة لهذه الأنواع من الطلبات في المستندات أو في نموذج التطبيق.

عرض الرد تدريجيًا

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

import FoundationModels
import FirebaseCore
import FirebaseAILogic

// Initialize the Gemini Developer API backend service.
let ai = FirebaseAI.firebaseAI(backend: .googleAI())
// Initialize a `geminiLanguageModel` with a Gemini model that supports your use case.
let model = ai.geminiLanguageModel(name: "gemini-3.6-flash")


// Create a session by injecting the model into Apple's `LanguageModelSession`.
let session = LanguageModelSession(model: model)

// Generate a streamed text response to a prompt.
// To stream the response, use `streamResponse(to:)` instead of `respond(to:)`
let stream = session.streamResponse(to: "Write a story about a magic backpack.")
var response = ""
for try await snapshot in stream {
  // The snapshot contains *all* content generated so far.
  response = snapshot.content
}

الخطوات التالية

  • استكشاف الـ إمكانات المتاحة عند الوصول إلى الـ Gemini API من خلال إطار عمل Foundation Models من Apple.
  • التعرّف على كيفية ضبط النموذج للتحكّم في ردوده، بما في ذلك ضبط مستوى التفكير ("الاستنتاج")
  • التعرّف على كيفية تزويد النموذج بالأدوات، بما في ذلك المعلومات الأساسية للحصول على معلومات حديثة
  • مزيد من المعلومات حول Firebase App Check وكيفية حماية مواردك


إرسال ملاحظات حول الوصول إلى Gemini API من خلال إطار عمل Foundation Models من Apple