GSP1209

Visão geral

O SDK da IA generativa do Google oferece uma interface unificada para os serviços de API da IA generativa do Google. O SDK simplifica o processo de integração das capacidades de IA generativa em aplicativos e serviços, permitindo que os desenvolvedores usem os modelos avançados de IA do Google em várias tarefas. Neste laboratório, você vai conhecer o SDK da IA generativa, aprender a se conectar a serviços de IA, enviar comandos diversos e ajustar as respostas do Gemini. Você também vai ter experiência prática com técnicas mais avançadas para aprender a usar o poder da IA generativa nos seus próprios projetos.

Objetivos

Neste laboratório, você vai aprender a usar o SDK da IA generativa do Google para Python para interagir com os serviços e modelos de IA generativa do Google, incluindo o Gemini. Vamos abordar estes tópicos:

• Como instalar o SDK da IA generativa.
• Como se conectar a um serviço de API.
• Como enviar comandos de texto e multimodais.
• Como definir instruções do sistema.
• Como configurar parâmetros de modelo e filtros de segurança.
• Como gerenciar interações de modelos (chat multiturno, streaming de conteúdo, solicitações assíncronas).
• Como usar recursos avançados (contagem de tokens, armazenamento em cache de contexto, chamada de função, predição em lote e embeddings de texto).

Pré-requisitos

Antes de fazer este laboratório, você precisa saber os seguintes conceitos:

• Noção básica de programação em Python.
• Conceitos gerais sobre APIs.
• Executar códigos Python em um notebook do Jupyter no Vertex AI Workbench.

Configuração e requisitos

Antes de clicar no botão Começar o Laboratório

Leia estas instruções. Os laboratórios são cronometrados e não podem ser pausados. O timer é ativado quando você clica em Iniciar laboratório e mostra por quanto tempo os recursos do Google Cloud vão ficar disponíveis.

Este laboratório prático permite que você realize as atividades em um ambiente real de nuvem, e não em uma simulação ou demonstração. Você vai receber novas credenciais temporárias para fazer login e acessar o Google Cloud durante o laboratório.

Confira os requisitos para concluir o laboratório:

• Acesso a um navegador de Internet padrão (recomendamos o Chrome).

Observação: para executar este laboratório, use o modo de navegação anônima (recomendado) ou uma janela anônima do navegador. Isso evita conflitos entre sua conta pessoal e de estudante, o que poderia causar cobranças extras na sua conta pessoal.

• Tempo para concluir o laboratório: não se esqueça que, depois de começar, não será possível pausar o laboratório.

Observação: use apenas a conta de estudante neste laboratório. Se usar outra conta do Google Cloud, você poderá receber cobranças nela.

Como iniciar seu laboratório e fazer login no console do Google Cloud

1. Clique no botão Começar o laboratório. Se for preciso pagar por ele, uma caixa de diálogo vai aparecer para você selecionar a forma de pagamento. No painel Detalhes do Laboratório, à esquerda, você vai encontrar o seguinte:

   • O botão Abrir Console do Google Cloud
   • O tempo restante
   • As credenciais temporárias que você vai usar neste laboratório
   • Outras informações, se forem necessárias

2. Se você estiver usando o navegador Chrome, clique em Abrir console do Google Cloud ou clique com o botão direito do mouse e selecione Abrir link em uma janela anônima.

   O laboratório ativa os recursos e depois abre a página Fazer Login em outra guia.

   Dica: coloque as guias em janelas separadas lado a lado.

   Observação: se aparecer a caixa de diálogo Escolher uma conta, clique em Usar outra conta.

3. Se necessário, copie o Nome de usuário abaixo e cole na caixa de diálogo Fazer login.

   {{{user_0.username | "Username"}}}

   Você também encontra o nome de usuário no painel Detalhes do Laboratório.

4. Clique em Próxima.

5. Copie a Senha abaixo e cole na caixa de diálogo de Olá.

   {{{user_0.password | "Password"}}}

   Você também encontra a senha no painel Detalhes do Laboratório.

6. Clique em Próxima.

   Importante: você precisa usar as credenciais fornecidas no laboratório, e não as da sua conta do Google Cloud. Observação: se você usar sua própria conta do Google Cloud neste laboratório, é possível que receba cobranças adicionais.

7. Acesse as próximas páginas:

   • Aceite os Termos e Condições.
   • Não adicione opções de recuperação nem autenticação de dois fatores (porque essa é uma conta temporária).
   • Não se inscreva em testes gratuitos.

Depois de alguns instantes, o console do Google Cloud será aberto nesta guia.

Observação: para acessar os produtos e serviços do Google Cloud, clique no Menu de navegação ou digite o nome do serviço ou produto no campo Pesquisar.

Tarefa 1: abrir o notebook no Vertex AI Workbench

1. No menu de navegação () do console do Google Cloud, clique em Vertex AI > Workbench.

2. Ache a instância e clique no botão Abrir o JupyterLab.

A interface do JupyterLab para sua instância do Workbench é aberta em uma nova guia do navegador.

Tarefa 2: configurar o notebook

Abra seu arquivo do notebook, importe as bibliotecas e escolha o modelo.

1. Abra o arquivo .

2. Na caixa de diálogo Selecionar Kernel, escolha Python 3 na lista de kernels disponíveis.

3. Confira estas seções do notebook:

   • Comece agora
   • Use o SDK da IA generativa do Google
   • Conecte-se a um serviço de API de IA generativa

Para ID do projeto, use , e em Local, use .

Observação: pule as células do notebook que tenham a indicação Somente Colab. Se você receber uma resposta 429 de uma das execuções de células do notebook, aguarde 1 minuto antes de executar a célula novamente para prosseguir.

Clique em Verificar meu progresso para conferir o objetivo. Importar bibliotecas e configurar o notebook

Tarefa 3: interagir com o modelo

Para mais informações sobre todos os modelos de IA e APIs na Vertex AI, consulte Modelos do Google e Model Garden.

Escolher um modelo

• Execute a seção Escolher um modelo do notebook.

Enviar comandos de texto

Use o método generate_content para gerar respostas aos comandos. É possível passar texto para generate_content e usar a propriedade .text para receber o conteúdo de texto da resposta.

• Execute a seção Enviar comandos de texto do notebook.

Enviar comandos multimodais

É possível incluir texto, documentos em PDF, imagens, áudio e vídeo nos comandos e receber respostas de texto ou código.

Também é possível passar o URL do arquivo em Part.from_uri na solicitação ao modelo diretamente.

• Execute a seção Enviar comandos multimodais do notebook.

Definir as instruções do sistema

As instruções do sistema permitem controlar o comportamento do modelo. Defina a instrução do sistema para dar ao modelo mais contexto para entender a tarefa, fornecer respostas mais personalizadas e aderir a diretrizes sobre a interação do usuário.

• Execute a seção Definir instrução do sistema do notebook.

Clique em Verificar meu progresso para conferir o objetivo. Interagir com o modelo

Tarefa 4: configurar e controlar o modelo

Configurar parâmetros do modelo

É possível incluir valores de parâmetro em cada chamada enviada a um modelo para controlar como ele gera uma resposta. Para saber mais, consulte Como testar valores de parâmetro.

• Execute a seção Configurar parâmetros do modelo do notebook.

Configurar filtros de segurança

É possível ajustar os filtros de segurança da API Gemini em diferentes categorias para restringir ou permitir determinados tipos de conteúdo. Use esses filtros para ajustar o que for necessário conforme seu caso de uso. Consulte a página Configurar filtros de segurança para saber mais.

Quando você faz uma solicitação ao modelo, o conteúdo é analisado e recebe uma classificação de segurança. Para verificar as classificações de segurança do conteúdo gerado, basta imprimir as respostas do modelo, como neste exemplo:

• Execute a seção Configurar filtros de segurança do notebook.

Iniciar um chat multiturno

A API Gemini permite conversas de formato livre em vários turnos.

• Execute a seção Iniciar um chat multiturno do notebook.

Controlar a saída gerada

O recurso de geração controlada na API Gemini permite que você restrinja a resposta do modelo a um formato estruturado. Defina os esquemas como modelos Pydantic ou uma string JSON.

Também é possível definir um esquema de resposta em um dicionário do Python. Use apenas os campos abaixo. Todos os outros campos serão ignorados.

• enum
• items
• maxItems
• nullable
• properties
• required

Neste exemplo, você instrui o modelo a analisar dados de avaliações de produtos, extrair entidades principais, realizar a classificação de sentimento (várias opções), fornecer explicações adicionais e gerar os resultados no formato JSON.

• Execute a seção Controlar a saída gerada do notebook.

Clique em Verificar meu progresso para conferir o objetivo. Configurar e controlar o modelo

Tarefa 5: gerenciar a interação do modelo

Gerar stream de conteúdo

Por padrão, o modelo retorna uma resposta depois de concluir todo o processo de geração. Também é possível usar o método generate_content_stream para transmitir a resposta conforme ela é gerada. O modelo retorna partes da resposta à medida que elas são geradas.

• Execute a seção Gerar stream de conteúdo do notebook.

Enviar solicitações assíncronas

É possível enviar solicitações assíncronas usando o módulo client.aio. Esse módulo expõe todos os métodos assíncronos análogos disponíveis em client.

Por exemplo, client.aio.models.generate_content é a versão assíncrona de client.models.generate_content.

• Execute a seção Enviar solicitações assíncronas do notebook.

Contar e calcular tokens

Use o método count_tokens para calcular o número de tokens de entrada antes de enviar uma solicitação à API Gemini. Consulte a página Listar e contar tokens para saber mais.

Contar tokens

• Execute a seção Contar tokens do notebook.

Calcular tokens

• Execute a seção Calcular tokens do notebook.

Clique em Verificar meu progresso para conferir o objetivo. Gerenciar a interação do modelo

Tarefa 6: recursos avançados

Chamadas de função

A chamada de função permite que você forneça um conjunto de ferramentas que o modelo pode usar para responder ao comando do usuário. Você cria uma descrição de uma função no código e transmite essa descrição para um modelo de linguagem em uma solicitação. A resposta do modelo inclui o nome de uma função que corresponde à descrição e os argumentos para chamá-la.

Para mais exemplos de chamadas de função, consulte este notebook.

• Execute a seção Chamada de função do notebook.

Clique em Verificar meu progresso para conferir o objetivo. Chamadas de função

Usar o armazenamento em cache de contexto

O armazenamento em cache de contexto permite armazenar tokens de entrada usados com frequência em um cache dedicado e consultá-los para solicitações subsequentes. Isso elimina a necessidade de passar repetidamente o mesmo conjunto de tokens para um modelo.

Observação: o armazenamento em cache de contexto só está disponível para modelos estáveis com versões fixas (por exemplo, gemini-2.0-flash-001). É necessário incluir o sufixo da versão (por exemplo, -001).

Criar um cache

• Execute a seção Criar um cache do notebook.

Usar um cache

• Execute a seção Usar um cache do notebook.

Excluir um cache

• Execute a seção Excluir um cache do notebook.

Clique em Verificar meu progresso para conferir o objetivo. Usar o armazenamento em cache de contexto

Predição em lote

Ao contrário de receber respostas on-line (síncronas), em que ficamos limitados a uma solicitação de entrada por vez, as previsões em lote da API Gemini na Vertex AI permitem enviar um grande número de solicitações ao Gemini em uma única solicitação em lote. Depois, as respostas do modelo são preenchidas de maneira assíncrona no local de saída do armazenamento no Cloud Storage ou no BigQuery.

As previsões em lote geralmente são mais eficientes e econômicas do que as previsões on-line ao processar um grande número de entradas que não são sensíveis à latência.

Preparar entradas em lote

A entrada de solicitações em lote especifica os itens que serão enviados ao seu modelo para previsão.

As solicitações em lote para o Gemini aceitam origens de armazenamento do BigQuery e do Cloud Storage. Saiba mais sobre os formatos de entrada em lote na página Geração de texto em lote.

Este laboratório usa o Cloud Storage como exemplo. Os requisitos para a entrada do Cloud Storage são:

• Formato do arquivo: linhas JSON (JSONL)
• Localizado em us-central1
• Permissões de leitura adequadas para a conta de serviço

Cada solicitação que você envia a um modelo pode incluir parâmetros que controlam como o modelo gera uma resposta. Saiba mais sobre os parâmetros do Gemini na página Testar valores de parâmetro.

Este é um dos exemplos de solicitações no arquivo JSONL de entrada batch_requests_for_multimodal_input_2.jsonl:

{"request":{"contents": [{"role": "user", "parts": [{"text": "List objects in this image."}, {"file_data": {"file_uri": "gs://cloud-samples-data/generative-ai/image/office-desk.jpeg", "mime_type": "image/jpeg"}}]}],"generationConfig":{"temperature": 0.4}}}

• Execute a seção Preparar entradas em lote do notebook.

Preparar o local de saída em lote

Quando uma tarefa de predição em lote é concluída, a saída é armazenada no local especificado na sua solicitação.

• O local é um prefixo de URI do Cloud Storage ou do BigQuery, por exemplo: gs://path/to/output/data ou bq://projectId.bqDatasetId.

• Se não for especificado, gs://STAGING_BUCKET/gen-ai-batch-prediction será usado para a origem do Cloud Storage e bq://PROJECT_ID.gen_ai_batch_prediction.predictions_TIMESTAMP será usado para a origem do BigQuery.

Este laboratório usa um bucket do Cloud Storage como exemplo de local de saída.

É possível especificar o URI do bucket do Cloud Storage em BUCKET_URI. Se não for especificado, um novo bucket do Cloud Storage será criado no formato gs://PROJECT_ID-TIMESTAMP.

• Execute a seção Preparar o local de saída em lote do notebook.

Enviar uma solicitação de predição em lote

Para fazer uma solicitação de predição em lote, especifique um ID de modelo de origem, uma origem de entrada e um local de saída em que a Vertex AI armazena os resultados dessa predição.

Para mais informações, consulte a página da API de predição em lote. Também é possível verificar o status no console em https://console.cloud.google.com/vertex-ai/batch-predictions

• Execute a seção Enviar uma solicitação de predição em lote do notebook.

Observação: a predição em lote pode levar alguns minutos para ser concluída.

Recuperar resultados de predição em lote

Quando uma tarefa de predição em lote é concluída, a saída da predição é armazenada no local especificado na sua solicitação. Ela também está disponível em batch_job.dest.bigquery_uri ou batch_job.dest.gcs_uri.

Exemplo de saída:

{"status": "", "processed_time": "2024-11-13T14:04:28.376+00:00", "request": {"contents": [{"parts": [{"file_data": null, "text": "List objects in this image."}, {"file_data": {"file_uri": "gs://cloud-samples-data/generative-ai/image/gardening-tools.jpeg", "mime_type": "image/jpeg"}, "text": null}], "role": "user"}], "generationConfig": {"temperature": 0.4}}, "response": {"candidates": [{"avgLogprobs": -0.10394711927934126, "content": {"parts": [{"text": "Here's a list of the objects in the image:\n\n* **Watering can:** A green plastic watering can with a white rose head.\n* **Plant:** A small plant (possibly oregano) in a terracotta pot.\n* **Terracotta pots:** Two terracotta pots, one containing the plant and another empty, stacked on top of each other.\n* **Gardening gloves:** A pair of striped gardening gloves.\n* **Gardening tools:** A small trowel and a hand cultivator (hoe). Both are green with black handles."}], "role": "model"}, "finishReason": "STOP"}], "modelVersion": "gemini-2.0-flash-001@default", "usageMetadata": {"candidatesTokenCount": 110, "promptTokenCount": 264, "totalTokenCount": 374}}}

• Execute a seção Recuperar resultados de predição em lote do notebook.

Clique em Verificar meu progresso para conferir o objetivo. Recuperar resultados de predição em lote

Acessar embeddings de texto

É possível usar o método embed_content para gerar embeddings de texto para um snippet. Todos os modelos produzem uma saída com 768 dimensões por padrão. No entanto, alguns modelos dão aos usuários a opção de escolher uma dimensionalidade de saída entre 1 e 768. Consulte a API de embeddings de texto da Vertex AI para mais detalhes.

• Execute a seção Recuperar embeddings de texto do notebook.

Clique em Verificar meu progresso para conferir o objetivo. Acessar embeddings de texto

Parabéns!

Parabéns! Você conheceu o SDK da IA generativa do Google, aprendeu a se conectar a serviços de IA, enviar comandos e ajustar as respostas do modelo Gemini. Também teve experiência prática com técnicas mais avançadas, como gerenciar interações, usar o armazenamento em cache de contexto e até mesmo trabalhar com embeddings. Agora você já pode aproveitar o potencial da IA generativa nos seus próprios projetos.

Próximas etapas / Saiba mais

Confira os recursos a seguir para saber mais sobre o Gemini:

• Visão geral do Gemini
• IA generativa na documentação da Vertex AI
• IA generativa no YouTube
• Confira o manual da Vertex AI para acessar uma galeria selecionada e pesquisável de notebooks da IA generativa.
• Conheça outros notebooks e exemplos no Repositório da IA generativa do Google Cloud (em inglês).

Treinamento e certificação do Google Cloud

Esses treinamentos ajudam você a aproveitar as tecnologias do Google Cloud ao máximo. Nossas aulas incluem habilidades técnicas e práticas recomendadas para ajudar você a alcançar rapidamente o nível esperado e continuar sua jornada de aprendizado. Oferecemos treinamentos que vão do nível básico ao avançado, com opções de aulas virtuais, sob demanda e por meio de transmissões ao vivo para que você possa encaixá-las na correria do seu dia a dia. As certificações validam sua experiência e comprovam suas habilidades com as tecnologias do Google Cloud.

Manual atualizado em 5 de maio de 2025

Laboratório testado em 5 de maio de 2025

Copyright 2025 Google LLC. Todos os direitos reservados. Google e o logotipo do Google são marcas registradas da Google LLC. Todos os outros nomes de produtos e empresas podem ser marcas registradas das respectivas empresas a que estão associados.