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

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

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

توجه داشته باشید که استنباط درون‌دستگاهی برای برنامه‌های وب که در Chrome در رایانه اجرا می‌شوند پشتیبانی می‌شود.

رفتن به نمونه‌های کد

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

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

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

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

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

    • بدون توجه به دردسترس بودن مدل درون‌دستگاهی یا اتصال اینترنت، به ۱۰۰٪ مخاطبانتان دسترسی پیدا کنید

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

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

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

قبل از شروع

به موارد زیر توجه کنید:

  • استنباط بااستفاده از مدل درون‌دستگاهی از API پیام‌واره از Chrome استفاده می‌کند؛ درحالی‌که استنباط بااستفاده از مدل میزبانی‌شده در فضای ابری از Gemini API ارائه‌دهنده انتخابی شما (یا Gemini Developer API یا Agent Platform Gemini API (formerly Vertex AI)) استفاده می‌کند.

  • این صفحه نحوه شروع توسعه بااستفاده از localhost را شرح می‌دهد (در اسناد Chrome درباره استفاده از API در localhost بیشتر بدانید).

    پس‌از تکمیل این راه‌اندازی استاندارد، گزینه‌ها و قابلیت‌های پیکربندی اضافی (مثل برونداد ساختاریافته) را بررسی کنید.

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

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

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

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

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

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

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

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

    «میانای برنامه‌سازی کاربردی پیام‌واره» در 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 JavaScript ویژه وب» ارائه می‌شود.

  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. در ساخت اشکال‌زدایی، قبل‌از مقداردهی اولیه کردن App Check، با تنظیم self.FIREBASE_APPCHECK_DEBUG_TOKEN روی true، حالت اشکال‌زدایی را فعال کنید. برای مثال:

    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 {
    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) نیز پشتیبانی می‌کند.

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

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

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

همه قابلیت‌های «کیت توسعه نرم‌افزار وب» برای استنباط درون‌دستگاهی دردسترس نیست. ویژگی‌های زیر هنوز برای استنباط درون‌دستگاهی پشتیبانی نمی‌شوند (اما معمولاً برای استنباط ابری دردسترس هستند).

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

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

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

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

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

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

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

  • گپ چندنوبتی

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

  • جاری‌سازی دوطرفه با Gemini Live API

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

  • شمارش داده‌واحدها

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

  • پایش هوشواره‌ای در کنسول Firebase برای استنباط درون‌دستگاهی.

    • توجه داشته باشید که هرگونه استنباط بااستفاده از مدل‌های میزبانی‌شده در فضای ابری می‌تواند مانند سایر استنباط‌ها بااستفاده از کیت توسعه نرم‌افزار مشتری Firebase AI Logic برای وب نظارت شود.


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