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

    С начала июля 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.1.0")
  implementation("com.google.firebase:firebase-ai-ondevice:16.0.0-beta07")
  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.1.0")
  implementation("com.google.firebase:firebase-ai-ondevice:16.0.0-beta07")
  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-адресов в мультимодальных запросах. Для вывода на устройстве необходимо предоставить одно изображение в виде растрового изображения.

    • Если вы укажете 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