البدء: الوصول إلى 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، وهو أمر مهم حتى أثناء عملية التطوير.

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

• نزِّل Xcode 27 من متجر Mac App Store.

• محاكي نظام 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. يحتوي هذا الملف على إعدادات "حزمة تطوير البرامج (SDK) لمنصّة Firebase" للربط بمشروعك على 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 لمستودع Firebase Apple SDK:

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

   3. اختَر الإصدار 12.19.0 على الأقل.

   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. ابحث عن تطبيقك، وانقر على القائمة الكاملة (more_vert)، ثم اختَر إدارة رموز تصحيح الأخطاء.

   3. اتّبِع التعليمات الظاهرة على الشاشة لتسجيل رمز تصحيح الأخطاء.

للحصول على تفاصيل حول مقدّم خدمة تصحيح الأخطاء (بما في ذلك كيفية الحصول على رمز تصحيح أخطاء جديد)، اطّلِع على مستندات App Check الرسمية.

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

بعد إعداد 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 من خلال إطار عمل Foundation Models من Apple
• تعرَّف على كيفية ضبط النموذج للتحكّم في ردوده، بما في ذلك ضبط مستوى التفكير ("الاستدلال").
• تعرَّف على كيفية تزويد النموذج بالأدوات، بما في ذلك توفير معلومات حديثة.
• Firebase App Check مزيد من المعلومات حول هذه الميزة وكيفية حمايتها لمواردك

تقديم ملاحظات حول الوصول إلى Gemini API من خلال إطار عمل "النماذج الأساسية" من Apple