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

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

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

توجه داشته باشید که استنتاج درون‌دستگاهی ازطریق Firebase AI Logic برای برنامه‌های وب که از Firebase AI Logic SDK نسخه ۱۲.۵.۰ یا بالاتر استفاده می‌کنند و در Chrome در رایانه (نسخه ۱۳۹ یا بالاتر) اجرا می‌شوند پشتیبانی می‌شود.

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

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

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

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

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

  • مزایای استفاده از رویکرد ترکیبی:

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

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

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

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

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

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

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

  • استنتاج درون‌ابری از ارائه‌دهنده Gemini API انتخابی شما (Gemini Developer API یا Agent Platform Gemini API (formerly Vertex AI)) استفاده می‌کند.

  • استنتاج درون‌دستگاهی از Prompt API از Chrome استفاده می‌کند.

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

برای استنتاج درون‌دستگاهی (که از Prompt API از Chrome استفاده می‌کند)، کاربر نهایی برنامه شما باید Chrome را در رایانه (نسخه ۱۳۹ یا بالاتر) اجرا کند. در اسناد Chrome بیشتر بدانید.

شروع به کار در localhost

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

در اسناد Chrome می‌توانید درباره استفاده از میاناهای برنامه‌سازی کاربردی در localhost بیشتر بدانید.

مرحله ۱: راه‌اندازی Chrome و Prompt API برای استنتاج درون‌دستگاهی

  1. مطمئن شوید از نسخه جدید Chrome استفاده می‌کنید. در chrome://settings/help به‌روز کنید.
    استنتاج درون‌دستگاهی از Chrome نسخه ۱۳۹ و بالاتر دردسترس است.

  2. با تنظیم پرچم زیر روی فعال‌شده، مدل چندوجهی درون‌دستگاهی را فعال کنید:

    • chrome://flags/#prompt-api-for-gemini-nano-multimodal-input

  3. ‫Chrome را بازراه‌اندازی کنید.

  4. (اختیاری) مدل درون‌دستگاهی را قبل‌از اولین درخواست بارگیری کنید.

    ‫Prompt API در Chrome تعبیه شده است، اما مدل درون‌دستگاهی به‌طور پیش‌فرض دردسترس نیست. اگر قبل‌از اولین درخواستتان برای استنتاج درون‌دستگاهی هنوز مدل را بارگیری نکرده باشید، درخواست به‌طور خودکار بارگیری مدل را در پس‌زمینه شروع می‌کند.

مرحله ۲: راه‌اندازی پروژه 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. برای افزودن کیت‌های توسعه نرم‌افزار لازم به برنامه‌تان، به مرحله بعدی در این راهنما بروید.

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

کتابخانه Firebase دسترسی به میاناهای برنامه‌سازی کاربردی را برای تعامل با مدل‌های زایا فراهم می‌کند. این کتابخانه به‌عنوان بخشی از کیت توسعه نرم‌افزار جاوا اسکریپت در Firebase برای وب گنجانده شده است.

  1. نصب کردن کیت توسعه نرم‌افزار Firebase JS برای وب بااستفاده از npm:

    npm install firebase

  2. مقداردهی اولیه Firebase در برنامه شما:

    import { initializeApp } from "firebase/app";
import { initializeAppCheck } from "firebase/app-check";

// TODO(developer) Replace the following with your app's Firebase configuration
// See: https://firebase.google.com/docs/web/learn-more#config-object
const firebaseConfig = {
  // ...
};

// Initialize FirebaseApp
const firebaseApp = initializeApp(firebaseConfig);

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

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

در اینجا نحوه استفاده از ارائه‌دهنده اشکال‌زدایی هنگام اجرای برنامه از localhost به‌صورت تعاملی (برای مثال، درطول توسعه محلی) آورده شده است:

  1. در ساخت اشکال‌زدایی، حالت اشکال‌زدایی را با تنظیم self.FIREBASE_APPCHECK_DEBUG_TOKEN روی true قبل‌از مقداردهی اولیه App Check فعال کنید. برای مثال:

    self.FIREBASE_APPCHECK_DEBUG_TOKEN = true;
initializeAppCheck(firebaseApp, { /* App Check options */ });

  2. به‌صورت محلی از برنامه وب خود بازدید کنید و ابزارهای توسعه‌دهنده مرورگر را باز کنید. در کنسول اشکال‌زدایی، یک توکن اشکال‌زدایی خواهید دید:

    AppCheck debug token: "123a4567-b89c-12d3-e456-789012345678".
You will need to safelist it in the Firebase console for it to work.

  3. کد اشکال‌زدایی‌تان را با App Check ثبت کنید:

    1. در کنسول Firebase، به برگه امنیت > بررسی برنامه > برنامه‌ها بروید.

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

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

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

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

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

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

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

  2. نمونه GenerativeModel ایجاد کنید. حتماً mode را روی یکی از این موارد تنظیم کنید:

    • PREFER_ON_DEVICE: اگر مدل درون‌دستگاهی دردسترس است، از آن استفاده کنید؛ درغیراین‌صورت، به مدل میزبانی‌شده در فضای ابری برگردید.

    • ONLY_ON_DEVICE: اگر مدل درون‌دستگاهی دردسترس است، از آن استفاده کنید؛ درغیراین‌صورت، یک استثنا ایجاد کنید.

    • PREFER_IN_CLOUD: اگر مدل میزبانی‌شده در فضای ابری دردسترس است، از آن استفاده کنید؛ درغیراین‌صورت، به مدل درون‌دستگاهی برگردید.

    • ONLY_IN_CLOUD: اگر مدل میزبانی‌شده در فضای ابری دردسترس است، از آن استفاده کنید؛ درغیراین‌صورت، یک استثنا ایجاد کنید.

import { initializeApp } from "firebase/app";
import { getAI, getGenerativeModel, GoogleAIBackend, InferenceMode } from "firebase/ai";

// TODO(developer) Replace the following with your app's Firebase configuration
// See: https://firebase.google.com/docs/web/learn-more#config-object
const firebaseConfig = {
  // ...
};

// Initialize FirebaseApp
const firebaseApp = initializeApp(firebaseConfig);

// Initialize the Gemini Developer API backend service
const ai = getAI(firebaseApp, { backend: new GoogleAIBackend() });

// Create a `GenerativeModel` instance
// Set the mode (for example, use the on-device model if it's available)
const model = getGenerativeModel(ai, { mode: InferenceMode.PREFER_ON_DEVICE });

مرحله ۶: مقداردهی اولیه مدل درون‌دستگاهی

باید initializeDeviceModel() را بعداز یا درحین تعامل کاربر نهایی با صفحه (مثل کلیک کردن روی دکمه) و قبل‌از ارسال درخواست پیام‌واره به مدل فراخوانی کنید. در اسناد Chrome، درباره الزامات فعال‌سازی کاربر بیشتر بدانید.

import { initializeApp } from "firebase/app";
import { getAI, getGenerativeModel, GoogleAIBackend, InferenceMode } from "firebase/ai";

// TODO(developer) Replace the following with your app's Firebase configuration
// See: https://firebase.google.com/docs/web/learn-more#config-object
const firebaseConfig = {
  // ...
};

// Initialize FirebaseApp
const firebaseApp = initializeApp(firebaseConfig);

// Initialize the Gemini Developer API backend service
const ai = getAI(firebaseApp, { backend: new GoogleAIBackend() });

// Create a `GenerativeModel` instance
// Set the mode (for example, use the on-device model if it's available)
const model = getGenerativeModel(ai, { mode: InferenceMode.PREFER_ON_DEVICE });

// `initializeDeviceModel` must be called:
// (1) after or on an end-user page interaction such as a button click
// and
// (2) before any queries to the model (such as `generateContent()`)
// You may want to `await` this promise if using `ONLY_ON_DEVICE` (see note below).
model.initializeDeviceModel((val) =>
  // Example: "Download progress: 72.62%""
  console.log(`Download progress: ${Math.round(val*10000) / 100}%`)
);

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

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

اگر می‌خواهید برونداد ساختاریافته (مانند JSON یا شمارشی) تولید کنید، از یکی از نمونه‌های «تولید نوشتار» زیر استفاده کنید و علاوه‌براین مدل را پیکربندی کنید تا براساس طرح‌واره ارائه‌شده پاسخ دهد.

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

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

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

// Imports + initialization of FirebaseApp and backend service + creation of model instance

// Wrap in an async function so you can use await
async function run() {
  // Provide a prompt that contains text
  const prompt = "Write a story about a magic backpack."

  // To generate text output, call `generateContent` with the text input
  const result = await model.generateContent(prompt);

  const response = result.response;
  const text = response.text();
  console.log(text);
}

run();

توجه داشته باشید که Firebase AI Logic از جاری‌سازی پاسخ‌های نوشتاری بااستفاده از generateContentStream (به‌جای generateContent) نیز پشتیبانی می‌کند.

تولید نوشتار از ورودی نوشتار و تصویر (چندحالتی)

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

می‌توانید از generateContent() برای تولید نوشتار از پیام‌واره‌ای که حاوی فایل‌های نوشتاری و تصویری است استفاده کنید—با ارائه mimeType هر فایل ورودی و خود فایل.

انواع تصویر ورودی پشتیبانی‌شده برای استنتاج درون‌دستگاهی PNG و JPEG هستند.

// Imports + initialization of FirebaseApp and backend service + creation of model instance

// Converts a File object to a Part object.
async function fileToGenerativePart(file) {
  const base64EncodedDataPromise = new Promise((resolve) => {
    const reader = new FileReader();
    reader.onloadend = () => resolve(reader.result.split(',')[1]);
    reader.readAsDataURL(file);
  });
  return {
    type: "inlineData",
    inlineData: { data: await base64EncodedDataPromise, mimeType: file.type },
  };
}

async function run() {
  // Provide a text prompt to include with the image
  const prompt = "Write a poem about this picture:";

  const fileInputEl = document.querySelector("input[type=file]");
  const imagePart = await fileToGenerativePart(fileInputEl.files[0]);

  // To generate text output, call `generateContent` with the text and image
  const result = await model.generateContent([prompt, imagePart]);

  const response = result.response;
  const text = response.text();
  console.log(text);
}

run();

توجه داشته باشید که Firebase AI Logic از جاری‌سازی پاسخ‌های نوشتاری بااستفاده از generateContentStream (به‌جای generateContent) نیز پشتیبانی می‌کند.

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

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

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

همه قابلیت‌های Web SDK یا مدل‌های میزبانی‌شده در فضای ابری برای استنتاج ترکیبی یا درون‌دستگاهی دردسترس نیستند.

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

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

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

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

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

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

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

  • درحال تولید تصاویر بااستفاده از مدل‌های Gemini Nano Banana

    • می‌تواند به مدل میزبانی‌شده در فضای ابری برگردد؛ بااین‌حال، حالت ONLY_ON_DEVICE خطا ایجاد خواهد کرد.

  • تولید نوشتار از انواع ورودی فایل تصویری به‌جز JPEG و PNG

    • می‌تواند به مدل میزبانی‌شده در فضای ابری برگردد؛ بااین‌حال، حالت ONLY_ON_DEVICE خطا ایجاد خواهد کرد.

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

    • می‌تواند به مدل میزبانی‌شده در فضای ابری برگردد؛ بااین‌حال، حالت ONLY_ON_DEVICE خطا ایجاد خواهد کرد.

  • ارائه فایل‌ها بااستفاده از نشانی‌های وب در درخواست‌های چندحالته. باید فایل‌ها را به‌صورت داده درون‌خطی به مدل‌های درون‌دستگاهی ارائه دهید.

  • گپ چندنوبتی

    • می‌تواند به مدل میزبانی‌شده در فضای ابری برگردد؛ بااین‌حال، حالت ONLY_ON_DEVICE خطا ایجاد خواهد کرد.

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

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

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

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

  • کاربر نهایی برنامه شما باید Chrome را در رایانه (نسخه ۱۳۹ یا بالاتر) با پرچم‌های لازم فعال‌شده اجرا کند.

  • مدل درون‌دستگاهی برای بارگیری اولیه مدل به فضای ذخیره‌سازی کافی در دستگاه کاربر نیاز دارد.


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