Как создавать гибридные приложения 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. Нажмите 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.

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

    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_IN_CLOUD, чтобы обеспечить более стабильную работу.

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

  • Создание текста на основе нескольких изображений

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

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

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

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

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

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

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

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

Помимо перечисленных выше, вывод на устройстве имеет следующие ограничения (подробнее о ML Kit…):

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

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

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

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

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

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


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