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

É possível criar apps e recursos da Apple com tecnologia de IA usando inferência híbrida com o Firebase AI Logic. A inferência híbrida permite executar inferências usando modelos no dispositivo (especificamente o framework de modelos de fundação da Apple), quando disponíveis, e, caso contrário, recorrer aos modelos do Google hospedados na nuvem (e vice-versa).

Nesta página, descrevemos como começar a usar o SDK do cliente. Depois de concluir essa configuração padrão, confira as outras opções e recursos de configuração.

A inferência no dispositivo via Firebase AI Logic é compatível com apps da Apple que usam o SDK do Firebase AI Logic v12.13.0+ e são executados em dispositivos com o Apple Intelligence ativado. Ele é regido pelos Requisitos de uso aceitável para o framework de modelos de fundação da Apple.

Ir para exemplos de código de visualização

Casos de uso e recursos compatíveis

Dependendo dos casos de uso do seu app, você pode aproveitar vários benefícios das experiências híbridas ou no dispositivo:

  • Benefícios de usar um modelo no dispositivo para inferência:

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

  • Benefícios de usar uma abordagem híbrida:

    • Oferecer uma experiência semelhante no app, independente do dispositivo do usuário final
    • Melhorar a disponibilidade dos recursos de IA generativa, independentemente da conectividade com a Internet, das limitações de cota ou dos recursos do dispositivo

Recursos de inferência no dispositivo compatíveis

A inferência no dispositivo só oferece suporte à geração de texto, especificamente aos seguintes recursos:

Confira a lista de recursos ainda não compatíveis com inferência híbrida ou no dispositivo na parte de baixo desta página.

APIs e dispositivos compatíveis

As seções a seguir descrevem as APIs compatíveis, bem como os dispositivos compatíveis (e os modelos no dispositivo).

APIs compatíveis com inferência na nuvem e no dispositivo

Dispositivos Apple compatíveis e os modelos no dispositivo

Para inferência no dispositivo (que usa o framework de modelos de fundação da Apple), consulte uma lista de dispositivos com o Apple Intelligence ativado na documentação da Apple.

Primeiros passos

Estas etapas de introdução descrevem a configuração geral necessária para qualquer solicitação de comando com suporte 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 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 do projeto.

  4. Se solicitado, siga as instruções na tela para registrar o app e adicionar a configuração do Firebase a ele.

  5. Quando for solicitado que você escolha um "provedor da API Gemini", recomendamos selecionar a API Gemini Developer, que permite começar rapidamente sem custos financeiros.

    A qualquer momento, é possível configurar o Agent Platform Gemini API (formerly Vertex AI) (e o requisito de faturamento).

  6. Continue no fluxo de trabalho para configurar as APIs necessárias e os serviços associados para Firebase AI Logic.

    Essa etapa do fluxo de trabalho aplica automaticamente o Firebase App Check para o AI Logic, que é um serviço essencial para ajudar a proteger o Gemini API quando ele é acessado diretamente pelo app. Como parte do processo de introdução (consulte as etapas mais adiante neste guia), você precisará configurar o provedor de depuração do App Check para desenvolvimento local quando o App Check for aplicado.

  7. Siga para a próxima etapa deste guia para adicionar os SDKs necessários ao seu app.

Etapa 2: adicionar os SDKs necessários

Use o Swift Package Manager (SPM) para instalar e gerenciar as dependências do Xcode. O suporte híbrido só está disponível ao usar o SPM.

A biblioteca Firebase AI Logic fornece acesso às APIs para interagir com modelos generativos. A biblioteca está incluída como parte do SDK do Firebase para plataformas Apple (firebase-ios-sdk).

Se você já usa o Firebase, verifique se o pacote é da versão 12.13.0 ou mais recente.

  1. No Xcode, com seu projeto de app aberto, acesse File > Add Package Dependencies.

  2. Quando solicitado, adicione o repositório do SDK do Firebase para as plataformas Apple:

    https://github.com/firebase/firebase-ios-sdk

  3. Selecione a versão mais recente do SDK.

  4. Selecione as bibliotecas FirebaseAILogic e FirebaseAppCheck.

Quando terminar, o Xcode vai começar a resolver e fazer o download das dependências em segundo plano automaticamente.

Etapa 3: configurar o provedor de depuração do App Check para desenvolvimento local

Como parte do fluxo de trabalho de configuração guiada para AI Logic no console, Firebase App Check é aplicado automaticamente para proteger o Gemini API. Para o desenvolvimento local, é necessário configurar o provedor de depuração do App Check para ignorar o atestado, mantendo a aplicação do App Check.

Veja como usar o provedor de depuração ao executar o app em um simulador de forma interativa (por exemplo, durante o desenvolvimento local):

  1. No projeto do Xcode, importe FirebaseAppCheck e inicialize App Check com a fábrica do provedor de depuração antes de configurar Firebase.

    import SwiftUI
import FirebaseCore
import FirebaseAppCheck

@main
struct YourApp: App {
  init() {
    let providerFactory = AppCheckDebugProviderFactory()
    AppCheck.setAppCheckProviderFactory(providerFactory)
    FirebaseApp.configure()
  }

  var body: some Scene {
    WindowGroup {
      NavigationView {
        ContentView()
      }
    }
  }
}

  2. Receba seu token de depuração:

    1. Inicie o app no simulador ou no dispositivo de teste.

    2. Abra o console do Xcode e procure o token de depuração App Check. Exemplo:

      <Warning> [AppCheckCore][I-GAC004001] App Check debug token: '123a4567-b89c-12d3-e456-789012345678'.

    3. Copie o token (por exemplo, 123a4567-b89c-12d3-e456-789012345678).

  3. Registre seu token de depuração com App Check:

    1. No console do Firebase, acesse a guia Segurança > App Check > Apps.

    2. Encontre seu app, clique no menu flutuante () e selecione Gerenciar tokens de depuração.

    3. Siga as instruções na tela para registrar o token de depuração.

Para saber mais sobre o provedor de depuração (incluindo como receber um novo token de depuração), confira a documentação oficial do App Check.

Etapa 4: inicializar o serviço e criar uma instância de sessão 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 Gemini API escolhido.

  2. Crie uma instância GenerativeModelSession com um HybridModel.

  3. Defina os modelos primary e secondary com base nas suas preferências. É possível definir a ordem da tentativa de inferência:

    • Tentar a inferência no dispositivo primeiro, mas permitir o fallback para a nuvem: defina primary como um modelo de "sistema" e secondary como um modelo de nuvem.

    • Tentar a inferência na nuvem primeiro, mas permitir o fallback para o dispositivo: defina primary como um modelo de nuvem e secondary como um modelo de "sistema".

    O SDK permite definir apenas um único model, o que significa que ele vai tentar apenas a inferência no dispositivo ou na nuvem. No entanto, para uma experiência híbrida, é necessário criar um HybridModel e definir os modelos primary e secondary.

    Saiba mais sobre o comportamento dos "modos de inferência" (a ordem da tentativa de inferência) em Opções de configuração.

O exemplo a seguir mostra como tentar a inferência no dispositivo primeiro, mas permitir o retorno ao modelo hospedado na nuvem:

// Initialize the Gemini Developer API backend service.
let ai = FirebaseAI.firebaseAI(backend: .googleAI())

// Initialize a cloud model that supports your use case.
let cloudModel = ai.geminiModel(name: "GEMINI_MODEL_NAME")
// Initialize an on-device model that supports your use case.
let systemModel = FirebaseAI.SystemLanguageModel.default

// Create a Hybrid Model.
// Provide your preferred model as `primary` and your fallback model as `secondary`.
// In this example, attempt to use on-device model; otherwise, fall back to cloud.
let hybridModel = HybridModel(
  primary: systemModel,
  secondary: cloudModel
)

// Create a GenerativeModelSession with the HybridModel created earlier.
let session = firebaseAI.generativeModelSession(
  model: hybridModel,
)

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

Nesta seção, mostramos como fazer o seguinte:

Gerar texto com base em entrada somente de texto

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

Para gerar texto com base em um comando que contém texto, use respond(to:) assim:

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

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

// To generate text output, call `respond(to:)` with the text input
let response = try await session.respond(to: prompt)
print(response.content)

Fazer streaming de texto gerado com base em entrada somente de texto

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

Para interações mais rápidas, não espere o resultado completo da geração do modelo. Em vez disso, use o streaming para processar resultados parciais. Para fazer streaming de texto gerado com base em um comando que contém texto, use streamResponse(to:) desta forma:

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

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

// To stream generated text output, call `streamResponse(to:)` with the text input
let stream = session.streamResponse(to: prompt)
for try await snapshot in stream {
  print(snapshot.content)
}

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

Como uma versão experimental, nem todos os recursos dos modelos hospedados na nuvem ou do SDK do Firebase AI Logic estão disponíveis para inferência híbrida ou no dispositivo.

Recursos ainda não disponíveis para implementações híbridas

Os recursos a seguir não podem ser usados com implementações híbridas (nem no dispositivo nem por substituição na nuvem):

  • Gemini Live API: o streaming bidirecional em tempo real não é compatível.

  • Modelos de comando do servidor: não há suporte para modelos de comando do servidor gerenciados.

  • Contagem de tokens: não é recomendável confiar na contagem de tokens porque ela varia entre os modelos hospedados na nuvem e no dispositivo. Portanto, não há um substituto intuitivo.

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

Os recursos a seguir ainda não são compatíveis com a inferência no dispositivo, mas estão disponíveis para modelos hospedados na nuvem.

  • Gerar mídia, como imagens, áudio ou vídeo

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

  • Enviar solicitações que excedem 4.096 tokens (ou aproximadamente 3.000 palavras em inglês)

  • Fornecer ao modelo no dispositivo ferramentas integradas para ajudar a gerar a resposta (como execução de código, contexto de URL, embasamento com Google Search e embasamento com Google Maps). No entanto, é possível fornecer suas próprias ferramentas usando a chamada de função.

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

Outras limitações

Além do que foi mencionado acima, a inferência no dispositivo tem as seguintes limitações:


Envie feedback sobre sua experiência com o Firebase AI Logic