شروع کار: دسترسی به Gemini API ازطریق چارچوب «مدل‌های پایه» Apple


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

در برنامه‌تان، می‌توانید نمونه مدل را عوض کنید تا درخواست‌هایتان را به استنباط درون‌دستگاهی یا ابری هدایت کنید تا با مورد استفاده‌تان مطابقت داشته باشد:

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

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

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

پیش‌نیازها

  • ‫Xcode 27 را از Mac App Store بارگیری کنید.

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

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

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

ادغام با چارچوب «مدل‌های بنیادی» 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 ازنظر فنی پشتیبانی می‌شوند، اما برای پروژه‌های جدید توصیه نمی‌شوند و به پیکربندی ویژه‌ای نیاز دارند که در این راهنماها پوشش داده نشده است.

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

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

  1. به سیستم کنسول Firebase وارد شوید.

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

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

مرحله ۲: متصل کردن برنامه به Firebase

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

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

  2. برنامه‌تان را ثبت کنید:

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

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

  3. فایل پیکربندی Firebase را اضافه کنید. این فایل حاوی تنظیمات «کیت توسعه نرم‌افزار Firebase» برای اتصال به پروژه Firebase شما است.

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

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

    3. در کنسول Firebase، روی بعدی کلیک کنید.

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

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

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

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

    2. نشانی وب مخزن «کیت توسعه نرم‌افزار Firebase Apple» را وارد کنید:

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

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

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

مرحله ۴الف: راه‌اندازی Firebase AI Logic در پروژه Firebase

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

  2. برای راه‌اندازی گردش کار راه‌اندازی گام‌به‌گام، روی شروع به کار کلیک کنید.

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

    هرزمان بخواهید می‌توانید Agent Platform Gemini API (formerly Vertex AI) (و الزامات آن برای صدور صورت‌حساب) را راه‌اندازی کنید.

  4. برای راه‌اندازی میاناهای برنامه‌سازی کاربردی موردنیاز و سرویس‌های مرتبط برای Firebase AI Logic، در گردش کار ادامه دهید.

    از اوایل ژوئیه ۲۰۲۶، این مرحله از گردش کار به‌طور خودکار Firebase App Check را برای AI Logic اعمال می‌کند، که سرویسی حیاتی برای کمک به محافظت از Gemini API هنگام دسترسی مستقیم از برنامه شما است. به‌عنوان بخشی از شروع کار (مراحل را در ادامه این راهنما ببینید)، وقتی App Check اعمال می‌شود، باید App Check ارائه‌دهنده اشکال‌زدایی را برای توسعه محلی پیکربندی کنید.

مرحله ۴ب: پیکربندی ارائه‌دهنده اشکال‌زدایی 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 را بررسی کنید.

مرحله ۵: مقداردهی اولیه سرویس 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")

مرحله ۶: ارسال درخواست به مدل 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 ساختاریافته ، و تولید تصاویر (بااستفاده از مدل‌های «نانو بنانا»). نمونه‌هایی از این نوع درخواست‌ها را در اسناد یا در برنامه نمونه ببینید.

جاری‌سازی پاسخ

با منتظر نماندن برای دریافت کل نتیجه از تولید مدل می‌توانید به تعامل‌های سریع‌تر دست یابید و درعوض از جاری‌سازی برای مدیریت نتایج جزئی استفاده کنید. برای جاری‌سازی پاسخ، به‌جای respond(to:) از streamResponse(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.
  • با نحوه پیکربندی مدل برای کنترل پاسخ‌های آن، ازجمله تنظیم سطح تفکر («استدلال») آشنا شوید.
  • با نحوه ارائه ابزار به مدل آشنا شوید، ازجمله زمینه‌سازی برای اطلاعات به‌روز.
  • درباره Firebase App Check و نحوه محافظت آن از منابعتان بیشتر بخوانید.


ارائه بازخورد درباره دسترسی به Gemini API ازطریق چارچوب «مدل‌های پایه» Apple