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


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

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

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

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

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

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

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

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

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

طُرز Gemini المتوافقة

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

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

    • gemini-3.1-pro-preview
    • ‫gemini-3.8-flash (والإصدارات الأقدم gemini-3.7-flash و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. يُرجى العِلم أنّ طُرز 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. تقدّم سير العمل في وحدة التحكّم تعليمات عامة حول إضافة حزمة تطوير البرامج (SDK) لمنصة Firebase إلى تطبيقك، لذا انتقِل إلى الخطوة التالية في هذا الدليل للحصول على تعليمات محدّدة بشأن Firebase AI Logic.

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

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

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

    2. أدخِل عنوان URL لمستودع حزمة تطوير البرامج (SDK) من Firebase لنظام التشغيل Apple:

      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، انتقِل إلى خدمات الذكاء الاصطناعي > منطق الذكاء الاصطناعي.

  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.8-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.8-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.8-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 من خلال إطار عمل "النماذج الأساسية" من Apple