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

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

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

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

پرش به مشاهده نمونه‌های کد

موارد استفاده و قابلیت‌های پشتیبانی‌شده

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

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

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

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

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

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

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

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

بخش‌های زیر میاناهای برنامه‌سازی کاربردی پشتیبانی‌شده و همچنین دستگاه‌های پشتیبانی‌شده (و مدل‌های درون‌دستگاهی آن‌ها) را شرح می‌دهند.

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

دستگاه‌های Apple پشتیبانی‌شده و مدل‌های درون‌دستگاهی آن‌ها

برای استنتاج درون‌دستگاهی (که از چارچوب مدل‌های پایه Apple استفاده می‌کند)، می‌توانید فهرستی از دستگاه‌هایی را که Apple Intelligence در آن‌ها فعال است در اسناد 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 استفاده کنید. پشتیبانی ترکیبی فقط هنگام استفاده از SPM دردسترس است.

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

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

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

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

    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 SDK برای استنتاج ترکیبی یا درون‌دستگاهی دردسترس نیستند.

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

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

  • Gemini Live API: جاری‌سازی هم‌زمان دوطرفه پشتیبانی نمی‌شود.

  • الگوهای پیام‌واره سرور: الگوهای پیام‌واره سرور مدیریت‌شده پشتیبانی نمی‌شوند.

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

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

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

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

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

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

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

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

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

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

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

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


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