Создавайте гибридные веб-приложения с моделями, размещенными на устройстве и в облаке

Создавайте веб-приложения и функции на основе ИИ с гибридным выводом, используя Firebase AI Logic. Гибридный инференс позволяет выполнять инференс с использованием моделей на устройстве, когда они доступны, и плавно возвращаться к моделям, размещенным в облаке, в противном случае (и наоборот).

На этой странице описано, как начать работу с клиентским SDK. После завершения стандартной настройки ознакомьтесь с дополнительными параметрами и возможностями, например структурированным выводом.

Обратите внимание, что вывод на устройстве поддерживается для веб-приложений, работающих в Chrome на компьютере.

Перейти к примерам кода

Рекомендуемые варианты использования и поддерживаемые возможности

Рекомендуемые варианты использования:

  • Использование локальной модели для инференса имеет следующие преимущества:

    • Повышенная конфиденциальность
    • Локальный контекст
    • Бесплатный вывод
    • Офлайн-функции

  • Использование гибридных функций позволяет:

    • Охватите 100% аудитории независимо от наличия модели на устройстве или подключения к интернету.

Поддерживаемые возможности и функции для инференса на устройстве:

Вывод на устройстве поддерживает только одноэтапную генерацию текста (не чат) с потоковым или непотоковым выводом. Она поддерживает следующие возможности генерации текста:

Вы также можете генерировать структурированные выходные данные, включая JSON и перечисления.

Подготовка

Вот на что стоит обратить внимание:

  • Для инференса с помощью модели на устройстве используется Prompt API из Chrome, а для инференса с помощью модели в облаке – выбранный вами поставщик Gemini API (Gemini Developer API или Agent Platform Gemini API (formerly Vertex AI)).

  • На этой странице рассказывается, как начать разработку с использованием localhost (подробнее об использовании API на localhost читайте в документации Chrome).

    После завершения стандартной настройки ознакомьтесь с дополнительными возможностями и параметрами конфигурации, например структурированным выводом.

Начало работы с localhost

В этом разделе описаны общие действия, которые нужно выполнить, чтобы отправить любой поддерживаемый запрос.

Шаг 1. Настройте Chrome и Prompt API для локального инференса

  1. Убедитесь, что вы используете последнюю версию Chrome. Обновите его на странице chrome://settings/help.
    Вывод на устройстве доступен в Chrome 139 и более поздних версиях.

  2. Включите мультимодальную модель на устройстве, установив для следующего параметра значение Enabled (Включено):

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

  3. Перезапустите Chrome.

  4. Необязательно. Скачайте модель на устройство до первого запроса.

    Prompt API встроен в Chrome, но модель на устройстве по умолчанию недоступна. Если вы не скачали модель до первого запроса на инференс на устройстве, запрос автоматически запустит скачивание модели в фоновом режиме.

Шаг 2. Настройте проект Firebase и подключите к нему приложение

  1. Войдите в консоль Firebase и выберите проект Firebase.

  2. В консоли Firebase выберите AI Services (Сервисы ИИ) > AI Logic (Логика ИИ).

  3. Нажмите Начать, чтобы запустить пошаговый процесс настройки необходимых API и ресурсов для проекта.

  4. Если появится запрос, следуйте инструкциям на экране, чтобы зарегистрировать приложение и добавить в него конфигурацию Firebase.

  5. Когда вам будет предложено выбрать поставщика Gemini API, рекомендуем выбрать Gemini Developer API. Это позволит вам быстро начать работу без дополнительных затрат.

    Вы можете в любой момент настроить Agent Platform Gemini API (formerly Vertex AI) (и платежные данные, которые для него требуются).

  6. Продолжите настройку необходимых API и связанных сервисов для Firebase AI Logic.

    На этом этапе рабочего процесса автоматически применяется Firebase App Check для AI Logic. Это критически важный сервис, который помогает защитить Gemini API при прямом доступе из вашего приложения. В рамках начала работы (см. шаги далее в этом руководстве) вам нужно будет настроить отладочный поставщик App Check для локальной разработки, когда применяется App Check.

  7. Перейдите к следующему шагу этого руководства, чтобы добавить в приложение необходимые SDK.

Шаг 3. Добавьте SDK

Библиотека Firebase предоставляет доступ к API для взаимодействия с генеративными моделями. Библиотека входит в состав Firebase JavaScript SDK для веб-приложений.

  1. Установите Firebase JS SDK для Web с помощью 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);

Шаг 4. Настройте отладочный поставщик 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 перейдите в раздел Security (Безопасность) > App Check (Проверка приложений) > Apps (Приложения).

    2. Найдите свое приложение, нажмите на значок дополнительного меню () и выберите Управление токенами отладки.

    3. Зарегистрируйте токен отладки, следуя инструкциям на экране.

Подробную информацию об отладочном поставщике, в том числе о том, как получить новый токен отладки, можно найти в официальной документации App Check.

Шаг 5. Инициализируйте сервис и создайте экземпляр модели

Нажмите на название своего поставщика 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 });

Шаг 6. Инициализируйте модель на устройстве

Вызывать initializeDeviceModel() нужно после или во время взаимодействия конечного пользователя со страницей (например, нажатия кнопки) и до отправки запроса модели. Подробнее о требовании активации пользователем…

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}%`)
);

Шаг 7. Отправьте запрос модели

В этом разделе показано, как отправлять различные типы входных данных для генерации различных типов выходных данных, в том числе:

Если вы хотите сгенерировать структурированные выходные данные (например, 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 доступны для локального вывода. Следующие функции пока не поддерживаются для вывода на устройстве (но обычно доступны для вывода в облаке).

  • Генерировать текст из графических файлов других форматов, кроме JPEG и PNG.

    • Можно использовать облачную модель, но в режиме ONLY_ON_DEVICE будет возникать ошибка.

  • Генерировать текст на основе аудио, видео и документов (например, PDF).

    • Можно использовать облачную модель, но в режиме ONLY_ON_DEVICE возникнет ошибка.

  • Генерирование изображений с помощью моделей Gemini Nano Banana

    • Можно использовать облачную модель, но в режиме ONLY_ON_DEVICE возникнет ошибка.

  • Предоставление файлов с использованием URL-адресов в мультимодальных запросах. Файлы необходимо передавать в модели на устройстве как встроенные данные.

  • Многоэтапный чат

    • Можно использовать облачную модель, но в режиме ONLY_ON_DEVICE возникнет ошибка.

  • Двунаправленная потоковая передача с помощью Gemini Live API

  • Предоставление модели инструментов, которые помогают ей генерировать ответы. К таким инструментам относятся вызов функций, выполнение кода, URL-контекст, обоснование с помощью Google Search и обоснование с помощью Google Maps.

  • Подсчет токенов

    • Всегда возвращает ошибку. Количество токенов будет отличаться для облачных и локальных моделей, поэтому интуитивно понятного резервного варианта нет.

  • ИИ-мониторинг в консоли Firebase для инференса на устройстве.

    • Обратите внимание, что любой инференс с использованием моделей, размещенных в облаке, можно отслеживать так же, как и любой другой инференс с использованием клиентского SDK Firebase AI Logic для веб-приложений.


Оставить отзыв о работе с Firebase AI Logic