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

Создавайте веб-приложения и функции на основе ИИ с гибридным выводом, используя 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 выберите Сервисы ИИ > Логика ИИ.

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

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

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

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

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

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

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

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

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

  1. Установите Firebase JS SDK для сайта с помощью 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 для локальной разработки

С начала июля 2026 года в рамках пошаговой настройки 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 перейдите на вкладку Приложения в разделе Безопасность > App Check.

    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() после или во время взаимодействия пользователя со страницей (например, нажатия кнопки) и до того, как отправите запрос подсказки модели. Подробнее о требованиях к активации пользователя рассказывается в документации 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}%`)
);

Шаг 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 {
    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

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

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

  • Многоходовые чаты

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

  • Двусторонняя трансляция с помощью Gemini Live API

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

  • Как подсчитать токены

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

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

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


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