Crie apps da Web com tecnologia de IA usando as Extensões do Firebase

1. Antes de começar

Neste codelab, você vai aprender a criar apps da Web com tecnologia de IA que oferecem experiências do usuário atrativas com as Extensões do Firebase.

Pré-requisitos

• Conhecimento sobre Node.js e JavaScript.

Neste curso, você vai aprender a:

• Como usar extensões relacionadas à IA para processar entradas de idioma e vídeo.
• Como usar o Cloud Functions para Firebase para formar um pipeline entre as extensões.
• Como usar JavaScript para acessar a saída produzida pelas extensões.

Pré-requisitos

• Um navegador da sua escolha, como o Google Chrome
• Ambiente de desenvolvimento com um editor de código e um terminal
• Uma Conta do Google para a criação e o gerenciamento do seu projeto do Firebase

2. Analisar apps da Web e os serviços do Firebase deles

Esta seção descreve os apps da Web que você criará neste codelab e qual Firebase vai usar para isso.

App Reviewly

Uma empresa de camisetas está sobrecarregada com longas avaliações de uma das camisetas e não tem certeza da classificação geral dela. O app da Web Reviewly completo resume cada avaliação, fornece uma nota para cada avaliação e usa cada avaliação para inferir uma classificação geral do produto. Os usuários também podem expandir cada avaliação resumida para saber a avaliação original.

App Chatbot

O corpo docente de uma escola está sobrecarregado por perguntas repetitivas sobre tópicos gerais, então eles querem automatizar as respostas. O app Chatbot completo oferece aos estudantes um chatbot de conversação alimentado por um modelo de linguagem grande (LLM) e pode responder a perguntas sobre tópicos gerais. Como o chatbot tem um contexto histórico, as respostas dele podem considerar perguntas anteriores que os estudantes fizeram na mesma conversa.

App Dicas de vídeo

Um departamento governamental quer que seus vídeos forneçam audiodescrições para melhorar a acessibilidade, mas ele tem centenas de vídeos para anotar e precisa de uma abordagem simplificada. O app Dicas de vídeo completo é um protótipo que o departamento analisará para avaliar a eficácia.

Estas são as extensões usadas no app Dicas de vídeo:

• Rotular vídeos com a extensão Cloud Video AI: extraia rótulos de cada vídeo enviado para o Storage.
• Extensão Tarefas de idioma com a API PaLM: resuma os rótulos em uma descrição de texto.
• Conversão de texto em voz: crie uma versão em áudio da descrição do vídeo.

3. Configurar o ambiente de desenvolvimento

Descubra sua versão do Node.js

1. No seu terminal, verifique se você tem o Node.js v20.0.0 ou superior instalado:

   node -v
   

2. Se você não tiver o Node.js v20.0.0 ou superior, faça o download e instale-o.

Faça o download do repositório

1. Se você tiver o git instalado, clone o repositório do GitHub do codelab:

   git clone https://github.com/FirebaseExtended/ai-extensions-codelab.git
   

2. Se o git não estiver instalado, faça o download do repositório do GitHub como um arquivo ZIP.

Revisar a estrutura de pastas

Na máquina local, encontre o repositório clonado e revise a estrutura de pastas. A tabela a seguir contém as pastas e as respectivas descrições:

Cada pasta inclui um arquivo readme.md que oferece um início rápido para executar o respectivo app da Web usando instruções simplificadas. No entanto, se você ainda está começando, conclua este codelab porque ele contém o conjunto mais abrangente de instruções.

Caso não tenha certeza se aplicou corretamente o código conforme as instruções deste codelab, você pode encontrar o código da solução para os respectivos apps nas pastas reviewly-end, chatbot-end e video-hint-end.

instalar a CLI do Firebase

Execute o seguinte comando para verificar se você tem a CLI do Firebase instalada e se ela é a v12.5.4 ou mais recente:

firebase --version

• Se você tiver a CLI do Firebase instalada, mas ela não for v12.5.4 ou mais recente, atualize-a:

  npm update -g firebase-tools
  

• Se você não tiver a CLI do Firebase, faça a instalação:

  npm install -g firebase-tools
  

Se não for possível instalar a CLI do Firebase devido a erros de permissão, consulte a documentação do npm ou use outra opção de instalação.

Fazer login no Firebase

1. No seu terminal, navegue até a pasta ai-extensions-codelab e faça login no Firebase:

   cd ai-extensions-codelab
   firebase login
   

2. Se o terminal informar que você já fez login no Firebase, prossiga para a seção Configurar seu projeto do Firebase deste codelab.
3. Para que o Firebase colete dados, insira Y ou N.
4. No navegador, selecione sua Conta do Google e clique em Permitir.

4. Configurar seu projeto do Firebase

Nesta seção, você vai configurar um projeto do Firebase e associar um app da Web do Firebase a ele. Você também vai ativar os serviços do Firebase usados pelos apps da Web de exemplo.

criar um projeto do Firebase

1. No console do Firebase, clique em Criar projeto.
2. Na caixa de texto Digite o nome do projeto, digite AI Extensions Codelab ou o nome do projeto que você quiser e clique em Continuar.
3. Neste codelab, você não precisa do Google Analytics. Portanto, desative a opção Ativar o Google Analytics para este projeto.
4. Clique em Criar projeto.
5. Aguarde o provisionamento do projeto e clique em Continuar.
6. No projeto do Firebase, acesse Configurações do projeto. Anote o ID do projeto, porque você vai precisar dele mais tarde. Esse identificador exclusivo é como seu projeto é identificado (por exemplo, na CLI do Firebase).

Fazer o download de uma conta de serviço do Firebase

Alguns dos apps da Web que você vai criar neste codelab usam a renderização do lado do servidor com o Next.js.

O SDK Admin do Firebase para Node.js é usado para garantir que as regras de segurança funcionem no código do lado do servidor. Para usar as APIs de administrador do Firebase, você precisa fazer o download de uma conta de serviço do Firebase no Console do Firebase.

1. No console do Firebase, navegue até a página Contas de serviço nas Configurações do projeto.
2. Clique em Gerar nova chave privada > Gerar chave.
3. Após o download do arquivo no seu sistema de arquivos, confira o caminho completo para esse arquivo.
   Por exemplo, se você fez o download do arquivo para a pasta Downloads, o caminho completo pode ser assim: /Users/me/Downloads/my-project-id-firebase-adminsdk-123.json
4. No seu terminal, defina a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS como o caminho da chave privada salva. Em um ambiente Unix, o comando pode ter esta aparência:

   export GOOGLE_APPLICATION_CREDENTIALS="/Users/me/Downloads/my-project-id-firebase-adminsdk-123.json"
   

5. Mantenha esse terminal aberto e use-o no restante deste codelab, já que sua variável de ambiente poderá ser perdida se você iniciar uma nova sessão do terminal.
   Se você abrir uma nova sessão de terminal, será necessário executar novamente o comando anterior.

Fazer upgrade do plano de preços do Firebase

Para usar o Cloud Functions e as Extensões do Firebase, seu projeto do Firebase precisa estar no plano de preços Blaze, ou seja, estar associado a uma conta do Cloud Billing.

• Uma conta do Cloud Billing exige uma forma de pagamento, como cartão de crédito.
• Se você ainda não conhece o Firebase e o Google Cloud, confira se tem qualificação para receber um crédito de US $300 e uma conta de teste gratuito do Cloud Billing.

No entanto, a conclusão deste codelab não gera cobranças.

Para fazer upgrade do seu projeto para o plano Blaze, siga estas etapas:

1. No console do Firebase, selecione Fazer upgrade do seu plano.
2. Na caixa de diálogo, selecione o plano Blaze e siga as instruções na tela para associar seu projeto a uma conta do Cloud Billing.
   Se precisar criar uma conta do Cloud Billing, talvez seja necessário voltar para o upgrade no console do Firebase para concluir o upgrade.

Configurar serviços do Firebase no console do Firebase

Nesta seção, você vai provisionar e configurar vários serviços do Firebase usados pelos apps da Web neste codelab. Nem todos esses serviços são usados em cada app da Web, mas configurar todos eles agora é uma conveniência para trabalhar neste codelab.

Configurar o Authentication

Você usará a autenticação com os apps Chatbot e Dicas de vídeo. No entanto, se você estiver criando um app real, cada app precisa ter o próprio projeto do Firebase.

1. No console do Firebase, navegue até Autenticação.
2. Clique em Começar.
3. Na coluna Outros provedores, clique em Google > Ativar.

4. Na caixa de texto Nome voltado ao público do projeto, digite um nome fácil de lembrar, como My AI Extensions Codelab.
5. No menu suspenso E-mail de suporte do projeto, selecione seu endereço de e-mail.
6. Clique em Salvar.
   

Configurar o Cloud Firestore

Você usará o Firestore com os três apps. No entanto, se você estiver criando um app real, cada app precisa ter o próprio projeto do Firebase.

1. No console do Firebase, navegue até o Firestore.
2. Clique em Criar banco de dados > Iniciar no modo de teste > Próxima.
   Mais adiante neste codelab, você vai adicionar regras de segurança para proteger seus dados. Não distribua ou exponha um aplicativo publicamente sem adicionar regras de segurança ao seu banco de dados.
3. Use o local padrão ou selecione um local de sua escolha.
   No caso de apps reais, escolha um local próximo aos usuários. Não é possível alterar o local depois. Ele também será automaticamente o local do seu bucket padrão do Cloud Storage (próxima etapa).
4. Clique em Concluído.

Configurar o Cloud Storage para Firebase

Você vai usar o Cloud Storage com o app Dicas de vídeo e testar a extensão Conversão de texto em voz (próxima etapa do codelab).

1. No console do Firebase, navegue até Armazenamento.
2. Clique em Começar > Iniciar no modo de teste > Próxima.
   Mais adiante neste codelab, você vai adicionar regras de segurança para proteger seus dados. Não distribua ou exponha um aplicativo publicamente sem adicionar regras de segurança ao bucket do Storage.
3. O local do seu bucket já deve estar selecionado (devido à configuração do Firestore na etapa anterior).
4. Clique em Concluído.

Nas próximas seções deste codelab, você vai instalar extensões e modificar as bases de código de cada app de exemplo neste codelab para colocar três apps da Web diferentes em funcionamento.

5. Configurar a extensão de tarefas de idioma com a API PaLM para o app Reviewly

Instale a extensão Tarefas de idioma com a API PaLM

1. Acesse a extensão Tarefas de idioma com a API PaLM.
2. Clique em Instalar no console do Firebase.
3. Selecione seu projeto do Firebase.
4. Na seção Revisar as APIs ativadas e os recursos criados, clique em Ativar ao lado dos serviços sugeridos:

5. Clique em Próxima > Próxima.
6. Na caixa de texto Caminho da coleção, insira bot.
7. Na caixa de texto Prompt, digite {{ input }}.
8. Na caixa de texto Campos de variáveis, insira input.
9. Na caixa de texto Campo de resposta, digite text.
10. No menu suspenso Local do Cloud Functions, selecione Iowa (us-central1) ou o local selecionado anteriormente para o Firestore e o Cloud Storage.
11. Na lista suspensa Modelo de linguagem, selecione text-bison-001.
12. Não mude os outros valores.
13. Clique em Instalar extensão e aguarde a instalação.

Testar a extensão Tarefas de idioma com a API PaLM

Embora o objetivo deste codelab seja interagir com a extensão Tarefas de idioma com a API PaLM por um app da Web, é útil entender como ela funciona acionando-a usando o Console do Firebase. A extensão é acionada quando um documento do Cloud Firestore é adicionado à coleção bot.

Para saber como a extensão funciona usando o Console do Firebase, siga estas etapas:

1. No console do Firebase, navegue até o Firestore.
2. Na coleção bot, clique em Adicionar documento.
3. Na caixa de texto ID do documento, clique em ID automático.
4. Na caixa de texto Campo, insira input.
5. Na caixa de texto Valor, insira Tell me about the moon.
6. Clique em Salvar e aguarde alguns segundos. Seu documento na coleção bot agora inclui uma resposta à sua consulta.

6. Configurar o app Reviewly para usar o Firebase

Para executar o app Reviewly, é necessário configurar o código do app e a CLI do Firebase para interagir com o projeto do Firebase.

Adicionar a configuração e os serviços do Firebase ao código do app

Para usar o Firebase, a base do código do seu app precisa dos SDKs do Firebase para os serviços que você quer usar e da configuração do Firebase que informa a esses SDKs qual projeto usar.

O app de exemplo deste codelab já inclui todo o código de importação e inicialização necessário para os SDKs (consulte reviewly-start/js/reviews.js), então você não precisa adicioná-los. No entanto, o app de exemplo tem apenas valores de marcador para a configuração do Firebase (consulte reviewly-start/js/firebase-config.js). Portanto, é necessário registrar o app no projeto do Firebase para receber os valores exclusivos de configuração.

1. No Console do Firebase, no projeto do Firebase, navegue até Visão geral do projeto e clique em Web.
   
2. Na caixa de texto Apelido do app, digite um apelido fácil de lembrar, como My Reviewly app.
3. Não marque a caixa de seleção Também configurar o Firebase Hosting para este app. Você vai realizar essas etapas mais adiante neste codelab.
4. Clique em Registrar app.
5. O console exibe um snippet de código para adicionar e inicializar o SDK do Firebase com um objeto de configuração do Firebase específico do app. Copie todas as propriedades no objeto de configuração do Firebase.
6. No editor de código, abra o arquivo reviewly-start/js/firebase-config.js.
7. Substitua os valores de marcador pelos valores que você acabou de copiar. Tudo bem se você tiver propriedades e valores para serviços do Firebase que não são usados no app Reviewly.
8. Salve o arquivo.
9. De volta ao Console do Firebase, clique em Continuar no console.

Configurar o terminal para executar comandos da CLI do Firebase no seu projeto

1. No seu terminal, navegue até a pasta ai-extensions-codelab que você salvou antes.
2. Navegue até a pasta do app da Web reviewly-start:

   cd reviewly-start
   

3. Faça com que a CLI do Firebase execute comandos em um projeto específico do Firebase:

   firebase use YOUR_PROJECT_ID
   

Executar e conferir o app da Web Reviewly

Para executar e conferir o app da Web, siga estas etapas:

1. No seu terminal, instale as dependências e execute o app da Web:

   npm install
   
   # Include the parentheses in the following command.
   (cd functions && npm install)
   
   npm run dev
   

2. No navegador, acesse o URL exibido no terminal. Por exemplo: http://localhost:8080.

A página deve carregar, mas vários recursos estão ausentes. Vamos adicionar isso nas próximas etapas deste codelab.

7. Adicione funcionalidades ao app Reviewly

Na última etapa deste codelab, você executou o app Reviewly localmente, mas ele não tinha muita funcionalidade e ainda não usou a extensão instalada. Nesta etapa do codelab, você vai adicionar essa funcionalidade e usar o app da Web para acionar a extensão.

Implantar regras de segurança

O app de exemplo deste codelab contém conjuntos de regras de segurança para o Firestore e o Cloud Storage para Firebase. Após a implantação dessas regras de segurança no seu projeto do Firebase, os dados no seu banco de dados e no seu bucket ficam mais protegidos contra uso indevido.

Confira essas regras nos arquivos firestore.rules e storage.rules.

1. Para implantar essas regras de segurança, execute este comando no seu terminal:

   firebase deploy --only firestore:rules,storage
   

2. Se aparecer a pergunta "Cloud Storage for Firebase needs an IAM Role to use cross-service rules. Grant the new role?", selecione Sim.

Atualizar o código do app para acionar a extensão

No app Reviewly, uma nova avaliação adicionada ao Firestore aciona a extensão para resumir a avaliação.

1. No editor de código, abra o arquivo functions/add-mock-reviews.js.
2. Substitua a variável reviewWithPrompt pelo código abaixo, que solicita uma avaliação mais curta do modelo de linguagem.

   const reviewWithPrompt = `Here's a user supplied review. Give me a shorter summary of the review, and a rating out of 5, and a flag which indicates if there was a product defect.
   
   Product name: "Blue t-shirt with cat picture". Review: """${review}"""
   
   Craft your response as JSON with properties has_defect, summary and rating. Don't include any extra text.`;
   

3. Depois da variável reviewWithPrompt, substitua a variável reviewDocument pelo código a seguir, que cria um documento de avaliação para ser adicionado ao Firestore.

   const reviewDocument = {
           input: reviewWithPrompt,
           originalReview: review,
           timestamp: Timestamp.now(),
   };
   
   getFirestore().collection(DB_COLLECTION_NAME).add(reviewDocument);
   

4. Salve o arquivo.
5. No arquivo js/reviews.js, após o comentário Insert code below, to import your Firebase Callable Cloud Function, importe a função HTTP chamável do Firebase com o auxiliar httpsCallable:

   const addMockReviews = httpsCallable(functions, "addMockReviews");
   

6. Após o comentário Insert code below, to invoke your Firebase Callable Cloud Function, invoque sua função HTTP chamável do Firebase:

   await addMockReviews();
   

7. Salve o arquivo.

Implantar uma função para adicionar novas avaliações

O app da Web Reviewly usa uma função do Cloud para adicionar as avaliações. No entanto, a função do Cloud não está implantada no momento.

Para implantar a função com a CLI do Firebase, siga estas etapas:

1. No seu terminal, enquanto ainda estiver na pasta reviewly-start, pressione Control+C para interromper o servidor.
2. Implante a função:

   firebase deploy --only functions
   

3. Se você encontrar um erro Permission denied while using the Eventarc Service Agent ou semelhante, aguarde alguns minutos e tente o comando novamente.

Você acabou de implantar sua primeira função personalizada com o Cloud Functions. O console do Firebase oferece um painel em que você pode encontrar todas as funções implantadas no seu projeto.

Execute e abra o app da Web Reviewly novamente (agora com funcionalidade).

Para executar e visualizar o app da Web que agora funciona, siga estas etapas:

1. No terminal, execute o servidor novamente:

   npm run dev
   

2. No navegador, acesse o URL exibido no terminal. Por exemplo: http://localhost:8080.
3. No app, clique em Adicionar avaliações simuladas e aguarde alguns segundos para que algumas avaliações longas apareçam.
   Em segundo plano, o recurso Tarefas de idioma com a API PaLM reage ao novo documento que representa a nova avaliação. O comando que você adicionou anteriormente solicita um resumo mais curto do modelo de linguagem.
4. Para conferir a avaliação completa e o comando usado, clique em uma das avaliações e selecione Mostrar comando do PaLM.

8. Configurar a extensão Chatbot com a API PaLM para o app Chatbot

Instale a extensão Chatbot com API PaLM.

1. Acesse a extensão Chatbot com API PaLM.
2. Clique em Instalar no console do Firebase.
3. Selecione seu projeto do Firebase.
4. Clique em Próxima > Próxima > Próxima até chegar à seção Configurar extensão.
5. Na caixa de texto Caminho da coleção, insira users/{uid}/discussion/{discussionId}/messages.
6. No menu suspenso Local do Cloud Functions, selecione Iowa (us-central1) ou o local selecionado anteriormente para o Firestore e o Cloud Storage.
7. No menu suspenso Modelo de linguagem, selecione chat-bison.
8. Não mude os outros valores.
9. Clique em Instalar extensão e aguarde a instalação.

Testar a extensão Chatbot com API PaLM

Embora o objetivo deste codelab seja interagir com a extensão Chatbot com API PaLM por meio de um app da Web, é útil entender como ela funciona acionando-a usando o Console do Firebase. A extensão é acionada quando um documento do Cloud Firestore é criado na coleção users/{uid}/discussion/{discussionId}/messages.

1. No console do Firebase, navegue até o Firestore.
2. Clique em Iniciar coleção.
   1. Na caixa de texto ID da coleção, digite users e clique em Próxima.
   2. Na caixa de texto ID do documento, clique em ID automático e depois em Salvar.
3. Na coleção users, clique em Iniciar coleção.
   
   1. Na caixa de texto ID da coleção, digite discussion e clique em Próxima.
   2. Na caixa de texto ID do documento, clique em ID automático e depois em Salvar.
4. Na coleção discussion, clique em Iniciar coleção.
   
   1. Na caixa de texto ID da coleção, digite messages e clique em Próxima.
   2. Na caixa de texto ID do documento, clique em ID automático.
   3. Na caixa de texto Campo, insira prompt.
   4. Na caixa de texto Valor, insira Tell me 5 random fruits.
   5. Clique em Salvar e aguarde alguns segundos. A coleção messages agora inclui um documento que contém uma resposta à sua consulta.

5. Na coleção messages, clique em Adicionar documento.
   1. Na caixa de texto ID do documento, clique em ID automático.
   2. Na caixa de texto Campo, insira prompt.
   3. Na caixa de texto Valor, insira And now, vegetables.
   4. Clique em Salvar e aguarde alguns segundos. A coleção messages agora inclui um documento que contém uma resposta à sua consulta.

9. Configurar o app do Chatbot para usar o Firebase

Para executar o app Chatbot, você precisa configurar o código do app e a CLI do Firebase para interagir com o projeto do Firebase.

Adicionar a configuração e os serviços do Firebase ao código do app

Para usar o Firebase, a base do código do seu app precisa dos SDKs do Firebase para os serviços que você quer usar e da configuração do Firebase que informa a esses SDKs qual projeto usar.

O app de exemplo deste codelab já inclui todo o código de importação e inicialização necessário para os SDKs (consulte chatbot-start/lib/firebase/firebase.js), então você não precisa adicioná-los. No entanto, o app de exemplo tem apenas valores de marcador para a configuração do Firebase (consulte chatbot-start/lib/firebase/firebase-config.js). Portanto, é necessário registrar o app no projeto do Firebase para receber os valores exclusivos de configuração.

1. No Console do Firebase, no projeto do Firebase, navegue até Visão geral do projeto e clique em Web (ou clique em Adicionar app) se você já registrou um aplicativo no projeto).
2. Na caixa de texto Apelido do app, digite um apelido fácil de lembrar, como My Chatbot app.
3. Não marque a caixa de seleção Também configurar o Firebase Hosting para este app. Você vai realizar essas etapas mais adiante neste codelab.
4. Clique em Registrar app.
5. O console exibe um snippet de código para adicionar e inicializar o SDK do Firebase com um objeto de configuração do Firebase específico do app. Copie todas as propriedades no objeto de configuração do Firebase.
6. No editor de código, abra o arquivo chatbot-start/lib/firebase/firebase-config.js.
7. Substitua os valores de marcador pelos valores que você acabou de copiar. Tudo bem se você tiver propriedades e valores para serviços do Firebase que não são usados no app Chatbot.
8. Salve o arquivo.
9. De volta ao Console do Firebase, clique em Continuar no console.

Configurar o terminal para executar comandos da CLI do Firebase no seu projeto

1. No terminal, pressione Control+C para impedir que o servidor execute o app da Web anterior.
2. No seu terminal, navegue até a pasta do app da Web chatbot-start:

   cd ../chatbot-start
   

3. Faça com que a CLI do Firebase execute comandos em um projeto específico do Firebase:

   firebase use YOUR_PROJECT_ID
   

Configurar a base de código do seu app para usar o Firebase Hosting com reconhecimento de framework

Este codelab usa frameworks da Web com o Hosting (pré-lançamento) com o app da Web Chatbot.

1. No seu terminal, ative os frameworks da Web com o Firebase Hosting:

   firebase experiments:enable webframeworks
   

2. Inicialize o Firebase Hosting:

   firebase init hosting
   

3. Quando a mensagem Detected an existing Next.js codebase in your current directory, should we use this? aparecer, pressione Y.
4. Quando solicitado com In which region would you like to host server-side content, if applicable?, selecione a região padrão ou o local selecionado anteriormente para o Firestore e o Cloud Storage e pressione Enter (ou return no macOS).
5. Quando a solicitação Set up automatic builds and deploys with GitHub? aparecer, pressione N.

Executar e conferir o app da Web Chatbot

1. No seu terminal, instale as dependências e execute o app da Web:

   npm install
   firebase emulators:start --only hosting
   

2. No seu navegador, navegue até o URL do Hosting hospedado localmente. Na maioria dos casos, é http://localhost:5000/ ou algo semelhante.

A página deve carregar, mas vários recursos estão ausentes. Vamos adicionar isso nas próximas etapas deste codelab.

Resolver problemas ao executar o app da Web

Se aparecer o erro na página da Web que começa assim: Error: Firebase session cookie has incorrect..., você precisa excluir todos os cookies do seu ambiente localhost. Para fazer isso, siga as instruções em excluir cookies | Documentação do DevTools.

10. Adicione funcionalidades ao aplicativo do chatbot

Na última etapa deste codelab, você executou o app Chatbot localmente, mas ele não tinha muita funcionalidade e ainda não usou a extensão instalada. Nesta etapa do codelab, você vai adicionar essa funcionalidade e usar o app da Web para acionar a extensão.

Implantar regras de segurança

O app de exemplo deste codelab contém conjuntos de regras de segurança para o Firestore e o Cloud Storage para Firebase. Após a implantação dessas regras de segurança no seu projeto do Firebase, os dados no seu banco de dados e no seu bucket ficam mais protegidos contra uso indevido.

Confira essas regras nos arquivos firestore.rules e storage.rules.

1. Para implantar essas regras de segurança, execute este comando no seu terminal:

   firebase deploy --only firestore:rules,storage
   

2. Se aparecer a pergunta "Cloud Storage for Firebase needs an IAM Role to use cross-service rules. Grant the new role?", selecione Sim.

Atualizar o código para adicionar mensagens ao Cloud Firestore

No app Chatbot, uma nova mensagem de um usuário é adicionada ao Firestore e aciona a extensão para gerar uma resposta.

1. No editor de código, abra o arquivo lib/firebase/firestore.js.
2. Perto do final do arquivo, encontre a função addNewMessage, que processa a adição de novas mensagens.
   A função já tem as seguintes propriedades de objeto:
   

   Parâmetro	Descrição
   userId	O ID do usuário conectado
   discussionId	O ID da discussão à qual a mensagem foi adicionada
   message	O conteúdo de texto da mensagem
   db	Uma instância de banco de dados do Firestore

   Com essas variáveis prontas, você pode adicionar um documento do Cloud Firestore para representar a nova mensagem.
3. No corpo da função addNewMessage, após o comentário // Insert your code below ⬇️, adicione o seguinte código:

   await addDoc(
           collection(
                   db,
                   "users",
                   userId,
                   "discussion",
                   discussionId,
                   "messages"
           ),
           {
                   prompt: message,
                   createTime: serverTimestamp(),
           }
   );
   
   await updateDoc(doc(db, "users", userId, "discussion", discussionId), {
           latestMessage: message,
           updatedTime: serverTimestamp(),
   });
   

Atualizar o código para criar uma consulta e receber mensagens

1. Ainda no arquivo lib/firebase/firestore.js, localize a função getMessagesQuery, que precisa retornar uma consulta do Cloud Firestore que localiza mensagens armazenadas no caminho da coleção users/{uid}/discussion/{discussionId}/messages.
2. Substitua a função getMessagesQuery inteira por este código:

   function getMessagesQuery(db, userId, discussionId) {
           if (!userId || !discussionId) {
                   return null;
           }
           const messagesRef = collection(
                   db,
                   "users",
                   userId,
                   "discussion",
                   discussionId,
                   "messages"
           );
           return query(messagesRef, orderBy("createTime", "asc"));
   }
   

Atualizar o código para processar documentos de mensagens do Cloud Firestore

1. Ainda no arquivo lib/firebase/firestore.js, localize a função handleMessageDoc, que recebe um documento do Cloud Firestore que representa uma única mensagem.
   Essa função precisa formatar e estruturar os dados de forma que faça sentido para a IU do app Chatbot.
2. Substitua a função handleMessageDoc inteira por este código:

   function handleMessageDoc(doc) {
           const data = doc.data();
           const item = {
                   prompt: data.prompt,
                   response: data.response,
                   id: doc.id,
                   createTime: formatDate(data.createTime.toDate()),
           };
   
           if (data?.status?.completeTime) {
                   item.completeTime = formatDate(data.status.completeTime.toDate());
           }
   
           return item;
   }
   

3. Salve o arquivo.

Execute e abra o app da Web Chatbot novamente (agora com funcionalidade).

Para executar e visualizar o app da Web que agora funciona, siga estas etapas:

1. No navegador, volte para a guia com o app da Web Chatbot e atualize a página.
2. Clique em Sign in with Google.
3. Se necessário, selecione sua Conta do Google.
4. Depois do login, atualize a página.
5. Na caixa de texto Digite sua mensagem, digite uma mensagem, como Tell me about space.
6. Clique em Enviar e aguarde alguns segundos para que o app da Web Chatbot responda.

Outro benefício da extensão Chatbot com API PaLM é o histórico de conversas.

Para acessar um exemplo da capacidade de conversar com o contexto histórico, siga estas etapas:

1. Na caixa de texto Digite sua mensagem, faça uma pergunta, como What are five random fruits?.
2. Na caixa de texto Insira sua mensagem, faça uma pergunta complementar relacionada à pergunta anterior, como And what about vegetables?.

O app da Web Chatbot responde com conhecimento histórico. Mesmo que sua última pergunta não tenha especificado cinco vegetais aleatórios, a extensão Chatbot com API PaLM entende perguntas complementares.

11. Configure a extensão Conversão de texto em voz para o app Video Hint

Instale a extensão Conversão de texto em voz.

1. Navegue até a extensão Conversão de texto em voz.
2. Clique em Instalar no console do Firebase.
3. Selecione seu projeto do Firebase.
4. Clique em Próxima.
5. Na seção Revisar as APIs ativadas e os recursos criados, clique em Ativar ao lado dos serviços sugeridos:

6. Clique em Próxima e selecione Conceder ao lado das permissões sugeridas.

7. Clique em Próxima.
8. Na caixa de texto Caminho da coleção, insira bot.
9. Na caixa de texto Caminho de armazenamento, insira tts.
10. Não altere os outros valores.
11. Clique em Instalar extensão e aguarde a instalação.

Teste a extensão Conversão de texto em voz

Embora o objetivo deste codelab seja interagir com a extensão Conversão texto em voz por meio de um app da Web, é útil entender como a extensão funciona acionando a extensão usando o Console do Firebase. A extensão é acionada quando um documento do Cloud Firestore é criado na coleção bot.

Para saber como a extensão funciona usando o Console do Firebase, siga estas etapas:

1. No Console do Firebase, navegue até Firestore
2. Clique em Iniciar coleção.
3. Na caixa de texto ID da coleção, insira bot.
4. Clique em Próxima.

5. Na caixa de texto ID do documento, clique em ID automático.
6. Na caixa de texto Campo, insira text.
7. Na caixa de texto Valor, insira The quick brown fox jumps over the lazy dog.
8. Clique em Salvar.

Para ver e ouvir o arquivo MP3 que você criou, siga estas etapas:

1. No console do Firebase, navegue até Armazenamento.
2. No painel em que é possível fazer upload de arquivos, anote o nome do bucket após o valor gs://. Esse é o nome do bucket padrão deste projeto. Você vai precisar dele em várias tarefas ao longo deste codelab.

3. No console do Google Cloud, acesse o Cloud Storage.
4. Selecione seu projeto.
   Se ele não aparecer na lista recente de projetos, clique em Selecionar projeto para localizá-lo no seletor.

5. Selecione o bucket padrão do Storage.
6. Navegue até a pasta tts/.
7. Clique no arquivo MP3.
8. No final do arquivo MP3, clique em e observe que o texto é convertido em voz.

12. Configure a extensão "Rotular vídeos com Cloud Video AI" para o app Dica de vídeo.

Instalar a extensão Rotular vídeos com a Cloud Video AI

1. Acesse a extensão Rotular vídeos com a Cloud Video AI.
2. Clique em Instalar no console do Firebase.
3. Selecione seu projeto do Firebase.
4. Clique em Próxima > Próxima > Próxima até chegar à seção Configurar extensão.
5. No menu suspenso Local do Cloud Functions, selecione um local compatível. Pode ser o local mais próximo ou selecionado para o Firestore e o Cloud Storage. Para locais compatíveis, consulte a seção location_id em AnnotateVideoRequest.
6. Na lista suspensa Modelo, selecione Mais recente.
7. No menu suspenso Câmera estática, selecione Não.
8. Não mude os outros valores.
9. Clique em Instalar extensão e aguarde a instalação.

Teste a extensão Rotular vídeos com a Cloud Video AI.

Embora o objetivo deste codelab seja interagir com a extensão Rotular vídeos com a Cloud Video AI por meio de um app da Web, é útil entender como a extensão funciona acionando-a usando o Console do Firebase. A extensão é acionada quando um arquivo de vídeo é enviado para o bucket do Storage.

Para saber como a extensão funciona usando o Console do Firebase, siga estas etapas:

1. Navegue até Armazenamento no projeto do Firebase > Criar pasta.
2. Na caixa de texto Nome da pasta, digite video_annotation_input.

3. Clique em Adicionar pasta.
4. Na pasta video_annotation_input, clique em Fazer upload do arquivo.
5. Na pasta ai-extensions-codelab/video-hint-start/public/videos que você clonou ou fez o download anteriormente, selecione o primeiro arquivo de vídeo.
6. No console do Google Cloud, acesse o Cloud Storage no navegador.
7. Selecione o bucket padrão do Storage, que você anotou anteriormente.
8. Clique na pasta video_annotation_output.
   Caso não encontre a pasta video_annotation_output, aguarde alguns segundos e atualize a página. A API Video Intelligence ainda pode estar processando o vídeo.

9. Observe que existe um arquivo JSON com um nome semelhante ao do arquivo que você enviou por upload anteriormente.
10. Clique em Fazer o download do NOMEDOARQUIVO.
11. Abra o arquivo JSON transferido por download no seu editor de código. Ele contém a saída bruta da API Video Intelligence, que inclui os rótulos detectados do vídeo enviado.

13. Configurar o app Dicas de vídeo para usar o Firebase

Para executar o app Dicas de vídeo, é necessário configurar o código do aplicativo e a CLI do Firebase para interagir com seu projeto.

Adicionar a configuração e os serviços do Firebase ao código do app

Para usar o Firebase, a base do código do seu app precisa dos SDKs do Firebase para os serviços que você quer usar e da configuração do Firebase que informa a esses SDKs qual projeto usar.

O app de exemplo deste codelab já inclui todo o código de importação e inicialização necessário para os SDKs (consulte video-hint-start/lib/firebase/firebase.js), então você não precisa adicioná-los. No entanto, o app de exemplo tem apenas valores de marcador para a configuração do Firebase (consulte video-hint-start/lib/firebase/firebase-config.js). Portanto, é necessário registrar o app no projeto do Firebase para receber os valores exclusivos de configuração.

1. No Console do Firebase, no projeto do Firebase, navegue até Visão geral do projeto e clique em Web (ou clique em Adicionar app) se você já registrou um aplicativo no projeto).
2. Na caixa de texto Apelido do app, digite um apelido fácil de lembrar, como My Video Hint app.
3. Não marque a caixa de seleção Também configurar o Firebase Hosting para este app. Você vai realizar essas etapas mais adiante neste codelab.
4. Clique em Registrar app.
5. O console exibe um snippet de código para adicionar e inicializar o SDK do Firebase com um objeto de configuração do Firebase específico do app. Copie todas as propriedades no objeto de configuração do Firebase.
6. No editor de código, abra o arquivo video-hint-start/lib/firebase/firebase-config.js.
7. Substitua os valores de marcador pelos valores que você acabou de copiar. Tudo bem se você tiver propriedades e valores para serviços do Firebase que não são usados no app Dicas de vídeo.
8. Salve o arquivo.
9. De volta ao Console do Firebase, clique em Continuar no console.

Configurar o terminal para executar comandos da CLI do Firebase no seu projeto

1. No terminal, pressione Control+C para impedir que o servidor execute o app da Web anterior.
2. No seu terminal, navegue até a pasta do app da Web video-hint-start:

   cd ../video-hint-start
   

3. Faça com que a CLI do Firebase execute comandos em um projeto específico do Firebase:

   firebase use YOUR_PROJECT_ID
   

Configurar a base de código do seu app para usar o Firebase Hosting com reconhecimento de framework

Este codelab usa frameworks da Web com o Hosting (pré-lançamento) com o app da Web Dicas de vídeo.

1. No seu terminal, ative os frameworks da Web com o Firebase Hosting:

   firebase experiments:enable webframeworks
   

2. Inicialize o Firebase Hosting:

   firebase init hosting
   

3. Quando a mensagem Detected an existing Next.js codebase in your current directory, should we use this? aparecer, pressione Y.
4. Quando solicitado com In which region would you like to host server-side content, if applicable?, selecione a região padrão ou o local selecionado anteriormente para o Firestore e o Cloud Storage e pressione Enter (ou return no macOS).
5. Quando a solicitação Set up automatic builds and deploys with GitHub? aparecer, pressione N.

Executar e abrir o app da Web Dicas de vídeo

1. No seu terminal, instale as dependências nas pastas video-hint-start e functions e execute o app:

   npm install
   
   # Include the parentheses in the following command.
   (cd functions && npm install)
   
   firebase emulators:start --only hosting
   

2. No seu navegador, navegue até o URL do Hosting hospedado localmente. Na maioria dos casos, é http://localhost:5000/ ou algo semelhante.

A página deve carregar, mas vários recursos estão ausentes. Vamos adicionar isso nas próximas etapas deste codelab.

Resolver problemas ao executar o app da Web

Caso você encontre uma mensagem de erro como Error: The query requires an index. You can create it here: https://console.firebase.google.com no painel Console do DevTools, siga estas etapas:

1. Navegue até o URL fornecido.

2. Clique em Salvar e aguarde até que o status mude de Criando para Ativado.

14. Adicionar funcionalidades ao app Dicas de vídeo

Na última etapa deste codelab, você executou o app Dicas de vídeo localmente, mas ele não tinha muita funcionalidade e ainda não usou a extensão instalada. Nesta etapa do codelab, você vai adicionar essa funcionalidade e usar o app da Web para acionar a extensão.

Implantar regras de segurança

O app de exemplo deste codelab contém conjuntos de regras de segurança para o Firestore e o Cloud Storage para Firebase. Após a implantação dessas regras de segurança no seu projeto do Firebase, os dados no seu banco de dados e no seu bucket ficam mais protegidos contra uso indevido.

Confira essas regras nos arquivos firestore.rules e storage.rules.

1. Para implantar essas regras de segurança, execute este comando no seu terminal:

   firebase deploy --only firestore:rules,storage
   

2. Se aparecer a pergunta "Cloud Storage for Firebase needs an IAM Role to use cross-service rules. Grant the new role?", selecione Sim.

Atualizar o código para combinar as funções

1. No editor de código, expanda a pasta functions.
   Essa pasta contém várias funções, que são combinadas para formar um pipeline de extensão. A tabela a seguir lista e descreve cada função:

   Function	Descrição
   functions/01-handle-video-upload.js	A primeira etapa no pipeline de extensão. Ele processa o arquivo de vídeo enviado pelo usuário.
   functions/02-handle-video-labels.js	A segunda etapa no pipeline de extensão. Ele processa o arquivo de rótulos de vídeo, que foi gerado pela extensão storage-label-videos.
   functions/03-handle-audio-file.js	A terceira etapa no pipeline de extensão. Ele processa o arquivo de áudio transcrito.

   No entanto, você ainda precisa adicionar um arquivo que agrupe essas funções.
2. No arquivo functions/index.js, adicione o seguinte código:

   import { initializeApp } from "firebase-admin/app";
   
   export * from "./01-handle-video-upload.js";
   export * from "./02-handle-video-labels.js";
   export * from "./03-handle-audio-file.js";
   
   initializeApp();
   

Esse código usa módulos JavaScript para importar e exportar as funções do arquivo index.js, criando um local centralizado para todas as funções.

Atualizar o código para processar o envio de vídeos

1. No editor de código, abra o arquivo lib/firebase/storage.js.
2. Localize a função uploadVideo.
   Ela recebe os parâmetros userId, filePath e file. Esses dados são suficientes para fazer upload de um arquivo no Cloud Storage.
3. No corpo da função uploadVideo, adicione o seguinte código:

   const storageRef = ref(storage, `video_annotation_input/${filePath}`);
   
   const uploadTask = uploadBytesResumable(storageRef, file, {
           customMetadata: {
                   uid: userId,
           },
   });
   
   return uploadTask;
   

Implante suas funções

Para implantar as funções com a CLI do Firebase, siga estas etapas:

1. No seu terminal ainda na pasta video-hint-start, pressione Control+C para interromper o processo atual.
2. Implante suas funções:

   firebase deploy --only functions
   

   Se você for solicitado a excluir qualquer função anterior do Cloud, selecione No.
3. Se uma mensagem semelhante a Permission denied while using the Eventarc Service Agent for exibida, aguarde alguns minutos e tente o comando novamente.
4. Depois que o comando for concluído, execute o app localmente novamente:

   firebase emulators:start --only hosting
   

Execute e abra o app da Web Dicas de vídeo novamente (agora com funcionalidade).

Para executar e visualizar o app da Web que agora funciona, siga estas etapas:

1. No navegador, encontre a guia em que você acessou http://localhost:5000.
2. Se necessário, clique em Fazer login com o Google e selecione sua Conta do Google.
3. Clique em Enviar exemplo de vídeo no 1 e aguarde alguns minutos para conferir os resultados do resumo.
4. Se nenhum resultado aparecer após o upload do vídeo, consulte Resolver erros com o Cloud Functions no apêndice deste codelab.

15. Conclusão

Parabéns! Você aprendeu muito neste codelab.

Instalar e configurar Extensões do Firebase

Você usou o console do Firebase para configurar e instalar várias extensões de IA. Usar extensões é conveniente porque você não precisa escrever muito código boilerplate que lida com a autenticação nos serviços do Google Cloud, a leitura e a gravação no Firestore e a interação com os serviços do Google Cloud e as várias nuances envolvidas com essas tarefas.

Trabalho com extensões usando o console do Firebase

Em vez de ir direto ao código, você dedicou tempo para entender como as extensões de IA funcionam, com base em uma entrada que você forneceu pelo console para o Firestore ou o Cloud Storage. Esse tipo de interação pode ser especialmente útil se você precisar depurar a saída da extensão.

Criação de três apps da Web com tecnologia de IA que usam as Extensões do Firebase

Reviewly

No app da Web Reviewly, você usou a extensão Tarefas de idioma com a API PaLM para resumir longas avaliações de um produto de camiseta. Você também solicitou que o modelo de idioma fornecesse uma resposta JSON à sua consulta, em que o JSON fornecesse uma nota e um resumo da avaliação original de formato longo.

Exercício opcional: a empresa de camisetas está satisfeita com as avaliações resumidas, mas pediu um resumo adicional da natureza do defeito. É possível ajustar a solicitação para retornar um resumo do defeito e, em seguida, incluir esse resumo na interface do usuário do app da Web?

Bot de bate-papo

No app da Web Chatbot, você usou a extensão Chatbot com a API PaLM para oferecer ao usuário uma interface de chat interativa, que inclui o contexto histórico nas conversas, onde cada mensagem é armazenada em um documento do Firestore com escopo para determinado usuário.

Exercício opcional: os estudantes ficaram satisfeitos com o chatbot, mas a equipe gostaria de fazer algumas melhorias. Os estudantes devem receber perguntas instigantes após a resposta. Exemplo:

Student asks: What is the ozone?
Response: The ozone is a molecule composed of...How do you think human activities can impact the ozone layer?

Dica: é possível usar uma opção configurável de contexto para fazer isso.

Dicas de vídeo

No app da Web Dicas de vídeo, você usou os recursos Conversão de texto em voz, Tarefas de idioma com a API PaLM e Rotular vídeos com Cloud Video para formar um pipeline de extensão que resulta em um texto e uma descrição de áudio de um vídeo.

Exercício opcional: o departamento governamental achou o protótipo interessante e agora também quer que o usuário clique em um rótulo de texto para ir até o ponto em que o rótulo é detectado no vídeo.

16. Apêndice: solucionar erros com o Cloud Functions

Se o app da Web não estiver funcionando como esperado e você achar que isso pode ter acontecido devido a funções, siga as etapas nesta página de solução de problemas.

Permitir acesso público não autenticado

Se você receber algum erro relacionado a permissões no painel Console do Chrome DevTools, siga estas etapas:

1. Leia a página Visão geral da autenticação | Cloud Run
2. Clique no link para acessar e concluir as tarefas necessárias para Permitir acesso público não autenticado à função.

3. Volte para o app Reviewly. Por exemplo: http://localhost:8080.
4. Clique em Adicionar algumas avaliações simuladas e aguarde alguns segundos.
   • Se as análises aparecerem: você não precisa continuar com as etapas de solução de problemas e pode ir direto para a seção Configurar o app da Web Chatbot deste codelab.
   • Se as avaliações não aparecerem: continue com esta seção de solução de problemas.

Tratar erros de permissão insuficiente

1. No console do Firebase, navegue até Funções.
2. Passe o cursor sobre a função addMockReviews e clique em > Conferir registros.

3. Percorra os registros até encontrar um erro semelhante a um destes:

   Exception from a finished function: Error: 7 PERMISSION_DENIED: Missing or insufficient permissions.
   

   0001-compute@developer.gserviceaccount.com does not have storage.objects.get access to the Google Cloud Storage object. Permission 'storage.objects.get' denied on resource (or it may not exist).
   

4. No console do Google Cloud, acesse a página Permissões do IAM e selecione seu projeto.
5. Na tabela, encontre a coluna Nome.
   Na página IAM e administrador, há uma tabela de usuários e papéis. A coluna "Nome" da tabela descreve a função do usuário ou principal. É possível ter um principal com o nome de Conta de serviço padrão do Compute.

Se a Conta de serviço padrão do Compute aparecer, siga estas etapas:

1. Clique em Editar principal.

2. Continue com a seção Adicionar papéis à conta de serviço padrão do Compute deste codelab.

Se a Conta de serviço padrão do Compute não aparecer, siga estas etapas:

1. Clique em Permitir acesso.
2. Na caixa de texto Novos principais, digite compute.
3. No menu de sugestões automáticas que aparece, selecione Conta de serviço padrão do Compute.

Adicionar papéis à conta de serviço padrão do Compute

Na seção Atribuir papéis da conta de serviço padrão do Compute:

1. Expanda o menu Selecionar um papel.
2. Na caixa de texto Filtro, insira Cloud Datastore User.
3. No menu de sugestões automáticas que é exibido, selecione Usuário do Cloud Datastore.
4. Clique em Adicionar outro papel.
   1. Expanda o menu Selecionar um papel.
   2. Na caixa de texto Filtro, insira Cloud Storage for Firebase Admin.
   3. No menu de sugestões automáticas que é exibido, selecione Administrador do Cloud Storage para Firebase.
5. Clique em Adicionar outro papel.
   1. Expanda o menu Selecionar um papel.
   2. Na caixa de texto Filtro, insira Cloud Storage for Firebase Service Agent.
   3. No menu de sugestões automáticas que é exibido, selecione Agente de serviço do Cloud Storage para Firebase.
6. Clique em Salvar.