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

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

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

پرش به مثال‌های کد

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

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

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

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

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

  • صرف نظر از مدل دستگاه یا اتصال به اینترنت، به ۱۰۰٪ مخاطبان خود دسترسی داشته باشید

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

• تولید محتوای تک نوبتی، پخش جریانی و غیرپخشی
• تولید متن از ورودی فقط متنی
• تولید متن از ورودی متن و تصویر ، به ویژه انواع تصاویر ورودی JPEG و PNG
• تولید خروجی ساختاریافته ، شامل JSON و enumها

شروع کنید

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

استنتاج با استفاده از یک مدل روی دستگاه از Prompt API کروم استفاده می‌کند؛ در حالی که استنتاج با استفاده از یک مدل میزبانی ابری از ارائه‌دهنده API Gemini انتخابی شما (یا Gemini Developer API یا Vertex AI Gemini API ) استفاده می‌کند.

همانطور که در این بخش توضیح داده شده است، توسعه را با استفاده از localhost شروع کنید (همچنین می‌توانید در مستندات Chrome درباره استفاده از APIها در localhost بیشتر بدانید). سپس، پس از پیاده‌سازی ویژگی خود، می‌توانید به صورت اختیاری به کاربران نهایی اجازه دهید تا ویژگی شما را امتحان کنند .

مرحله ۱ : کروم و Prompt API را برای استنتاج روی دستگاه تنظیم کنید

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

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

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

3. کروم را مجدداً راه‌اندازی کنید.

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

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

   دستورالعمل‌های دانلود مدل روی دستگاه را مشاهده کنید

   1. ابزارهای توسعه‌دهنده > کنسول را باز کنید.

   2. دستور زیر را اجرا کنید:

      await LanguageModel.availability();
      

   3. مطمئن شوید که خروجی available ، downloading یا downloadable است.

   4. اگر خروجی downloadable است، دانلود مدل را با اجرای دستور زیر آغاز کنید:

      await LanguageModel.create();
      

   5. می‌توانید از تابع فراخوانی monitor زیر برای گوش دادن به پیشرفت دانلود استفاده کنید و قبل از ارسال درخواست، از available بودن مدل مطمئن شوید:

      const session = await LanguageModel.create({
        monitor(m) {
          m.addEventListener("downloadprogress", (e) => {
            console.log(`Downloaded ${e.loaded * 100}%`);
          });
        },
      });
      

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

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

   آیا از قبل پروژه Firebase ندارید؟

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

   • گزینه ۱ : با وارد کردن نام پروژه جدید در اولین مرحله از گردش کار، یک پروژه Firebase کاملاً جدید (و پروژه Google Cloud زیربنایی آن به طور خودکار) ایجاد کنید.

   • گزینه ۲ : با کلیک روی «افزودن فایربیس به پروژه گوگل کلود» (در پایین صفحه)، «افزودن فایربیس » را به یک پروژه Google Cloud موجود اضافه کنید. در اولین مرحله از گردش کار، نام پروژه موجود را وارد کنید و سپس پروژه را از لیست نمایش داده شده انتخاب کنید.

   مراحل باقی‌مانده از گردش کار روی صفحه را برای ایجاد یک پروژه Firebase تکمیل کنید. توجه داشته باشید که در صورت درخواست، نیازی به تنظیم Google Analytics برای استفاده از Firebase AI Logic SDKs ندارید .

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

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

4. ارائه‌دهنده‌ی « Gemini API » را که می‌خواهید با Firebase AI Logic SDKs استفاده کنید، انتخاب کنید. Gemini Developer API برای کاربران تازه‌کار توصیه می‌شود. در صورت تمایل، همیشه می‌توانید بعداً صورتحساب را اضافه کنید یا Vertex AI Gemini API را راه‌اندازی کنید.

   • رابط برنامه‌نویسی کاربردی توسعه‌دهندگان Gemini - پرداخت هزینه اختیاری (در طرح قیمت‌گذاری رایگان Spark موجود است و در صورت تمایل می‌توانید بعداً آن را ارتقا دهید)
     کنسول، APIهای مورد نیاز را فعال کرده و یک کلید API مربوط به Gemini را در پروژه شما ایجاد می‌کند.
     این کلید API مربوط به Gemini را به کدبیس برنامه خود اضافه نکنید . اطلاعات بیشتر.

   • رابط برنامه‌نویسی کاربردی Vertex AI Gemini - پرداخت صورتحساب الزامی است (نیازمند طرح قیمت‌گذاری پرداخت در محل Blaze است)
     این کنسول به شما کمک می‌کند تا صورتحساب را تنظیم کنید و APIهای مورد نیاز را در پروژه خود فعال کنید.

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

6. برای افزودن SDK به برنامه خود، به مرحله بعدی این راهنما بروید.

مرحله ۳ : اضافه کردن SDK

کتابخانه Firebase دسترسی به APIها را برای تعامل با مدل‌های مولد فراهم می‌کند. این کتابخانه به عنوان بخشی از Firebase JavaScript SDK for Web گنجانده شده است.

1. نصب Firebase JS SDK برای وب با استفاده از npm:

   npm install firebase
   

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

   import { initializeApp } from "firebase/app";
   
   // 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);
   

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

قبل از ارسال اعلان به مدل Gemini ، سرویس را برای ارائه‌دهنده API انتخابی خود مقداردهی اولیه کنید و یک نمونه GenerativeModel ایجاد کنید.

mode را روی یکی از موارد زیر تنظیم کنید:

• PREFER_ON_DEVICE : SDK را طوری پیکربندی می‌کند که در صورت وجود، از مدل روی دستگاه استفاده کند یا به مدل میزبانی ابری بازگردد.

• ONLY_ON_DEVICE : SDK را طوری پیکربندی می‌کند که از مدل روی دستگاه استفاده کند یا یک استثنا ایجاد کند.

• PREFER_IN_CLOUD : SDK را طوری پیکربندی می‌کند که در صورت وجود، از مدل میزبانی ابری استفاده کند، یا به مدل روی دستگاه بازگردد.

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

وقتی از PREFER_ON_DEVICE ، PREFER_IN_CLOUD یا ONLY_IN_CLOUD استفاده می‌کنید ، مدل پیش‌فرض میزبانی ابری به صورت زیر است: gemini-2.0-flash-lite ، اما می‌توانید پیش‌فرض را لغو کنید .

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 to use on-device model when possible
const model = getGenerativeModel(ai, { mode: InferenceMode.PREFER_ON_DEVICE });

// 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();

// 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();

1. برای نسخه آزمایشی Prompt API Chrome Origin ثبت نام کنید. به شما یک توکن داده خواهد شد.

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

   • توکن را به عنوان یک متا تگ در تگ <head> قرار دهید: <meta http-equiv="origin-trial" content=" TOKEN ">

   • توکن را به عنوان یک هدر HTTP ارائه دهید: Origin-Trial: TOKEN

   • توکن را به صورت برنامه‌نویسی شده ارائه دهید.

از حالت‌های استنتاج جایگزین استفاده کنید

مثال‌های بالا از حالت PREFER_ON_DEVICE برای پیکربندی SDK جهت استفاده از یک مدل روی دستگاه در صورت وجود، یا بازگشت به یک مدل میزبانی ابری استفاده کردند. SDK سه حالت استنتاج جایگزین ارائه می‌دهد: ONLY_ON_DEVICE ، ONLY_IN_CLOUD و PREFER_IN_CLOUD .

• از حالت ONLY_ON_DEVICE استفاده کنید تا SDK فقط بتواند از یک مدل روی دستگاه استفاده کند. در این پیکربندی، اگر مدل روی دستگاه در دسترس نباشد، API خطایی ایجاد می‌کند.

  const model = getGenerativeModel(ai, { mode: InferenceMode.ONLY_ON_DEVICE });
  

• از حالت ONLY_IN_CLOUD استفاده کنید تا SDK فقط بتواند از یک مدل میزبانی شده توسط ابر استفاده کند.

  const model = getGenerativeModel(ai, { mode: InferenceMode.ONLY_IN_CLOUD });
  

• از حالت PREFER_IN_CLOUD استفاده کنید تا SDK تلاش کند از مدل ابری استفاده کند، اما اگر مدل ابری در دسترس نباشد (مثلاً دستگاه آفلاین باشد) به مدل روی دستگاه بازگردد.

  const model = getGenerativeModel(ai, { mode: InferenceMode.PREFER_IN_CLOUD });
  

تعیین اینکه آیا از استنتاج درون دستگاهی یا درون ابری استفاده شده است

اگر از حالت‌های استنتاج PREFER_ON_DEVICE یا PREFER_IN_CLOUD استفاده می‌کنید، دانستن اینکه کدام حالت برای درخواست‌های داده شده استفاده شده است، می‌تواند مفید باشد. این اطلاعات توسط ویژگی inferenceSource هر پاسخ ارائه می‌شود (از JS SDK v12.5.0 به بعد در دسترس است).

وقتی به این ویژگی دسترسی پیدا می‌کنید، مقدار برگشتی یا ON_DEVICE یا IN_CLOUD خواهد بود.

// ...

console.log('You used: ' + result.response.inferenceSource);

console.log(result.response.text());

مدل پیش‌فرض میزبانی ابری به صورت زیر است: gemini-2.0-flash-lite .

این مدل، مدل پشتیبانِ مبتنی بر ابر است وقتی که از حالت PREFER_ON_DEVICE استفاده می‌کنید. همچنین مدل پیش‌فرض است وقتی که از حالت ONLY_IN_CLOUD یا حالت PREFER_IN_CLOUD استفاده می‌کنید.

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

const model = getGenerativeModel(ai, {
  mode: InferenceMode.INFERENCE_MODE,
  inCloudParams: {
    model: "GEMINI_MODEL_NAME"
  }
});

const model = getGenerativeModel(ai, {
  mode: InferenceMode.INFERENCE_MODE,
  inCloudParams: {
    model: "GEMINI_MODEL_NAME"
    temperature: 0.8,
    topK: 10
  }
});

const model = getGenerativeModel(ai, {
  mode: InferenceMode.INFERENCE_MODE,
  onDeviceParams: {
    createOptions: {
      temperature: 0.8,
      topK: 8
    }
  }
});

import {
  getAI,
  getGenerativeModel,
  Schema
} from "firebase/ai";

const jsonSchema = Schema.object({
 properties: {
    characters: Schema.array({
      items: Schema.object({
        properties: {
          name: Schema.string(),
          accessory: Schema.string(),
          age: Schema.number(),
          species: Schema.string(),
        },
        optionalProperties: ["accessory"],
      }),
    }),
  }
});

const model = getGenerativeModel(ai, {
  mode: InferenceMode.INFERENCE_MODE,
  inCloudParams: {
    model: "gemini-2.5-flash"
    generationConfig: {
      responseMimeType: "application/json",
      responseSchema: jsonSchema
    },
  }
  onDeviceParams: {
    promptOptions: {
      responseConstraint: jsonSchema
    }
  }
});

// ...

const enumSchema = Schema.enumString({
  enum: ["drama", "comedy", "documentary"],
});

const model = getGenerativeModel(ai, {

// ...

    generationConfig: {
      responseMimeType: "text/x.enum",
      responseSchema: enumSchema
    },

// ...
});

// ...