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

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

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

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

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

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

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

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

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

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

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

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

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

قبل از اینکه شروع کنی

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

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

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

• بعد از اینکه ویژگی مورد نظر خود را پیاده‌سازی کردید، می‌توانید به کاربران نهایی این امکان را بدهید که آن را در برنامه‌ی اصلی خود امتحان کنند .

شروع کار روی لوکال هاست

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

مرحله ۱ : کروم و 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 » استفاده کند.

   توصیه می‌کنیم برای شروع از رابط برنامه‌نویسی نرم‌افزار Gemini Developer API استفاده کنید. در هر مرحله، می‌توانید رابط برنامه‌نویسی نرم‌افزار Vertex AI Gemini (و الزامات آن برای صدور صورتحساب) را تنظیم کنید .

   برای Gemini Developer API ، کنسول APIهای مورد نیاز را فعال کرده و یک کلید API Gemini در پروژه شما ایجاد می‌کند.
   این کلید API مربوط به Gemini را به کدبیس برنامه خود اضافه نکنید . اطلاعات بیشتر.

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

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

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

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

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

   1. فراخوانی getGenerativeModel پس از یا در حین تعامل کاربر نهایی (مانند کلیک روی دکمه). این یک پیش‌نیاز برای inferenceMode است.

   2. 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
// Call `getGenerativeModel` after or on an end-user interaction
// Set the mode (for example, use the on-device model if it's available)
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 استفاده می‌کنند، اما این تنها یکی از چهار حالت استنتاج موجود است.

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

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

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

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

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

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

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

  const model = getGenerativeModel(ai, { mode: InferenceMode.ONLY_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.5-flash-lite (با شروع از JS SDK نسخه ۱۲.۸.۰).

این مدل، مدل پشتیبانِ مبتنی بر ابر است وقتی که از حالت 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
    },

// ...
});

// ...