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 o Firebase AI Logic. A inferência híbrida permite executar a inferência usando modelos no dispositivo quando disponíveis e fazer fallback sem problemas para modelos hospedados na nuvem caso contrário (e vice-versa).

Nesta página, descrevemos como começar a usar o SDK do cliente e mostramos outras opções e recursos de configuração, como 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 e pelos termos específicos dos aspectos de IA generativa do Kit de ML.

Casos de uso recomendados e recursos disponíveis

Casos de uso recomendados

  • Usar um modelo no dispositivo para inferência oferece:

    • Privacidade reforçada
    • Contexto local
    • Inferência sem custo financeiro
    • Funcionalidade off-line

  • Usar a funcionalidade híbrida oferece:

    • Alcance mais pessoas do seu público-alvo ao considerar a disponibilidade de modelos no dispositivo e a conectividade com a Internet

Recursos e funcionalidades compatíveis para inferência no dispositivo

A inferência no dispositivo só é compatível com geração de texto de uma única vez (não chat), com saída de streaming ou não streaming. Ele é compatível com os 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), confira uma lista de dispositivos compatíveis e modelos no dispositivo na documentação do Kit de ML.

Primeiros passos

Estas etapas de início 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 seu app a ele

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

  2. No console Firebase, acesse a página Firebase AI Logic.

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

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

    Recomendamos começar usando o Gemini Developer API. A qualquer momento, você pode configurar o 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 app.

Etapa 2: adicionar os SDKs necessários

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

No arquivo Gradle do módulo (nível do app) (como <project>/<app-module>/build.gradle.kts), adicione as dependências das bibliotecas Firebase AI Logic 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.10.0")
  implementation("com.google.firebase:firebase-ai-ondevice:16.0.0-beta01")
}

Java

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

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.10.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.

Depois de baixado, 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 baixar o modelo no dispositivo depende de muitos fatores, incluindo sua rede.

  • Se o código usar um modelo no dispositivo para inferência principal ou de substituição, verifique se o modelo foi baixado no início do ciclo de vida do app para que ele 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 usar o modelo hospedado na nuvem ou gerar uma exceção. Consulte detalhes sobre o comportamento dos modos de inferência.

  • O 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 baixado o modelo no dispositivo com sucesso, essa verificação vai retornar que o modelo está disponível.

Otimização da latência

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

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

Clique no seu provedor de Gemini API para conferir o conteúdo e o código específicos do provedor 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 valores. As descrições aqui são muito gerais, mas você pode saber mais detalhes sobre o comportamento desses modos em Definir um modo de inferência.

    • PREFER_ON_DEVICE: tente usar o modelo no dispositivo. Caso contrário, faça o fallback para o modelo hospedado na nuvem.

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

    • PREFER_IN_CLOUD: tente usar o modelo hospedado na nuvem. Caso contrário, use o modelo no dispositivo.

    • ONLY_IN_CLOUD: tente usar o modelo hospedado na nuvem; caso contrário, gerar 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 testar esta amostra, confira se você concluiu a seção Começar deste guia.

É possível usar o 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);

O Firebase AI Logic também é compatível com o streaming de respostas de texto usando generateContentStream (em vez de generateContent).

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

Antes de testar esta amostra, confira se você concluiu a seção Começar deste guia.

Você pode usar o 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);

O Firebase AI Logic também é compatível com o streaming de respostas de texto usando generateContentStream (em vez de generateContent).

O que mais você pode fazer?

Você pode usar várias opções e recursos de configuração adicionais 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 dos modelos de nuvem estão disponíveis para a 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 algum 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 arquivos 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. Você precisa 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).

  • Chat multiturno

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

O monitoramento de IA no console do Firebase não mostra dados de 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 via Firebase AI Logic.

Outras limitações

Além do exposto acima, a inferência no dispositivo tem as seguintes limitações. Saiba mais na documentação do ML Kit.

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

  • Seu app só pode executar inferências no dispositivo quando está em primeiro plano.

  • Apenas 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 uma saída longa (mais de 256 tokens).

  • O AICore (um serviço do sistema Android que gerencia os modelos no dispositivo) impõe 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, use a espera exponencial para tentar fazer 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).


Envie feedback sobre sua experiência com Firebase AI Logic