Fundamentos do Firebase AI Logic

O que Fundamentos do Firebase AI Logic faz?

Visão Geral

O Firebase AI Logic é um produto do Firebase que permite que desenvolvedores adicionem IA generativa

a seus aplicativos móveis e web usando SDKs do lado do cliente. O aplicativo pode chamar diretamente os modelos Gemini via Firebase AI Logic, sem que o desenvolvedor precise gerenciar um backend dedicado. O Firebase AI Logic era anteriormente conhecido como "Vertex AI for Firebase".

Ele suporta dois provedores da API Gemini:

• Gemini Developer API: Possui um nível gratuito ideal para prototipação e pagamento conforme o uso para produção
• Agent Platform Gemini API (antigamente chamado de Vertex AI): Ideal para escala com prontidão de produção de nível empresarial, requer o plano de preços Blaze

Use a Gemini Developer API como padrão, e somente a Agent Platform Gemini API (antigo Vertex AI) se o aplicativo exigir.

---

Configuração e inicialização

Pré-requisitos

• Identifique a plataforma na qual o usuário deseja desenvolver antes de começar: Android, iOS, Web ou Flutter.
• Se a plataforma não for suportada, direcione o usuário para a Documentação do Firebase para aprender como configurar o AI Logic para seu aplicativo (compartilhe este link com o usuário https://firebase.google.com/docs/ai-logic/get-started)
• Os comandos do Firebase CLI abaixo são executados através de npx em todas as plataformas, portanto eles precisam de Node.js 20+ e npm. Use a skill firebase-basics para verificar a existência deles e fazer login no Firebase CLI. Se o Node.js estiver ausente ou for mais antigo que a versão 20, peça ao usuário para instalá-lo conforme descrito nessa skill. Não instale pacotes do sistema você mesmo, por exemplo com sudo apt-get, pois isso altera a máquina do usuário sem seu consentimento.

1. Provisionar o Firebase AI Logic (TODAS as plataformas)

Use o Firebase CLI para provisionar o Firebase AI Logic para o Projeto Firebase:

1. Certifique-se de estar em um diretório firebase (com um firebase.json).

2. Verifique se você está executando comandos do Firebase CLI contra o Projeto Firebase pretendido. Ao executar este comando, o projeto ativo é marcado com "current":

   npx -y firebase-tools@latest projects:list
   

3. Certifique-se de que há pelo menos um Aplicativo Firebase para a plataforma alvo registrado no Projeto Firebase atual:

   npx -y firebase-tools@latest apps:list
   

4. Provisione o Firebase AI Logic para o Projeto Firebase:

   npx -y firebase-tools@latest init ailogic
   

   Este comando habilitará a Gemini Developer API no projeto Firebase.

[!WARNING] CRÍTICO: Provisionar o Firebase AI Logic é Obrigatório Para todas as plataformas (Android, iOS, Web ou Flutter), mesmo que o aplicativo já use Firebase, você DEVE executar npx -y firebase-tools@latest init ailogic para provisionar o serviço. Os arquivos de configuração GoogleService-Info.plist, google-services.json e firebase_options.dart lidam APENAS com a configuração do cliente e NÃO habilitam o serviço Firebase AI Logic, levando a erros PERMISSION_DENIED.

Se você não puder executar init ailogic (por exemplo, porque o Node.js está ausente ou o Firebase CLI não está logado), NÃO o pule. As requisições do aplicativo aos modelos Gemini falharão até que o serviço Firebase AI Logic seja provisionado. Diga ao usuário para executar este comando no diretório do projeto e inclua-o em seu resumo final:

npx -y firebase-tools@latest init ailogic

2. Adicionar o SDK e inicializar o serviço no aplicativo

Adicionar a dependência do SDK e inicializar o serviço são específicos da plataforma. Antes de escrever código, leia a referência para a plataforma alvo listada em Referências de Código de Inicialização.

Mais informações em Primeiros Passos com Firebase AI Logic

---

Capacidades Principais

[!WARNING] CRÍTICO: Use nomes de modelo atuais: Sempre verifique a Documentação de Modelos do Firebase AI Logic para os nomes de modelo atualmente suportados. NÃO use gemini-2.0-pro ou gemini-2.0-flash ou outros modelos mais antigos que foram descontinuados.

Geração Apenas de Texto

Multimodal (Entrada de Texto + Imagens/Áudio/Vídeo/PDF)

O Firebase AI Logic permite que os modelos Gemini analisem arquivos de imagem diretamente do seu app. Isso permite recursos como criar legendas, responder perguntas sobre imagens, detectar objetos e categorizar imagens. Além de imagens, o Gemini pode analisar outros tipos de mídia como áudio, vídeo e PDFs, passando-os como dados inline com seu tipo MIME. Para arquivos maiores que 20 megabytes (que podem causar erros HTTP 413 como dados inline), armazene-os no Cloud Storage for Firebase e passe suas URLs para a Gemini Developer API.

Sessão de Chat (Multi-turn)

Mantenha o histórico automaticamente usando startChat.

Respostas em Streaming

Para melhorar a experiência do usuário mostrando resultados parciais à medida que chegam (como um efeito de digitação), use generateContentStream em vez de generateContent para exibição mais rápida dos resultados.

Geração de Texto-para-Fala (TTS)

Gere áudio falado diretamente em dispositivos clientes sem um backend de fala personalizado. O Firebase AI Logic suporta síntese de fala usando modelos Gemini TTS dedicados:

• Modelos Suportados: gemini-3.1-flash-tts-preview
• Capacidades:
  • Seleção de persona de voz de um único locutor (voiceName) e diálogos com múltiplos locutores (até 2 locutores distintos) via SpeechConfig / MultiSpeakerVoiceConfig
  • Respostas de áudio diretas configurando responseModalities para áudio
  • Respostas de fala em streaming com generateContentStream para reprodução de baixa latência
  • Diretivas de áudio ([Audio Profile: ...], [Scene: ...], [Director's Note: ...]) e tags emocionais ([whispers], [laughs], [slowly])
  • Decodificação e reprodução no lado do cliente de PCM linear de 24 kHz 16 bits (audio/l16) ou formato de contêiner WAV (audio/x-wav)

Consulte o Guia de Geração de Texto-para-Fala (TTS) para detalhes completos de implementação, padrões de streaming e trechos de código copiáveis para iOS (Swift), Android (Kotlin) e Web.

Gerar Imagens com Nano Banana

[!WARNING] Use nomes de modelo de imagem atuais: Sempre verifique a Documentação de Modelos do Firebase AI Logic para os nomes de modelo de geração de imagem (Nano Banana) atualmente suportados.

• Requer um plano de faturamento Blaze pagamento conforme o uso atualizado.

Fundamentação de Pesquisa com a ferramenta googleSearch integrada

---

Plataformas e Frameworks Suportados

Plataformas e Frameworks Suportados incluem Kotlin e Java para Android, Swift para iOS, JavaScript para aplicativos web, Dart para Flutter e C Sharp para Unity.

Recursos Avançados

Saída Estruturada (JSON)

Imponha um esquema JSON específico para a resposta.

IA no Dispositivo (Híbrida)

A inferência híbrida executa prompts com um modelo no dispositivo quando disponível e recorre a um modelo hospedado na nuvem caso contrário (ou vice-versa). A disponibilidade e as etapas de configuração diferem por plataforma; mais informações na documentação híbrida e no dispositivo, que possui links para o guia de cada plataforma.

---

Segurança e Produção

Firebase App Check

[!WARNING] Requisito Crítico de Segurança: Para usar o AI Logic com segurança, você DEVE configurar o App Check em seu aplicativo. Isso impede que clientes não autorizados usem sua cota de API e acessem seus recursos de backend.

Consulte App Check para Firebase AI Logic para instruções de configuração. Cada plataforma usa seu próprio provedor de atestado, portanto siga as instruções para a plataforma alvo.

Tokens de Depuração do App Check para Desenvolvimento Local e CI/CD

Como os provedores de atestado do App Check (como Play Integrity ou DeviceCheck) rejeitam emuladores, simuladores ou ambientes de CI, você deve usar Tokens de Depuração do App Check durante o desenvolvimento e teste para contornar o atestado padrão.

[!WARNING] CRÍTICO: Nunca Hardcode ou Comprometa Tokens de Depuração Tokens de depuração do App Check permitem que clientes contornem o atestado e acessem recursos de backend sem um dispositivo genuíno. Trate-os como segredos privados. Nunca comprometa tokens de depuração em controle de versão ou hardcode strings de token brutas no código do cliente (Web, Android, iOS ou Flutter). Sempre os injete através de variáveis de ambiente locais, configurações locais ignoradas pelo git ou segredos de CI. Se um token for comprometido, revogue-o imediatamente no Console do Firebase.

Desenvolvimento Local (Gerado Automaticamente)

1. Configure o provedor App Check do seu código para usar a fábrica de depuração. A API é específica da plataforma; consulte a seção App Check da referência da plataforma ou a documentação do App Check vinculada acima.
2. Execute seu aplicativo no emulador/localhost.
3. Observe seu console de depuração / logs do Logcat em tempo de execução para o UUID gerado:
   • Exemplo: AppCheck debug token: "123a4567-b89c-12d3-e456-789012345678"
4. Registre este token no Console do Firebase em Segurança > App Check > Aplicativos > Gerenciar tokens de depuração.

💡 Dica (Evite Rotatividade de Token de Depuração): Reinicializações de simulador ou emulador, instalações novas e limpeza de dados do navegador podem fazer o SDK gerar um novo token de depuração que você deve registrar novamente. Para manter um token de depuração estável sem hardcoded, consulte a seção App Check da referência da plataforma.

Pipelines de CI/CD (Pré-Provisionados)

1. Gere e registre um novo token de depuração no Console do Firebase em Segurança > App Check > Aplicativos > Gerenciar tokens de depuração.
2. Adicione esta string de token como um segredo criptografado em seu sistema de CI (por exemplo, APP_CHECK_DEBUG_TOKEN).
3. Configure sua compilação para passar este segredo como uma variável de ambiente para o SDK durante a execução do teste.

Firebase Remote Config

Considere que você não precisa hardcodear nomes de modelos (por exemplo, uma string de versão de modelo específica). Use o Firebase Remote Config para atualizar versões de modelos dinamicamente sem implantar novo código do cliente. Consulte Alterando nomes de modelos remotamente

---

Referências de Código de Inicialização

• Android (Kotlin)

  • Provedor da API Gemini: Gemini Developer API
  • Referência: usage_patterns_android.md

• iOS (Swift)

  • Provedor da API Gemini: Gemini Developer API
  • Referência: ios_setup.md

• Web Modular API

  • Provedor da API Gemini: Gemini Developer API
  • Referência: usage_patterns_web.md

• Flutter (Dart)

  • Provedor da API Gemini: Gemini Developer API
  • Referência: flutter_setup.md

[!WARNING] CRÍTICO: Use nomes de modelo atuais: Sempre verifique a Documentação de Modelos do Firebase AI Logic para os nomes de modelo atualmente suportados. NÃO use gemini-2.0-pro ou gemini-2.0-flash ou outros modelos mais antigos que foram descontinuados.

Referências

Padrões de uso do SDK Android (Kotlin) Exemplos de código e padrões de uso do SDK iOS Configuração, exemplos de código e padrões de uso do SDK Web

Exemplos de código e padrões de uso do SDK Flutter Geração de Texto-para-Fala (TTS) no lado do cliente