Começar a usar a API Gemini nos apps Dart ou Flutter

Neste tutorial, demonstramos como acessar a API Gemini para aplicativos Dart ou Flutter usando o SDK Dart do Google AI. Use esse SDK se você não quiser trabalhar diretamente com APIs REST para acessar modelos do Gemini no 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 embeddings e contagem de tokens), bem como opções para controlar a geração de conteúdo.

Pré-requisitos

Para seguir este tutorial, você precisa estar familiarizado com a criação de aplicativos com o Dart.

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

  • Dart 3.2.0 ou superior

Configurar seu projeto

Antes de chamar a API Gemini, você precisa configurar seu projeto, o que inclui a configuração da chave de API, a adição do SDK às dependências do Pub e a inicialização do 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

Proteja sua chave de API. Recomendamos não incluir a chave de API diretamente no código nem verificar os arquivos que a contêm nos sistemas de controle de versões. Em vez disso, use um armazenamento de secrets para sua chave de API.

Em todos os snippets deste tutorial, presumimos que você esteja acessando sua chave de API como uma variável de ambiente de processo. Se você estiver desenvolvendo um app do Flutter, poderá usar String.fromEnvironment e transmitir --dart-define=API_KEY=$API_KEY para flutter build ou flutter run para compilar com a chave de API, já que o ambiente de processo será diferente ao executar o app.

Instalar o pacote do SDK

Para usar a API Gemini no seu próprio aplicativo, é necessário add o pacote google_generative_ai para seu app Dart ou Flutter:

Dart 

dart pub add google_generative_ai

Flutter 

flutter pub add google_generative_ai

Inicializar o modelo generativo

Antes de fazer qualquer chamada de API, é preciso importar e inicializar o modelo generativo.

import 'package:google_generative_ai/google_generative_ai.dart';

// Access your API key as an environment variable (see "Set up your API key" above)
final apiKey = Platform.environment['API_KEY'];
if (apiKey == null) {
  print('No \$API_KEY environment variable');
  exit(1);
}

final model = GenerativeModel(model: 'MODEL_NAME', apiKey: apiKey);

Ao especificar um modelo, observe o seguinte:

  • Use um modelo específico para seu caso de uso (por exemplo, gemini-pro-vision é 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 o projeto está configurado, é possível explorar o uso da API Gemini para implementar diferentes casos de uso:

Na seção de casos de uso avançados, você encontra informações sobre a API Gemini e embeddings.

Gerar texto com base apenas em entradas de texto

Quando a entrada do comando incluir apenas texto, use o modelo gemini-pro com o método generateContent para gerar a saída de texto:

import 'dart:io';

import 'package:google_generative_ai/google_generative_ai.dart';

void main() async {
  // Access your API key as an environment variable (see "Set up your API key" above)
  final apiKey = Platform.environment['API_KEY'];
  if (apiKey == null) {
    print('No \$API_KEY environment variable');
    exit(1);
  }
  // For text-only input, use the gemini-pro model
  final model = GenerativeModel(model: 'gemini-pro', apiKey: apiKey);
  final content = [Content.text('Write a story about a magic backpack.')];
  final response = await model.generateContent(content);
  print(response.text);
}

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

O Gemini fornece um modelo multimodal (gemini-pro-vision), para que você possa inserir texto e imagens. Revise os requisitos de imagem para entrada.

Quando a entrada da solicitação incluir texto e imagens, use o modelo gemini-pro-vision com o método generateContent para gerar a saída de texto:

import 'dart:io';

import 'package:google_generative_ai/google_generative_ai.dart';

void main() async {
  // Access your API key as an environment variable (see "Set up your API key" above)
  final apiKey = Platform.environment['API_KEY'];
  if (apiKey == null) {
    print('No \$API_KEY environment variable');
    exit(1);
  }
  // For text-and-image input (multimodal), use the gemini-pro-vision model
  final model = GenerativeModel(model: 'gemini-pro-vision', apiKey: apiKey);
  final (firstImage, secondImage) = await (
    File('image0.jpg').readAsBytes(),
    File('image1.jpg').readAsBytes()
  ).wait;
  final prompt = TextPart("What's different between these pictures?");
  final imageParts = [
    DataPart('image/jpeg', firstImage),
    DataPart('image/jpeg', secondImage),
  ];
  final response = await model.generateContent([
    Content.multi([prompt, ...imageParts])
  ]);
  print(response.text);
}

Criar conversas com vários turnos (chat)

Com o Gemini, é possível criar conversas livres em vários turnos. O SDK simplifica o processo gerenciando o estado da conversa. Portanto, ao contrário de generateContent, você não precisa armazenar o histórico da conversa.

Para criar uma conversa de várias interações (como um chat), use o modelo gemini-pro e inicialize o chat chamando startChat(). Em seguida, use sendMessage() para enviar uma nova mensagem de usuário, que também vai anexar a mensagem e a resposta ao histórico de chat.

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

  • user: o papel que fornece as solicitações. 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 'dart:io';

import 'package:google_generative_ai/google_generative_ai.dart';

Future<void> main() async {
  // Access your API key as an environment variable (see "Set up your API key" above)
  final apiKey = Platform.environment['API_KEY'];
  if (apiKey == null) {
    print('No \$API_KEY environment variable');
    exit(1);
  }
  // For text-only input, use the gemini-pro model
  final model = GenerativeModel(
      model: 'gemini-pro',
      apiKey: apiKey,
      generationConfig: GenerationConfig(maxOutputTokens: 100));
  // Initialize the chat
  final chat = model.startChat(history: [
    Content.text('Hello, I have 2 dogs in my house.'),
    Content.model([TextPart('Great to meet you. What would you like to know?')])
  ]);
  var content = Content.text('How many paws are in my house?');
  var response = await chat.sendMessage(content);
  print(response.text);
}

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

Por padrão, o modelo retorna uma resposta depois de concluir todo o processo de geração. Consiga interações mais rápidas não esperando todo o resultado e, em vez disso, use o streaming para lidar com resultados parciais.

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

// ...

final response = model.generateContentStream([
  Content.multi([prompt, ...imageParts])
]);
await for (final chunk in response) {
  print(chunk.text);
}

// ...

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

// Use streaming with text-only input
final response = model.generateContentStream(content);

// Use streaming with multi-turn conversations (like chat)
final response = chat.sendMessageStream(content);

Implemente 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.

Usar embeddings

O embedding é uma técnica usada para representar informações como uma lista de números de ponto flutuante em uma matriz. Com o Gemini, é possível representar textos (palavras, frases e blocos de texto) de forma vetorial, facilitando a comparação e o contraste de embeddings. Por exemplo, dois textos que compartilham um assunto ou sentimento semelhante precisam ter embeddings semelhantes, que podem ser identificados por meio de técnicas de comparação matemática, como semelhança de cosseno.

Use o modelo embedding-001 com o método embedContent ou batchEmbedContent para gerar embeddings. O exemplo a seguir gera um embedding para uma única string:

final model = GenerativeModel(model: 'embedding-001', apiKey: apiKey);
final content = Content.text('The quick brown fox jumps over the lazy dog.');
final result = await model.embedContent(content);
print(result.embedding.values);

Tokens de contagem

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

// For text-only input
final tokenCount = await model.countTokens(Content.text(prompt));
print('Token count: ${tokenCount.totalTokens}');

// For text-and-image input (multimodal)
final tokenCount = await model.countTokens([
  Content.multi([prompt, ...imageParts])
]);
print('Token count: ${tokenCount.totalTokens}');

// For multi-turn conversations (like chat)
final prompt = Content.text(message);
final allContent = [...chat.history, prompt];
final tokenCount = await model.countTokens(allContent);
print('Token count: ${tokenCount.totalTokens}');

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

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

Observe que transmitir generationConfig ou safetySettings para um método de solicitação de modelo (como generateContent) substituirá completamente o objeto de configuração com o mesmo nome transmitido em getGenerativeModel.

Configurar parâmetros do modelo

Cada comando enviado ao modelo inclui valores de parâmetros 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 de modelo. A configuração é mantida durante todo o ciclo de vida da instância de modelo.

final generationConfig = GenerationConfig(
  stopSequences: ["red"],
  maxOutputTokens: 200,
  temperature: 0.9,
  topP: 0.1,
  topK: 16,
);
final model = GenerativeModel(
  model: 'MODEL_NAME',
  apiKey: apiKey,
  generationConfig: generationConfig,
);

Usar configurações de segurança

Você pode usar as configurações de segurança para ajustar a probabilidade de receber respostas que podem 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:

final safetySettings = [
  SafetySetting(HarmCategory.harassment, HarmBlockThreshold.high)
];
final model = GenerativeModel(
  model: 'MODEL_NAME',
  apiKey: apiKey,
  safetySettings: safetySettings,
);

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

final safetySettings = [
  SafetySetting(HarmCategory.harassment, HarmBlockThreshold.high),
  SafetySetting(HarmCategory.hateSpeech, HarmBlockThreshold.high),
];

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 escrita 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 diálogo e restrições de tamanho. Saiba mais sobre os modelos disponíveis do Gemini.

  • Gemini oferece opções para solicitar aumentos no limite de taxa. O limite de taxa para os modelos Genmini Pro é de 60 solicitações por minuto (RPM).