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


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

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

Обратите внимание, что инференс на устройстве с помощью Firebase AI Logic поддерживается для приложений Android, использующих Firebase AI Logic SDK версии 17.10.0 или более поздней (BoM версии 34.10.0 или более поздней) и работающих на определенных устройствах. Его использование регулируется Условиями использования ML Kit, а также Условиями использования генеративного ИИ в ML Kit.

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

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

  • Локальная модель для логического вывода позволяет:

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

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

    • Охватите больше пользователей, учитывая доступность модели на устройстве и подключение к интернету.

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

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

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

Подготовка

Обратите внимание на следующее:

Поддерживаемые устройства Android и их модели на устройстве

Список поддерживаемых устройств и их моделей для вывода на устройстве (с использованием Prompt API из ML Kit) можно найти в документации ML Kit.

Начать

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

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

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

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

  3. Нажмите Начать, чтобы запустить пошаговый процесс настройки необходимых 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.

Шаг 2. Добавьте все необходимые SDK.

Firebase AI Logic SDK для Android (firebase-ai) и Firebase AI Logic On-Device SDK (firebase-ai-ondevice) предоставляют доступ к API для взаимодействия с генеративными моделями.

В файле Gradle на уровне модуля (приложения) (например, <project>/<app-module>/build.gradle.kts) добавьте зависимости для библиотек Firebase AI Logic и App Check для Android:

Kotlin 

dependencies {
  // ... other androidx dependencies

  // Add the dependencies for the Firebase AI Logic and App Check libraries
  // Note that the on-device SDK is not yet included in the Firebase Android BoM
  implementation("com.google.firebase:firebase-ai:18.0.0")
  implementation("com.google.firebase:firebase-ai-ondevice:16.0.0-beta06")
  implementation("com.google.firebase:firebase-appcheck-debug:20.0.0")
}

Java

Для Java необходимо добавить две дополнительные библиотеки.

dependencies {
  // ... other androidx dependencies

  // Add the dependencies for the Firebase AI Logic and App Check libraries
  // Note that the on-device SDK is not yet included in the Firebase Android BoM
  implementation("com.google.firebase:firebase-ai:18.0.0")
  implementation("com.google.firebase:firebase-ai-ondevice:16.0.0-beta06")
  implementation("com.google.firebase:firebase-appcheck-debug:20.0.0")

  // Required for one-shot operations (to use `ListenableFuture` from Guava Android)
  implementation("com.google.guava:guava:31.0.1-android")

  // Required for streaming operations (to use `Publisher` from Reactive Streams)
  implementation("org.reactivestreams:reactive-streams:1.0.4")
}

Шаг 3. Настройте поставщика отладки App Check для локальной разработки

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

  1. В отладочной сборке настройте App Check так, чтобы он использовал фабрику поставщика отладочной версии:

    Kotlin

    Firebase.initialize(context = this)
Firebase.appCheck.installAppCheckProviderFactory(
    DebugAppCheckProviderFactory.getInstance(),
)

    Java

    FirebaseApp.initializeApp(/*context=*/ this);
FirebaseAppCheck firebaseAppCheck = FirebaseAppCheck.getInstance();
firebaseAppCheck.installAppCheckProviderFactory(
        DebugAppCheckProviderFactory.getInstance());

  2. Получите токен отладки:

    1. Запустите приложение в эмуляторе или на тестовом устройстве.

    2. Найдите в журналах токен отладки App Check. Пример:

      D DebugAppCheckProvider: Enter this debug secret into the allow list
in the Firebase Console for your project: 123a4567-b89c-12d3-e456-789012345678

    3. Скопируйте токен (например, 123a4567-b89c-12d3-e456-789012345678).

  3. Зарегистрируйте токен отладки в App Check:

    1. В консоли Firebase перейдите в раздел Security (Безопасность) > App Check (Проверка приложений) > Apps (Приложения).

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

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

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

Шаг 4. Проверьте, доступна ли модель на устройстве

С помощью FirebaseAIOnDevice проверьте, доступна ли модель на устройстве. Если нет, скачайте ее.

После скачивания AICore будет автоматически обновлять модель. Дополнительную информацию об AICore и управлении скачиванием модели на устройстве вы найдете в примечаниях после фрагмента кода.

Kotlin 

val status = FirebaseAIOnDevice.checkStatus()
when (status) {
  OnDeviceModelStatus.UNAVAILABLE -> {
    Log.w(TAG, "On-device model is unavailable")
  }

  OnDeviceModelStatus.DOWNLOADABLE -> {
    FirebaseAIOnDevice.download().collect { status ->
      when (status) {
        is DownloadStatus.DownloadStarted ->
          Log.w(TAG, "Starting download - ${status.bytesToDownload}")

        is DownloadStatus.DownloadInProgress ->
          Log.w(TAG, "Download in progress ${status.totalBytesDownloaded} bytes downloaded")

        is DownloadStatus.DownloadCompleted ->
          Log.w(TAG, "On-device model download complete")

        is DownloadStatus.DownloadFailed ->
          Log.e(TAG, "Download failed ${status}")
      }
    }
  }
  OnDeviceModelStatus.DOWNLOADING -> {
    Log.w(TAG, "On-device model is being downloaded")
  }

  OnDeviceModelStatus.AVAILABLE -> {
    Log.w(TAG, "On-device model is available")
  }
}

Java 

Checking for, downloading, and warming up the model is not yet available for Java.

However, all other APIs and interactions in this guide are available for Java.

Обратите внимание на следующее:

  • Время скачивания модели на устройство зависит от многих факторов, в том числе от вашей сети.

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

  • Если модель на устройстве недоступна при запросе на вывод на устройстве, SDK не будет автоматически запускать скачивание модели. SDK переключится на модель, размещенную в облаке, или вызовет исключение (подробнее о режимах работы).

  • AICore (системный сервис Android) управляет тем, какая модель и версия скачиваются, а также поддерживает модель в актуальном состоянии. Обратите внимание, что на устройстве может быть скачана только одна модель. Если другое приложение на устройстве ранее успешно скачало локальную модель, то при проверке будет возвращено, что модель доступна.

Оптимизация задержки

Чтобы оптимизировать первый вызов логического вывода, приложение может вызывать функцию onDeviceExtension?.warmUp() (в настоящее время доступна только для Kotlin). Это загрузит модель на устройстве в память и инициализирует компоненты среды выполнения.

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

Нажмите на поставщика Gemini API, чтобы посмотреть контент и код, относящиеся к нему.

Прежде чем отправлять запрос модели, настройте следующее:

  1. Инициализируйте сервис для выбранного поставщика API.

  2. Создайте экземпляр GenerativeModel и задайте для mode одно из следующих значений: Здесь приведены только общие сведения, а подробную информацию о поведении этих режимов можно найти в разделе Как задать режим вывода.

    • PREFER_ON_DEVICE: попытка использовать модель на устройстве; в противном случае переход на модель, размещенную в облаке.

    • ONLY_ON_DEVICE: попытаться использовать модель на устройстве, в противном случае выдать исключение.

    • PREFER_IN_CLOUD: попытка использовать облачную модель. Если это не удается, используется модель на устройстве.

    • ONLY_IN_CLOUD – попытаться использовать облачную модель, а в случае неудачи выдать исключение.

Kotlin 

// Using this SDK to access on-device inference is an Experimental release and requires opt-in
@OptIn(PublicPreviewAPI::class)

// ...

// Initialize the Gemini Developer API backend service
// Create a GenerativeModel instance with a model that supports your use case
// Set the inference mode (like PREFER_ON_DEVICE to use the on-device model if available)
val model = Firebase.ai(backend = GenerativeBackend.googleAI())
    .generativeModel(
        modelName = "CLOUD_MODEL_NAME",
        onDeviceConfig = OnDeviceConfig(mode = InferenceMode.PREFER_ON_DEVICE)
    )

Java 

// Initialize the Gemini Developer API backend service
// Create a GenerativeModel instance with a model that supports your use case
// Set the inference mode (like PREFER_ON_DEVICE to use the on-device model if available)
GenerativeModel ai = FirebaseAI.getInstance(GenerativeBackend.googleAI())
    .generativeModel(
        "CLOUD_MODEL_NAME",
        new OnDeviceConfig(InferenceMode.PREFER_ON_DEVICE)
    );

// Use the GenerativeModelFutures Java compatibility layer which offers
// support for ListenableFuture and Publisher APIs
GenerativeModelFutures model = GenerativeModelFutures.from(ai);

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

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

Как генерировать текст на основе текстового запроса

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

Вы можете использовать generateContent(), чтобы генерировать сгенерированный текст на основе запроса, содержащего текст.

Kotlin 

// Imports + initialization of Gemini API backend service + creation of model instance

// Provide a prompt that contains text
val prompt = "Write a story about a magic backpack."

// To generate text output, call generateContent with the text input
val response = model.generateContent(prompt)
print(response.text)

Java 

// Imports + initialization of Gemini API backend service + creation of model instance

// Provide a prompt that contains text
Content prompt = new Content.Builder()
    .addText("Write a story about a magic backpack.")
    .build();

// To generate text output, call generateContent with the text input
ListenableFuture<GenerateContentResponse> response = model.generateContent(prompt);
Futures.addCallback(response, new FutureCallback<GenerateContentResponse>() {
    @Override
    public void onSuccess(GenerateContentResponse result) {
        String resultText = result.getText();
        System.out.println(resultText);
    }

    @Override
    public void onFailure(Throwable t) {
        t.printStackTrace();
    }
}, executor);

Обратите внимание, что Firebase AI Logic также поддерживает потоковую передачу текстовых ответов с помощью generateContentStream (вместо generateContent).

Как генерировать текст на основе текста и изображения (мультимодальный ввод)

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

Вы можете использовать generateContent(), чтобы сгенерировать текст на основе запроса, содержащего текст и до одного файла изображения (только в формате Bitmap), указав mimeType для каждого входного файла и сам файл.

Kotlin 

// Imports + initialization of Gemini API backend service + creation of model instance

// Loads an image from the app/res/drawable/ directory
val bitmap: Bitmap = BitmapFactory.decodeResource(resources, R.drawable.sparky)

// Provide a prompt that includes the image specified above and text
val prompt = content {
  image(bitmap)
  text("What developer tool is this mascot from?")
}

// To generate text output, call generateContent with the prompt
val response = model.generateContent(prompt)
print(response.text)

Java 

// Imports + initialization of Gemini API backend service + creation of model instance

Bitmap bitmap = BitmapFactory.decodeResource(getResources(), R.drawable.sparky);

// Provide a prompt that includes the image specified above and text
Content content = new Content.Builder()
        .addImage(bitmap)
        .addText("What developer tool is this mascot from?")
        .build();

// To generate text output, call generateContent with the prompt
ListenableFuture<GenerateContentResponse> response = model.generateContent(content);
Futures.addCallback(response, new FutureCallback<GenerateContentResponse>() {
    @Override
    public void onSuccess(GenerateContentResponse result) {
        String resultText = result.getText();
        System.out.println(resultText);
    }

    @Override
    public void onFailure(Throwable t) {
        t.printStackTrace();
    }
}, executor);

Обратите внимание, что Firebase AI Logic также поддерживает потоковую передачу текстовых ответов с помощью generateContentStream (вместо generateContent).

Что ещё ты умеешь делать?

Для гибридных экспериментов можно использовать различные дополнительные параметры конфигурации и возможности:

Функции, которые пока недоступны для обработки на устройстве

Поскольку это экспериментальная версия, не все возможности облачных моделей доступны для вывода на устройстве. Следующие функции пока недоступны для инференса на устройстве (но обычно доступны для облачного инференса).

  • Генерирование изображений

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

  • Генерировать текст на основе изображений, формат которых отличается от Bitmap (изображение загружено в память).

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

  • Создание сгенерированного текста на основе файла с изображением. Для инференса на устройстве необходимо предоставить текст в составе мультимодального запроса.

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

  • Генерирование текста на основе нескольких графических файлов

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

  • Генерация текста на основе аудио, видео и документов (например, PDF-файлов).

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

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

    • Если вы укажете URL файла с помощью fileData (FileDataPart), то в качестве резервного варианта может использоваться модель, размещенная в облаке (в режиме ONLY_ON_DEVICE будет выдано исключение).
    • Если вы вставите URL непосредственно в текстовый запрос, он не будет автоматически перенаправлен в облачную модель (модель на устройстве игнорирует встроенные URL).

  • Отправка запросов, превышающих 4000 токенов (примерно 3000 слов на английском языке).

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

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

    • Не переключается автоматически на облачную модель. При локальном инференсе история запросов объединяется в один текстовый запрос. Поскольку локальная модель не различает роли и воспринимает историю как одно сообщение, она не будет такой же точной, как облачная.
    • Если вы хотите использовать пошаговый чат, рекомендуем выбрать режим ONLY_IN_CLOUD.

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

    • Не переключается автоматически на модель, размещенную в облаке. Если вы хотите использовать инструменты, рекомендуем режим ONLY_IN_CLOUD.

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

Дополнительные ограничения

Помимо перечисленного выше, у инференса на устройстве есть следующие ограничения (подробнее об этом рассказывается в документации ML Kit):

  • Конечный пользователь вашего приложения должен использовать поддерживаемое устройство для вывода на устройстве.

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

  • Для локального вывода проверены только английский и корейский языки.

  • Максимальный лимит токенов для всего запроса на локальный инференс составляет 4000 токенов. Если ваши запросы могут превысить это ограничение, настройте режим инференса, который может использовать модель, размещенную в облаке.

  • Мы не рекомендуем использовать варианты использования инференса на устройстве, требующие длинного вывода (более 256 токенов).

  • AICore (системный сервис Android, который управляет моделями на устройстве) устанавливает квоту на инференс для каждого приложения. Если за короткий период времени будет отправлено слишком много запросов к API, вы получите ответ ErrorCode.BUSY. Если вы получаете эту ошибку, попробуйте использовать экспоненциальную выдержку для повторной отправки запроса. Кроме того, код ошибки ErrorCode.PER_APP_BATTERY_USE_QUOTA_EXCEEDED может быть возвращен, если приложение превышает квоту на длительный период (например, дневную квоту).


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