شروع کنید: از طریق چارچوب مدل‌های بنیادی اپل به رابط برنامه‌نویسی کاربردی (API) جمینی دسترسی پیدا کنید


در WWDC 2026، اپل چارچوب مدل‌های بنیاد (Foundation Models) را برای آداپتورهای مدل شخص ثالث باز کرد، به این معنی که می‌توانید از طریق چارچوب مدل‌های بنیاد (Foundation Models) با استفاده از همان API که برای دسترسی به مدل‌های روی دستگاه استفاده می‌کنید، به مدل‌های میزبانی شده توسط ابر (مانند Gemini ) دسترسی پیدا کنید.

در برنامه خود، می‌توانید نمونه مدل را تغییر دهید تا درخواست‌هایتان را به استنتاج روی دستگاه یا ابری، متناسب با مورد استفاده‌تان، هدایت کنید:

  • مدل‌های روی دستگاه، حداکثر حریم خصوصی، بدون هزینه و پشتیبانی آفلاین را ارائه می‌دهند.
  • مدل‌های Gemini مبتنی بر ابر، پنجره‌های زمینه‌ای بزرگ، قابلیت‌های پیشرفته و قدرت استدلال بیشتری را ارائه می‌دهند.

شما می‌توانید با استفاده از Firebase SDK برای پلتفرم‌های Apple - به ویژه کتابخانه Firebase AI Logic - از طریق چارچوب Foundation Models اپل به مدل‌های Gemini که بر روی فضای ابری میزبانی می‌شوند، دسترسی پیدا کنید . این راهنما نحوه شروع کار را به شما نشان می‌دهد.

برای محافظت از دسترسی به مدل‌های Gemini ، این راهنما همچنین به شما نشان می‌دهد که چگونه Firebase App Check راه‌اندازی کنید، که حتی در طول توسعه نیز بسیار مهم است.

پیش‌نیازها

  • آخرین نسخه بتای Xcode 27 را نصب کنید.

  • یک شبیه‌ساز پلتفرم اپل یا یک دستگاه فیزیکی، که هر دو نسخه بتای سیستم عامل مربوطه را اجرا می‌کنند (برای مثال، iOS 27 بتا).

  • یک پروژه جدید Xcode از یک اپلیکیشن پلتفرم اپل با استفاده از رابط کاربری SwiftUI.

مدل‌های پشتیبانی‌شده‌ی جمینی

ادغام با چارچوب مدل‌های Foundation اپل، مدل‌های Gemini زیر را پشتیبانی می‌کند.

  • مدل‌های عمومی

    • gemini-3.1-pro-preview
    • gemini-3.5-flash
    • gemini-3.1-flash-lite

  • مدل‌های تولید تصویر

    • gemini-3-pro-image-preview (معروف به "نانو موز پرو")
    • gemini-3.1-flash-image-preview (معروف به "نانو موز ۲")
    • gemini-2.5-flash-image (معروف به "نانو موز")

مدل‌های Gemini Live API و مدل‌های Imagen پشتیبانی نمی‌شوند . توجه داشته باشید که مدل‌های Gemini 2.5 از نظر فنی پشتیبانی می‌شوند، اما برای پروژه‌های جدید توصیه نمی‌شوند و نیاز به پیکربندی خاصی دارند که در این راهنماها پوشش داده نشده است.

مرحله ۱: ایجاد یک پروژه Firebase

توصیه می‌کنیم برای بررسی این ادغام، با یک پروژه جدید Firebase شروع کنید.

  1. وارد کنسول Firebase شوید.

  2. روی ایجاد یک پروژه جدید Firebase کلیک کنید.

  3. دستورالعمل‌های روی صفحه را دنبال کنید. نیازی به فعال کردن گوگل آنالیتیکس نیست .

مرحله ۲: اتصال برنامه به فایربیس

برای اتصال برنامه خود به Firebase، باید آن را در پروژه Firebase خود ثبت کنید و یک فایل پیکربندی به پایگاه کد خود اضافه کنید.

  1. در مرکز صفحه نمای کلی پروژه ، روی آیکون iOS+ کلیک کنید تا گردش کار راه‌اندازی شود.

  2. اپلیکیشن خود را ثبت کنید:

    1. شناسه بسته برنامه خود را وارد کنید. مطمئن شوید که با شناسه بسته پروژه‌ای که در Xcode می‌سازید، مطابقت دارد.

    2. روی ثبت برنامه کلیک کنید.

  3. فایل پیکربندی Firebase را اضافه کنید. این فایل شامل تنظیمات مربوط به Firebase SDK برای اتصال به پروژه Firebase شما است.

    1. برای دریافت فایل پیکربندی خود، روی دانلود GoogleService-Info.plist کلیک کنید.

    2. GoogleService-Info.plist را به ریشه پروژه Xcode خود منتقل کنید و آن را به همه targetها اضافه کنید.

    3. در کنسول Firebase روی Next کلیک کنید.

  4. گردش کار در کنسول، دستورالعمل‌های عمومی برای افزودن Firebase SDK به برنامه شما ارائه می‌دهد، بنابراین برای دستورالعمل‌های خاص برای Firebase AI Logic به مرحله بعدی این راهنما بروید.

مرحله 3: کتابخانه‌های Firebase را اضافه کنید و Firebase را در برنامه خود مقداردهی اولیه کنید

  1. برای افزودن کتابخانه‌های مورد نیاز Firebase از Swift Package Manager استفاده کنید:

    1. در Xcode، در حالی که پروژه برنامه شما باز است، File > Add Packages را انتخاب کنید.

    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()
      }
    }
  }
}

مرحله ۴: فعال‌سازی و ایمن‌سازی سرویس‌های فایربیس

اکنون که برنامه شما برای استفاده از Firebase پیکربندی شده است، باید سرویس Firebase AI Logic را فعال کرده و با استفاده از Firebase App Check از دسترسی به API های مرتبط با آن محافظت کنید.

مرحله 4a: منطق هوش مصنوعی فایربیس را در پروژه فایربیس خود تنظیم کنید

  1. در کنسول Firebase ، به بخش سرویس‌های هوش مصنوعی > منطق هوش مصنوعی بروید.

  2. برای شروع گردش کار تنظیمات، روی شروع کار کلیک کنید.

  3. توصیه می‌کنیم برای شروع سریع و رایگان، ارائه‌دهنده‌ی Gemini Developer API را انتخاب کنید.

مرحله 4b: تنظیم Firebase App Check در پروژه Firebase خود

در صورت اعمال، Firebase App Check فقط درخواست‌های ورودی را که از برنامه واقعی شما و یک دستگاه دستکاری نشده هستند، مجاز می‌داند. Firebase App Check از بسیاری از ارائه دهندگان گواهی، از جمله App Attest اپل، پشتیبانی می‌کند.

مراحل زیر برای تنظیمات اولیه و پیش‌فرض App Check است. درباره گزینه‌های پیکربندی اضافی برای App Check (مانند تنظیم TTL توکن‌ها و فعال کردن توکن‌های با کاربرد محدود) بیشتر بدانید.

در اینجا نحوه ثبت ارائه دهنده App Attest در کنسول Firebase آورده شده است:

  1. در کنسول Firebase ، به مسیر Security > App Check بروید.

  2. روی شروع به کار کلیک کنید.

  3. در برگه برنامه‌ها ، برنامه خود را برای استفاده از App Check با ارائه‌دهنده App Attest ثبت کنید.

  4. در تب APIها ، گزینه Firebase AI Logic را انتخاب کنید و روی Enforce کلیک کنید.

مرحله ۴c: پیکربندی ارائه‌دهنده اشکال‌زدایی App Check برای توسعه محلی

برای توسعه محلی، ارائه‌دهنده اشکال‌زدایی بررسی برنامه (App Check Debug Provider) را پیکربندی کنید. راه‌اندازی این ارائه‌دهنده، فرآیند گواهی‌دهی (attestation) را در طول توسعه دور می‌زند، بنابراین می‌توانید منطق برنامه خود را بدون تغییر پیکربندی امنیتی عملیاتی که در بالا تنظیم کرده‌اید، تأیید کنید.

  1. در پروژه Xcode خود، FirebaseAppCheck را وارد کنید و قبل از پیکربندی Firebase App Check با debug provider factory مقداردهی اولیه کنید.

    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. توکن اشکال‌زدایی خود را در کنسول Firebase به App Check ارائه دهید:

    1. در کنسول Firebase ، به مسیر Security > App Check > Apps بروید.

    2. برنامه‌ی خود را پیدا کنید، روی منوی سرریز ( ) کلیک کنید و سپس مدیریت توکن‌های اشکال‌زدایی (Manage debug tokens ) را انتخاب کنید.

    3. روی «افزودن نشانه اشکال‌زدایی» کلیک کنید، یک نام وارد کنید (مثلاً « My Simulator »)، نشانه را جای‌گذاری کنید و سپس روی «ذخیره» کلیک کنید.

برای جزئیات بیشتر در مورد ارائه‌دهنده اشکال‌زدایی (از جمله نحوه دریافت یک توکن اشکال‌زدایی جدید)، به اسناد رسمی App Check مراجعه کنید.

مرحله ۵: سرویس منطق هوش مصنوعی را در برنامه خود راه‌اندازی کنید

برای مشاهده محتوا و کد مخصوص ارائه‌دهنده در این صفحه، روی ارائه‌دهنده API Gemini خود کلیک کنید.

با پیکربندی 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.5-flash")

مرحله ۶: ارسال درخواست به مدل 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.5-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") پشتیبانی می‌کنند. نمونه‌هایی از این نوع درخواست‌ها را در اسناد یا در برنامه نمونه مشاهده کنید.

پاسخ را پخش کنید

شما می‌توانید با منتظر نماندن برای کل نتیجه از تولید مدل، به تعاملات سریع‌تری دست یابید و در عوض از استریمینگ برای مدیریت نتایج جزئی استفاده کنید. برای استریم کردن پاسخ، به جای respond(to:) streamResponse(to:) 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.5-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
}

مراحل بعدی


در مورد دسترسی به API Gemini از طریق چارچوب مدل‌های بنیادی اپل، بازخورد خود را ارائه دهید.