Tutorial: primeiros passos com a API Gemini


Neste tutorial, demonstramos como acessar a API Gemini diretamente do seu web app usando o SDK da IA do Google para JavaScript. Use esse SDK se não quiser trabalhar diretamente com APIs REST ou código do lado do servidor (como Node.js) para acessar modelos do Gemini no seu web app.

Neste tutorial, você aprenderá a fazer o seguinte:

Além disso, este tutorial contém seções sobre casos de uso avançados (como contagem de tokens) e opções para controlar a geração de conteúdo.

Pré-requisitos

Neste tutorial, presumimos que você esteja familiarizado com o uso do JavaScript para desenvolver apps da Web. Este guia é independente de framework.

Para concluir este tutorial, verifique se o ambiente de desenvolvimento atende aos seguintes requisitos:

  • Node.js (opcional)
  • Navegador da Web moderno

Configurar seu projeto

Antes de chamar a API Gemini, você precisa configurar seu projeto, o que inclui receber uma chave de API, importar o SDK e inicializar o modelo.

Configurar sua chave de API

Para usar a API Gemini, você precisa de uma chave de API. Se você ainda não tiver uma, crie uma chave no Google AI Studio.

Gerar uma chave de API

Proteger sua chave de API

É altamente recomendável não fazer a verificação de uma chave de API no sistema de controle de versões. Em vez disso, transmita a chave de API ao app antes de inicializar o modelo.

Em todos os snippets deste tutorial, supomos que você esteja acessando sua chave de API como uma constante global.

Importar o SDK e inicializar o modelo generativo

Antes de fazer chamadas de API, é preciso importar o SDK e inicializar o modelo generativo.

<html>
  <body>
    <!-- ... Your HTML and CSS -->

    <script type="importmap">
      {
        "imports": {
          "@google/generative-ai": "https://esm.run/@google/generative-ai"
        }
      }
    </script>
    <script type="module">
      import { GoogleGenerativeAI } from "@google/generative-ai";

      // Fetch your API_KEY
      const API_KEY = "...";
      // Reminder: This should only be for local testing

      // Access your API key (see "Set up your API key" above)
      const genAI = new GoogleGenerativeAI(API_KEY);

      // ...

      // The Gemini 1.5 models are versatile and work with most use cases
      const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash"});

      // ...
    </script>
  </body>
</html>

Ao especificar um modelo, observe o seguinte:

  • Use um modelo específico para seu caso de uso (por exemplo, gemini-1.5-flash é para entrada multimodal). Neste guia, as instruções para cada implementação listam o modelo recomendado para cada caso de uso.

Implemente casos de uso comuns

Agora que seu projeto está configurado, é possível usar a API Gemini para implementar diferentes casos de uso:

Gerar texto com base em uma entrada somente de texto

Quando a entrada do comando incluir apenas texto, use um modelo Gemini 1.5 ou Gemini 1.0 Pro com generateContent para gerar a saída de texto:

import { GoogleGenerativeAI } from "@google/generative-ai";

// Access your API key (see "Set up your API key" above)
const genAI = new GoogleGenerativeAI(API_KEY);

async function run() {
  // The Gemini 1.5 models are versatile and work with both text-only and multimodal prompts
  const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash"});

  const prompt = "Write a story about a magic backpack."

  const result = await model.generateContent(prompt);
  const response = await result.response;
  const text = response.text();
  console.log(text);
}

run();

Gerar texto com base em entradas de texto e imagem (multimodal)

O Gemini oferece vários modelos que podem processar entrada multimodal (modelos do Gemini 1.5) para que você possa inserir texto e imagens. Confira os requisitos de imagem para comandos.

Quando a entrada do comando incluir texto e imagens, use um modelo Gemini 1.5 com o método generateContent para gerar a saída de texto:

import { GoogleGenerativeAI } from "@google/generative-ai";

// Access your API key (see "Set up your API key" above)
const genAI = new GoogleGenerativeAI(API_KEY);

// Converts a File object to a GoogleGenerativeAI.Part object.
async function fileToGenerativePart(file) {
  const base64EncodedDataPromise = new Promise((resolve) => {
    const reader = new FileReader();
    reader.onloadend = () => resolve(reader.result.split(',')[1]);
    reader.readAsDataURL(file);
  });
  return {
    inlineData: { data: await base64EncodedDataPromise, mimeType: file.type },
  };
}

async function run() {
  // The Gemini 1.5 models are versatile and work with both text-only and multimodal prompts
  const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash" });

  const prompt = "What's different between these pictures?";

  const fileInputEl = document.querySelector("input[type=file]");
  const imageParts = await Promise.all(
    [...fileInputEl.files].map(fileToGenerativePart)
  );

  const result = await model.generateContent([prompt, ...imageParts]);
  const response = await result.response;
  const text = response.text();
  console.log(text);
}

run();

Criar conversas de várias interações (chat)

Com o Gemini, você pode criar conversas em formato livre em vários turnos. O SDK simplifica o processo gerenciando o estado da conversa. Portanto, diferentemente de generateContent, não é necessário armazenar o histórico de conversas.

Para criar uma conversa de vários turnos (como um chat), use um modelo Gemini 1.5 ou Gemini 1.0 Pro e inicialize a conversa chamando startChat(). Em seguida, use sendMessage() para enviar uma nova mensagem de usuário, que também anexará a mensagem e a resposta ao histórico de chat.

Há duas opções possíveis para role associados ao conteúdo em uma conversa:

  • user: o papel que fornece os comandos. Esse valor é o padrão para chamadas sendMessage, e a função vai gerar uma exceção se um papel diferente for transmitido.

  • model: o papel que fornece as respostas. Esse papel pode ser usado ao chamar startChat() com history.

import { GoogleGenerativeAI } from "@google/generative-ai";

// Access your API key (see "Set up your API key" above)
const genAI = new GoogleGenerativeAI(API_KEY);

async function run() {
  // The Gemini 1.5 models are versatile and work with multi-turn conversations (like chat)
  const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash"});

  const chat = model.startChat({
    history: [
      {
        role: "user",
        parts: [{ text: "Hello, I have 2 dogs in my house." }],
      },
      {
        role: "model",
        parts: [{ text: "Great to meet you. What would you like to know?" }],
      },
    ],
    generationConfig: {
      maxOutputTokens: 100,
    },
  });

  const msg = "How many paws are in my house?";

  const result = await chat.sendMessage(msg);
  const response = await result.response;
  const text = response.text();
  console.log(text);
}

run();

Use o streaming para interações mais rápidas

Por padrão, o modelo retorna uma resposta após concluir todo o processo de geração. Para ter interações mais rápidas, não espere o resultado todo e, em vez disso, use o streaming para processar resultados parciais.

O exemplo a seguir mostra como implementar o streaming com o método generateContentStream para gerar texto com base em um prompt de entrada de texto e imagem.

// ...

const result = await model.generateContentStream([prompt, ...imageParts]);

let text = '';
for await (const chunk of result.stream) {
  const chunkText = chunk.text();
  console.log(chunkText);
  text += chunkText;
}

// ...

Você pode usar uma abordagem semelhante para casos de uso de entrada somente de texto e chat.

// Use streaming with text-only input
const result = await model.generateContentStream(prompt);

Consulte o exemplo de chat acima para saber como instanciar um chat.

// Use streaming with multi-turn conversations (like chat)
const result = await chat.sendMessageStream(msg);

Implementar casos de uso avançados

Os casos de uso comuns descritos na seção anterior deste tutorial ajudam você a se familiarizar com o uso da API Gemini. Esta seção descreve alguns casos de uso que podem ser considerados mais avançados.

Chamadas de função

A chamada de função facilita a geração de saídas de dados estruturados de modelos generativos. Depois, use essas saídas para chamar outras APIs e retornar os dados de resposta relevantes ao modelo. Em outras palavras, a chamada de função ajuda você a conectar modelos generativos a sistemas externos, para que o conteúdo gerado inclua as informações mais atualizadas e precisas. Saiba mais no tutorial sobre chamada de função.

Contar tokens

Ao usar prompts longos, pode ser útil contar os tokens antes de enviar qualquer conteúdo para o modelo. Os exemplos abaixo mostram como usar countTokens() em vários casos de uso:

// For text-only input
const { totalTokens } = await model.countTokens(prompt);

// For text-and-image input (multimodal)
const { totalTokens } = await model.countTokens([prompt, ...imageParts]);

// For multi-turn conversations (like chat)
const history = await chat.getHistory();
const msgContent = { role: "user", parts: [{ text: msg }] };
const contents = [...history, msgContent];
const { totalTokens } = await model.countTokens({ contents });

Opções para controlar a geração de conteúdo

É possível controlar a geração de conteúdo definindo parâmetros do modelo e usando as configurações de segurança.

Configurar parâmetros do modelo

Cada comando que você envia ao modelo inclui valores de parâmetro que controlam como o modelo gera uma resposta. O modelo pode gerar diferentes resultados para diferentes valores de parâmetros. Saiba mais sobre os parâmetros do modelo. A configuração é mantida durante o ciclo de vida da instância do modelo.

const generationConfig = {
  stopSequences: ["red"],
  maxOutputTokens: 200,
  temperature: 0.9,
  topP: 0.1,
  topK: 16,
};

// The Gemini 1.5 models are versatile and work with most use cases
const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash",  generationConfig });

Usar as configurações de segurança

Use as configurações de segurança para ajustar a probabilidade de receber respostas que possam ser consideradas prejudiciais. Por padrão, as configurações de segurança bloqueiam conteúdo com probabilidade média e/ou alta de não ser seguro em todas as dimensões. Saiba mais sobre as Configurações de segurança.

Veja como definir uma configuração de segurança:

import { HarmBlockThreshold, HarmCategory } from "@google/generative-ai";

// ...

const safetySettings = [
  {
    category: HarmCategory.HARM_CATEGORY_HARASSMENT,
    threshold: HarmBlockThreshold.BLOCK_ONLY_HIGH,
  },
];

// The Gemini 1.5 models are versatile and work with most use cases
const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash", safetySettings });

Também é possível definir mais de uma configuração de segurança:

const safetySettings = [
  {
    category: HarmCategory.HARM_CATEGORY_HARASSMENT,
    threshold: HarmBlockThreshold.BLOCK_ONLY_HIGH,
  },
  {
    category: HarmCategory.HARM_CATEGORY_HATE_SPEECH,
    threshold: HarmBlockThreshold.BLOCK_MEDIUM_AND_ABOVE,
  },
];

A seguir

  • Design de prompt é o processo de criação de prompts que extraem a resposta desejada dos modelos de linguagem. Escrever solicitações bem estruturadas é uma parte essencial para garantir respostas precisas e de alta qualidade de um modelo de linguagem. Saiba mais sobre as práticas recomendadas para a criação de comandos.

  • O Gemini oferece diversas variações de modelo para atender às necessidades de diferentes casos de uso, como tipos de entrada e complexidade, implementações para chat ou outras tarefas de linguagem de caixas de diálogo e restrições de tamanho. Saiba mais sobre os modelos do Gemini disponíveis.