THE3RDTRAINER/Homepage

Fundamentos do Firebase AI Logic

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 por meio do Firebase AI Logic, sem que o desenvolvedor precise gerenciar um backend dedicado. O Firebase AI Logic era anteriormente conhecido como "Vertex AI para Firebase".

Ele suporta os 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 (anteriormente 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 (anteriormente chamada de 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 da Firebase CLI abaixo são executados através do npx em todas as plataformas, portanto, eles precisam de Node.js 20+ e npm. Use o skill firebase-basics para verificar esses requisitos e fazer login na 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 nesse skill. Não instale pacotes do sistema por conta própria, por exemplo com sudo apt-get, pois isso altera a máquina do usuário sem o consentimento dele.

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

Use a 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 da Firebase CLI no Projeto Firebase correto. Ao executar este comando, o projeto ativo é marcado com "current":

   npx -y firebase-tools@latest projects:list
   

3. Certifique-se de que haja pelo menos um Aplicativo Firebase para a plataforma de destino 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] IMPORTANTE: O provisionamento do Firebase AI Logic é obrigatório Para todas as plataformas (Android, iOS, Web ou Flutter), mesmo que o aplicativo já use o 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, resultando em erros PERMISSION_DENIED.

Se você não puder executar init ailogic por conta própria (por exemplo, porque o Node.js está ausente ou a Firebase CLI não está logada), NÃO o ignore. 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 de destino listada em Referências de Código de Inicialização.

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

---

Capacidades Principais

[!WARNING] IMPORTANTE: 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 aplicativo. 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 para Firebase e passe suas URLs para a Gemini Developer API.

Sessão de Chat (Múltiplas Interações)

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 uma exibição mais rápida dos resultados.

Geração de Texto para Fala (TTS)

Gere áudio falado diretamente em dispositivos cliente sem um backend de fala personalizado. O Firebase AI Logic oferece suporte à 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.

Search Grounding com a ferramenta googleSearch integrada

---

Plataformas e Frameworks Suportados

As plataformas e frameworks suportados incluem Kotlin e Java para Android, Swift para iOS, JavaScript para aplicativos web, Dart para Flutter e C# 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 recai para 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 contém 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 de destino.

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 ignorar o atestado padrão.

[!WARNING] IMPORTANTE: Nunca codifique ou comente tokens de depuração Os tokens de depuração do App Check permitem que clientes ignorem o atestado e acessem recursos de backend sem um dispositivo genuíno. Trate-os como segredos privados. Nunca comente tokens de depuração no controle de versão ou codifique strings de token brutas no código do cliente (Web, Android, iOS ou Flutter). Sempre injete-os por meio 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 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. Verifique os logs do console de depuração / 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 Firebase em Segurança > App Check > Aplicativos > Gerenciar tokens de depuração.

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

Pipelines CI/CD (Pré-Provisionados)

1. Gere e registre um novo token de depuração no Console 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 build 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 codificar nomes de modelo (por exemplo, uma string de versão de modelo específica). Use o Firebase Remote Config para atualizar versões de modelo dinamicamente sem implantar novo código do cliente. Consulte Alterando nomes de modelo 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 (API Modular)

  • 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] IMPORTANTE: 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