Crie experiências híbridas em apps Android com modelos hospedados na nuvem e no dispositivo


É possível criar apps e recursos Android com tecnologia de IA e inferência híbrida usando Firebase AI Logic. A inferência híbrida permite executar a inferência usando modelos no dispositivo quando disponíveis e fazer o fallback para modelos hospedados na nuvem (e vice-versa).

Esta página descreve como começar a usar o SDK do cliente, além de mostrar outras opções e recursos de configuração, como a temperatura.

A inferência no dispositivo via Firebase AI Logic é compatível com apps Android executados em dispositivos específicos e é regida pelos termos do Kit de ML, bem como pelos termos específicos dos aspectos de IA generativa do Kit de ML.

Casos de uso recomendados e recursos compatíveis

Casos de uso recomendados

  • O uso de um modelo no dispositivo para inferência oferece:

    • Privacidade aprimorada
    • Contexto local
    • Inferência sem custo financeiro
    • Funcionalidade off-line

  • O uso da funcionalidade híbrida oferece:

    • Alcance um público maior acomodando a disponibilidade do modelo no dispositivo e a conectividade com a Internet

Recursos e funcionalidades compatíveis com a inferência no dispositivo

A inferência no dispositivo só oferece suporte à geração de texto de turno único (não chat), com saída de streaming ou não streaming. Ela oferece suporte aos seguintes recursos de geração de texto:

Confira a lista de recursos ainda não disponíveis para inferência no dispositivo na parte de baixo desta página.

Antes de começar

Observações:

Dispositivos Android compatíveis e modelos no dispositivo

Para inferência no dispositivo (que usa a API Prompt do Kit de ML), você pode encontrar uma lista de dispositivos compatíveis e modelos no dispositivo na documentação do Kit de ML.

Primeiros passos

Estas etapas de primeiros passos descrevem a configuração geral necessária para qualquer solicitação de comando compatível que você queira enviar.

Etapa 1: configurar um projeto do Firebase e conectar o app ao Firebase

  1. Faça login no Firebase console, e selecione seu Projeto do Firebase.

  2. No console do Firebase, acesse Serviços de IA > Lógica de IA.

  3. Clique em Começar para iniciar um fluxo de trabalho guiado que ajuda a configurar as APIs necessárias e os recursos para seu projeto.

  4. Configure seu projeto para usar um provedor "Gemini API".

    Recomendamos começar usando a Gemini Developer API. A qualquer momento, você pode sempre configurar a Vertex AI Gemini API (e o requisito de faturamento).

    Para o Gemini Developer API, o console vai ativar as APIs necessárias e criar uma chave de API Gemini no seu projeto.
    Não adicione essa chave de API Gemini à base de código do seu app.     Saiba mais.

  5. Se solicitado no fluxo de trabalho do console, siga as instruções na tela para registrar seu app e conectá-lo ao Firebase.

  6. Continue para a próxima etapa deste guia para adicionar o SDK ao seu app.

Etapa 2: adicionar os SDKs necessários

O Firebase AI Logic SDK para Android (firebase-ai) e o Firebase AI Logic On-Device SDK (firebase-ai-ondevice) fornecem acesso às APIs para interagir com modelos generativos.

No arquivo do Gradle do módulo (nível do app) (como <project>/<app-module>/build.gradle.kts), adicione as dependências das Firebase AI Logic bibliotecas para Android:

Kotlin 

dependencies {
  // ... other androidx dependencies

  // Add the dependencies for the Firebase AI Logic libraries
  // Note that the on-device SDK is not yet included in the Firebase Android BoM
  implementation("com.google.firebase:firebase-ai:17.11.0")
  implementation("com.google.firebase:firebase-ai-ondevice:16.0.0-beta01")
}

Java

Para Java, é necessário adicionar mais duas bibliotecas.

dependencies {
  // ... other androidx dependencies

  // Add the dependencies for the Firebase AI Logic libraries
  // Note that the on-device SDK is not yet included in the Firebase Android BoM
  implementation("com.google.firebase:firebase-ai:17.11.0")
  implementation("com.google.firebase:firebase-ai-ondevice:16.0.0-beta01")

  // 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")
}

Etapa 3: verificar se o modelo no dispositivo está disponível

Usando FirebaseAIOnDevice, verifique se o modelo no dispositivo está disponível e faça o download dele se não estiver disponível.

Depois de fazer o download, o AICore vai manter o modelo atualizado automaticamente. Confira as observações após o snippet para mais detalhes sobre o AICore e o gerenciamento do download do modelo no dispositivo.

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 and downloading the model is not yet available for Java.

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

Observe o seguinte sobre o download do modelo no dispositivo:

  • O tempo necessário para fazer o download do modelo no dispositivo depende de muitos fatores, incluindo sua rede.

  • Se o código usar um modelo no dispositivo para a inferência principal ou de fallback, verifique se o modelo foi baixado no início do ciclo de vida do app para que o modelo no dispositivo esteja disponível antes que os usuários finais encontrem o código no app.

  • Se o modelo no dispositivo não estiver disponível quando uma solicitação de inferência no dispositivo for feita, o SDK não vai acionar automaticamente o download do modelo no dispositivo. O SDK vai fazer o fallback para o modelo hospedado na nuvem ou gerar uma exceção (consulte detalhes sobre o comportamento dos modos de inferência).

  • AICore (um serviço do sistema Android) gerencia qual modelo e versão são baixados, mantendo o modelo atualizado etc. O dispositivo só terá um modelo baixado. Portanto, se outro app no dispositivo tiver feito o download do modelo no dispositivo, essa verificação vai retornar que o modelo está disponível.

Otimização da latência

Para otimizar a primeira chamada de inferência, você pode fazer com que o app chame warmup(). Isso carrega o modelo no dispositivo na memória e inicializa os componentes de execução.

Etapa 4: inicializar o serviço e criar uma instância de modelo

Clique no provedor Gemini API para conferir o conteúdo específico do provedor e o código nesta página.

Configure o seguinte antes de enviar uma solicitação de comando ao modelo.

  1. Inicialize o serviço para o provedor de API escolhido.

  2. Crie uma instância GenerativeModel e defina o mode como um dos seguintes. As descrições aqui são muito gerais, mas você pode aprender detalhes sobre o comportamento desses modos em Definir um modo de inferência.

    • PREFER_ON_DEVICE: tenta usar o modelo no dispositivo. Caso contrário, faz o fallback para o modelo hospedado na nuvem.

    • ONLY_ON_DEVICE: tenta usar o modelo no dispositivo. Caso contrário, gera uma exceção.

    • PREFER_IN_CLOUD: tenta usar o modelo hospedado na nuvem. Caso contrário, faz o fallback para o modelo no dispositivo.

    • ONLY_IN_CLOUD: tenta usar o modelo hospedado na nuvem. Caso contrário, gera uma exceção.

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 = "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(
        "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);

Etapa 5: enviar uma solicitação de comando a um modelo

Esta seção mostra como enviar vários tipos de entrada para gerar diferentes tipos de saída, incluindo:

Gerar texto com base em entradas somente de texto

Antes de tentar este exemplo, confira se você concluiu a Primeiros passos seção deste guia.

É possível usar generateContent() para gerar texto com base em um comando que contém texto:

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);

Observe que Firebase AI Logic também oferece suporte ao streaming de respostas de texto usando generateContentStream (em vez de generateContent).

Gerar texto com base em entradas de texto e imagem (multimodais)

Antes de tentar este exemplo, confira se você concluiu a Primeiros passos seção deste guia.

É possível usar generateContent() para gerar texto com base em um comando que contém texto e até um arquivo de imagem (somente bitmap) , fornecendo o mimeType e o arquivo de cada entrada.

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);

Observe que Firebase AI Logic também oferece suporte ao streaming de respostas de texto usando generateContentStream (em vez de generateContent).

O que mais você sabe fazer?

É possível usar várias outras opções e recursos de configuração para suas experiências híbridas:

Recursos ainda não disponíveis para inferência no dispositivo

Como um lançamento experimental, nem todos os recursos de modelos de nuvem estão disponíveis para inferência no dispositivo.

Os recursos listados nesta seção ainda não estão disponíveis para inferência no dispositivo. Se você quiser usar qualquer um desses recursos, recomendamos usar o modo de inferência ONLY_IN_CLOUD para uma experiência mais consistente.

  • Gerar saída estruturada (como JSON ou enums)

  • Gerar texto com base em tipos de entrada de arquivo de imagem diferentes de bitmap (imagem carregada na memória)

  • Gerar texto com base em mais de um arquivo de imagem

  • Gerar texto com base em entradas de áudio, vídeo e documentos (como PDFs)

  • Gerar imagens usando modelos Gemini ou Imagen

  • Fornecer arquivos usando URLs em solicitações multimodais. É necessário fornecer arquivos como dados inline para modelos no dispositivo

  • Enviar solicitações que excedam 4.000 tokens (ou aproximadamente 3.000 palavras em inglês).

  • Conversa multiturno

  • Fornecer ferramentas ao modelo para ajudar a gerar a resposta (como chamada de função, execução de código, contexto de URL e embasamento com a Pesquisa Google)

O monitoramento de IA no console Firebase não mostra dados para inferência no dispositivo (incluindo registros no dispositivo). No entanto, qualquer inferência que use um modelo hospedado na nuvem pode ser monitorada como outras inferências pela Firebase AI Logic.

Outras limitações

Além do acima, a inferência no dispositivo tem as seguintes limitações (saiba mais na documentação do Kit de ML):

  • O usuário final do seu app precisa usar um dispositivo compatível com a inferência no dispositivo.

  • O app só pode executar a inferência no dispositivo quando estiver em primeiro plano.

  • Somente inglês e coreano foram validados para inferência no dispositivo.

  • O limite máximo de tokens para toda a solicitação de inferência no dispositivo é de 4.000 tokens. Se as solicitações excederem esse limite, configure um modo de inferência que possa usar um modelo hospedado na nuvem.

  • Recomendamos evitar casos de uso de inferência no dispositivo que exigem saída longa (mais de 256 tokens).

  • AICore (um serviço do sistema Android que gerencia os modelos no dispositivo) aplica uma cota de inferência por app. Fazer muitas solicitações de API em um curto período vai resultar em uma resposta ErrorCode.BUSY. Se você estiver recebendo esse erro, considere usar a espera exponencial para tentar a solicitação novamente. Além disso, ErrorCode.PER_APP_BATTERY_USE_QUOTA_EXCEEDED pode ser retornado se um app exceder uma cota de longa duração (por exemplo, cota diária).


Enviar feedback sobre sua experiência com Firebase AI Logic