با مدل‌های میزبانی‌شده در دستگاه و فضای ابری، تجربه‌های ترکیبی در برنامه‌های Apple بسازید

بااستفاده از Firebase AI Logic می‌توانید برنامه‌ها و ویژگی‌های Apple با بهره‌گیری از هوش مصنوعی را با استنباط ترکیبی بسازید. استنتاج ترکیبی امکان اجرای استنتاج را بااستفاده از مدل‌های درون‌دستگاهی (به‌طور خاص چارچوب مدل‌های بنیادی Apple) درصورت دردسترس بودن فراهم می‌کند و درغیراین‌صورت به‌طور یکپارچه به مدل‌های Google میزبانی‌شده در فضای ابری (و بالعکس) بازمی‌گردد.

این صفحه نحوه شروع استفاده از کیت توسعه نرم‌افزار کارخواه و همچنین گزینه‌ها و قابلیت‌های پیکربندی اضافی مانند دما را شرح می‌دهد.

توجه داشته باشید که استنتاج درون‌دستگاهی ازطریق Firebase AI Logic برای برنامه‌های Apple که از Firebase AI Logic SDK نسخه ۱۲.۱۳.۰+ استفاده می‌کنند و در دستگاه‌هایی که Apple Intelligence در آن‌ها فعال است اجرا می‌شوند پشتیبانی می‌شود. این چارچوب تحت حاکمیت الزامات استفاده قابل‌قبول برای چارچوب «مدل‌های پایه Apple» است.

موارد استفاده توصیه‌شده

  • استفاده از مدل درون‌دستگاهی برای استنتاج این مزایا را دارد:

    • حریم خصوصی بهبودیافته
    • استنتاج بدون هزینه
    • عملکرد آفلاین

  • استفاده از عملکرد ترکیبی این موارد را ارائه می‌دهد:

    • تجربه برنامه مشابهی را برای همه مشتریان فراهم کنید، صرف‌نظر از اینکه دستگاه کاربر نهایی چه باشد
    • بهبود دردسترس بودن ویژگی‌های هوش مصنوعی زایا، صرف‌نظر از اتصال‌پذیری اینترنت، محدودیت‌های سهمیه، یا قابلیت‌های دستگاه

قابلیت‌ها، میاناهای برنامه‌سازی کاربردی، و دستگاه‌های پشتیبانی‌شده

قبل‌از پیاده‌سازی استنتاج ترکیبی و درون‌دستگاهی بااستفاده از Firebase AI Logic، این بخش را مرور کنید تا متوجه شوید چه چیزهایی برای برنامه‌های Apple پشتیبانی می‌شود.

قابلیت‌ها و ویژگی‌های پشتیبانی‌شده برای استنباط درون‌دستگاهی

استنتاج درون‌دستگاهی فقط از تولید نوشتار پشتیبانی می‌کند، به‌ویژه قابلیت‌های تولید نوشتار زیر:

حتماً فهرست دقیق استنباط ترکیبی یا درون‌دستگاهی که هنوز پشتیبانی نمی‌شود را در پایین این صفحه مرور کنید.

دستگاه‌ها و میاناهای برنامه‌سازی کاربردی پشتیبانی‌شده

شروع کنید

مطمئن شوید که بخش بالا را که قابلیت‌ها، میاناهای برنامه کاربردی، و دستگاه‌های پشتیبانی‌شده را توضیح می‌دهد مرور کرده‌اید.

این مراحل شروع به کار، تنظیمات عمومی موردنیاز برای هر درخواست پیام‌واره پشتیبانی‌شده‌ای را که می‌خواهید ارسال کنید شرح می‌دهد.

مرحله ۱: راه‌اندازی پروژه Firebase و متصل کردن برنامه به Firebase

  1. به کنسول Firebase وارد شوید، و سپس پروژه Firebase خود را انتخاب کنید.

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

  3. برای راه‌اندازی گردش کار گام‌به‌گام که به شما کمک می‌کند میاناهای برنامه‌سازی کاربردی موردنیاز و منابع پروژه را تنظیم کنید، روی شروع به کار کلیک کنید.

  4. درصورت درخواست، دستورالعمل‌های روی صفحه را برای ثبت برنامه و افزودن پیکربندی Firebase به برنامه دنبال کنید.

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

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

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

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

  7. برای افزودن کیت‌های توسعه نرم‌افزار لازم به برنامه‌تان، به مرحله بعدی در این راهنما بروید.

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

از Swift Package Manager (SPM) برای نصب و مدیریت وابستگی‌های Xcode استفاده کنید. پشتیبانی ترکیبی فقط هنگام استفاده از «مدیر شریک استراتژیک» دردسترس است.

کتابخانه Firebase AI Logic دسترسی به میاناهای برنامه‌سازی کاربردی برای تعامل با مدل‌های زایا را فراهم می‌کند. این کتابخانه به‌عنوان بخشی از کیت توسعه نرم‌افزار Firebase برای پلاتفرم‌های Apple (firebase-ios-sdk) گنجانده شده است.

اگر درحال‌حاضر از Firebase استفاده می‌کنید، مطمئن شوید که بسته Firebase شما نسخه ۱۲.۱۳.۰ یا جدیدتر باشد.

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

  2. وقتی درخواست شد، مخزن کیت توسعه نرم‌افزار پلاتفرم‌های Firebase Apple را اضافه کنید:

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

  3. جدیدترین نسخه کیت توسعه نرم‌افزار را انتخاب کنید.

  4. کتابخانه‌های FirebaseAILogic و FirebaseAppCheck را انتخاب کنید.

وقتی تمام شد، Xcode به‌طور خودکار شروع به حل و بارگیری وابستگی‌های شما در پس‌زمینه می‌کند.

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

از اوایل ژوئیه ۲۰۲۶، به‌عنوان بخشی از گردش کار راه‌اندازی راهنمایی‌شده برای AI Logic در کنسول، Firebase App Check به‌طور خودکار برای محافظت از Gemini API اعمال می‌شود. برای توسعه محلی، باید 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 را بررسی کنید.

مرحله ۴: مقداردهی اولیه سرویس و ایجاد نمونه جلسه مدل

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

قبل‌از ارسال درخواست پیام‌واره به مدل، موارد زیر را راه‌اندازی کنید.

  1. سرویس را برای ارائه‌دهنده Gemini API انتخابی‌تان مقداردهی اولیه کنید.

  2. نمونه GenerativeModelSession را با HybridModel ایجاد کنید.

  3. مدل‌های primary و secondary را براساس اولویت‌هایتان تنظیم کنید. می‌توانید ترتیب استنتاج‌های انجام‌شده را تنظیم کنید:

    • ابتدا استنتاج درون‌دستگاهی را امتحان کنید، اما امکان بازگشت به فضای ابری را فراهم کنید: primary را روی مدل «سیستم» و secondary را روی مدل ابری تنظیم کنید.

    • ابتدا استنباط درون‌ابری را امتحان کنید، اما اجازه دهید به استنباط درون‌دستگاهی برگردد: primary را روی مدل ابری و secondary را روی مدل «سیستم» تنظیم کنید.

    توجه داشته باشید که کیت توسعه نرم‌افزار فقط از تنظیم یک model پشتیبانی می‌کند، یعنی کیت توسعه نرم‌افزار فقط استنتاج درون‌دستگاهی یا ابری را امتحان می‌کند. اما برای تجربه ترکیبی، باید HybridModel ایجاد کنید و هر دو مدل primary و secondary را تنظیم کنید.

    درباره رفتار «حالت‌های استنتاج» (ترتیب استنتاج‌های امتحان‌شده) در گزینه‌های پیکربندی بیشتر بدانید.

مثال زیر نشان می‌دهد که چگونه ابتدا استنتاج درون‌دستگاهی را امتحان کنید، اما اجازه دهید به مدل میزبانی‌شده در فضای ابری بازگردد:

// Initialize the Gemini Developer API backend service.
let ai = FirebaseAI.firebaseAI(backend: .googleAI())

// Initialize a cloud model that supports your use case.
let cloudModel = ai.geminiModel(name: "GEMINI_MODEL_NAME")
// Initialize an on-device model that supports your use case.
let systemModel = FirebaseAI.SystemLanguageModel.default

// Create a Hybrid Model.
// Provide your preferred model as `primary` and your fallback model as `secondary`.
// In this example, attempt to use on-device model; otherwise, fall back to cloud.
let hybridModel = HybridModel(
  primary: systemModel,
  secondary: cloudModel
)

// Create a GenerativeModelSession with the HybridModel created earlier.
let session = firebaseAI.generativeModelSession(
  model: hybridModel,
)

مرحله ۵: ارسال درخواست پیام‌واره به مدل

این بخش به شما نشان می‌دهد که چگونه کارهای زیر را انجام دهید:

تولید نوشتار از ورودی فقط نوشتاری

قبل‌از امتحان کردن این نمونه، مطمئن شوید که بخش شروع به کار این راهنما را تکمیل کرده‌اید.

برای تولید نوشتار از پیام‌واره‌ای که حاوی نوشتار است، از respond(to:) به‌این‌صورت استفاده کنید:

// Imports + initialization of Gemini API backend service + creation of model session

// Provide a prompt that contains text
let prompt = "Write a story about a magic backpack."

// To generate text output, call `respond(to:)` with the text input
let response = try await session.respond(to: prompt)
print(response.content)

جاری‌سازی نوشتار از ورودی فقط نوشتاری

قبل‌از امتحان کردن این نمونه، مطمئن شوید که بخش شروع به کار این راهنما را تکمیل کرده‌اید.

با منتظر نماندن برای دریافت کل نتیجه از تولید مدل می‌توانید به تعامل‌های سریع‌تر دست یابید و درعوض از جاری‌سازی برای مدیریت نتایج جزئی استفاده کنید. برای جاری‌سازی نوشتار تولیدشده از پیام‌واره‌ای که حاوی نوشتار است، از streamResponse(to:) به‌صورت زیر استفاده کنید:

// Imports + initialization of Gemini API backend service + creation of model session

// Provide a prompt that contains text
let prompt = "Write a story about a magic backpack."

// To stream generated text output, call `streamResponse(to:)` with the text input
let stream = session.streamResponse(to: prompt)
for try await snapshot in stream {
  print(snapshot.content)
}

چه کارهای دیگری می‌توانید انجام دهید؟

می‌توانید از گزینه‌ها و قابلیت‌های پیکربندی اضافی مختلفی برای تجربه‌های ترکیبی خود استفاده کنید:

ویژگی‌هایی که هنوز برای استنباط ترکیبی یا درون‌دستگاهی پشتیبانی نمی‌شوند

به‌عنوان نسخه آزمایشی، همه قابلیت‌های Firebase AI Logic یا مدل‌های میزبانی‌شده در فضای ابری پشتیبانی نمی‌شود.

  • موارد زیر برای پیاده‌سازی‌های ترکیبی یا درون‌دستگاهی پشتیبانی نمی‌شود: Gemini Live API و الگوهای پیام‌واره سرور. همچنین، نمی‌توان به تعداد داده‌واحدها تکیه کرد زیرا تعداد در مدل‌های میزبانی‌شده در فضای ابری و درون‌دستگاهی متفاوت خواهد بود، بنابراین هیچ بازگشت شهودی وجود ندارد.

  • ویژگی‌های زیر هنوز برای استنتاج درون‌دستگاهی پشتیبانی نمی‌شوند. اگر می‌خواهید از هرکدام از این ویژگی‌ها استفاده کنید، توصیه می‌کنیم برای داشتن تجربه‌ای سازگارتر، فقط از مدل میزبانی‌شده در فضای ابری استفاده کنید.

    • تولید نوشتار از ورودی‌های چندحالته، مانند تصاویر، صدا، ویدیو، و اسناد (PDF)

    • تولید رسانه، مانند تصویر، صدا، یا ویدیو

    • ارسال درخواست‌هایی که از ۴۰۹۶ واحد (یا تقریباً ۳۰۰۰ کلمه انگلیسی) فراتر می‌روند.

    • ارائه ابزارهای داخلی به مدل درون‌دستگاهی برای کمک به آن در تولید پاسخ (مانند اجرای کد، بافت نشانی وب، و پایه‌مندسازی با «جستجوی Google»)

  • پایش هوش مصنوعی در کنسول Firebase هیچ داده‌ای را برای استنتاج درون‌دستگاهی (ازجمله گزارش‌های درون‌دستگاهی) نشان نمی‌دهد. بااین‌حال، هر استنتاجی که از مدل میزبانی‌شده در فضای ابری استفاده می‌کند می‌تواند درست مانند سایر استنتاج‌ها ازطریق Firebase AI Logic نظارت شود.

محدودیت‌های بیشتر

علاوه‌بر موارد بالا، استنتاج درون‌دستگاهی محدودیت‌های زیر را دارد:

  • کاربر نهایی برنامه شما باید از دستگاهی با «هوش مصنوعی Apple» فعال استفاده کند.

  • برنامه شما فقط زمانی می‌تواند استنباط درون‌دستگاهی را اجرا کند که برنامه در پیش‌زمینه باشد.


بازخورد دادن درباره تجربه‌تان با Firebase AI Logic