Tutoriel: Premiers pas avec l'API Gemini


Ce tutoriel explique comment accéder à l'API Gemini pour votre application Dart ou Flutter à l'aide du SDK Dart de Google AI. Vous pouvez utiliser ce SDK si vous ne souhaitez pas travailler directement avec les API REST pour accéder aux modèles Gemini dans votre application.

Dans ce tutoriel, vous allez apprendre à effectuer les opérations suivantes:

En outre, ce tutoriel contient des sections sur des cas d'utilisation avancés (comme les représentations vectorielles continues et le compte des jetons) ainsi que des options pour contrôler la génération de contenu.

Conditions préalables

Dans ce tutoriel, nous partons du principe que vous savez comment créer des applications avec Dart.

Pour suivre ce tutoriel, assurez-vous que votre environnement de développement répond aux exigences suivantes:

  • Dart 3.2.0+

Configurer votre projet

Avant d'appeler l'API Gemini, vous devez configurer votre projet, ce qui implique de configurer votre clé API, d'ajouter le SDK à vos dépendances Pub/Sub et d'initialiser le modèle.

Configurer votre clé API

Pour utiliser l'API Gemini, vous avez besoin d'une clé API. Si ce n'est pas déjà fait, créez une clé dans Google AI Studio.

Obtenir une clé API

Sécuriser votre clé API

Sécurisez votre clé API. Nous vous recommandons vivement de ne pas inclure la clé API directement dans votre code ni de vérifier les fichiers contenant la clé dans les systèmes de contrôle des versions. Vous devez plutôt utiliser un magasin de secrets pour votre clé API.

Tous les extraits de ce tutoriel supposent que vous accédez à votre clé API en tant que variable d'environnement de processus. Si vous développez une application Flutter, vous pouvez utiliser String.fromEnvironment et transmettre --dart-define=API_KEY=$API_KEY à flutter build ou flutter run pour procéder à la compilation avec la clé API, car l'environnement de processus sera différent lors de l'exécution de l'application.

Installer le package SDK

Pour utiliser l'API Gemini dans votre propre application, vous devez add le package google_generative_ai dans votre application Dart ou Flutter:

Dart 

dart pub add google_generative_ai

Flutter 

flutter pub add google_generative_ai

Initialiser le modèle génératif

Avant de pouvoir effectuer des appels d'API, vous devez importer et initialiser le modèle génératif.

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);
  }

  // The Gemini 1.5 models are versatile and work with most use cases
  final model = GenerativeModel(model: 'gemini-1.5-flash', apiKey: apiKey);
}

Lorsque vous spécifiez un modèle, tenez compte des points suivants:

  • Utilisez un modèle spécifique à votre cas d'utilisation (par exemple, gemini-1.5-flash est destiné à l'entrée multimodale). Dans ce guide, les instructions correspondant à chaque implémentation répertorient le modèle recommandé pour chaque cas d'utilisation.

Mettre en œuvre des cas d'utilisation courants

Maintenant que votre projet est configuré, vous pouvez explorer l'utilisation de l'API Gemini pour implémenter différents cas d'utilisation:

Dans la section des cas d'utilisation avancés, vous trouverez des informations sur l'API Gemini et les représentations vectorielles continues.

Générer du texte à partir d'une entrée textuelle uniquement

Lorsque l'entrée de la requête n'inclut que du texte, utilisez un modèle Gemini 1.5 ou Gemini 1.0 Pro avec generateContent pour générer une sortie textuelle:

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);
  }
  // The Gemini 1.5 models are versatile and work with both text-only and multimodal prompts
  final model = GenerativeModel(model: 'gemini-1.5-flash', apiKey: apiKey);
  final content = [Content.text('Write a story about a magic backpack.')];
  final response = await model.generateContent(content);
  print(response.text);
}

Générer du texte à partir d'une entrée texte et image (multimodal)

Gemini fournit différents modèles pouvant gérer la saisie multimodale (modèles Gemini 1.5) afin que vous puissiez saisir à la fois du texte et des images. Veillez à consulter les exigences concernant les images pour les requêtes.

Lorsque l'entrée de la requête inclut à la fois du texte et des images, utilisez un modèle Gemini 1.5 avec la méthode generateContent pour générer une sortie textuelle:

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);
  }
  // The Gemini 1.5 models are versatile and work with both text-only and multimodal prompts
  final model = GenerativeModel(model: 'gemini-1.5-flash', 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);
}

Développer des conversations multitours (chat)

Avec Gemini, vous pouvez construire des conversations libres dans plusieurs tours. Le SDK simplifie le processus en gérant l'état de la conversation. Ainsi, contrairement à generateContent, vous n'avez pas besoin de stocker vous-même l'historique de la conversation.

Pour créer une conversation multitours (comme un chat), utilisez un modèle Gemini 1.5 ou Gemini 1.0 Pro, puis initialisez la discussion en appelant startChat(). Utilisez ensuite sendMessage() pour envoyer un nouveau message à l'utilisateur, qui ajoutera également le message et la réponse à l'historique des discussions.

Il existe deux options possibles pour role associées au contenu d'une conversation:

  • user: rôle qui fournit les invites. Cette valeur est la valeur par défaut pour les appels sendMessage. La fonction génère une exception si un autre rôle est transmis.

  • model: rôle qui fournit les réponses. Ce rôle peut être utilisé lorsque vous appelez startChat() avec un history existant.

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);
  }
  // The Gemini 1.5 models are versatile and work with multi-turn conversations (like chat)
  final model = GenerativeModel(
      model: 'gemini-1.5-flash',
      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);
}

Utiliser le streaming pour des interactions plus rapides

Par défaut, le modèle renvoie une réponse à la fin du processus de génération. Vous pouvez obtenir des interactions plus rapides en n'attendant pas l'intégralité du résultat et en utilisant plutôt le traitement par flux pour gérer les résultats partiels.

L'exemple suivant montre comment implémenter la diffusion en continu avec la méthode generateContentStream pour générer du texte à partir d'une requête d'entrée de texte et d'image.

// ...

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

// ...

Vous pouvez adopter une approche similaire pour les cas d'utilisation de saisie uniquement de texte et de chat.

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

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

Implémenter des cas d'utilisation avancés

Les cas d'utilisation courants décrits dans la section précédente de ce tutoriel vous aident à vous familiariser avec l'API Gemini. Cette section décrit certains cas d'utilisation pouvant être considérés comme plus avancés.

Appel de fonction

L'appel de fonction vous permet d'obtenir plus facilement des sorties de données structurées à partir de modèles génératifs. Vous pouvez ensuite utiliser ces sorties pour appeler d'autres API et renvoyer les données de réponse pertinentes au modèle. En d'autres termes, l'appel de fonction vous aide à connecter des modèles génératifs à des systèmes externes afin que le contenu généré inclue les informations les plus récentes et les plus précises. Pour en savoir plus, consultez le tutoriel sur l'appel de fonction.

Utiliser des représentations vectorielles continues

La représentation vectorielle continue est une technique utilisée pour représenter des informations sous la forme d'une liste de nombres à virgule flottante dans un tableau. Avec Gemini, vous pouvez représenter du texte (mots, phrases et blocs de texte) sous forme vectorisée, ce qui facilite la comparaison des représentations vectorielles continues. Par exemple, deux textes partageant un sujet ou un sentiment similaire doivent avoir des représentations vectorielles continues similaires, qui peuvent être identifiées à l'aide de techniques de comparaison mathématique telles que la similarité cosinus.

Utilisez le modèle embedding-001 avec la méthode embedContent (ou la méthode batchEmbedContent) pour générer des représentations vectorielles continues. L'exemple suivant génère une représentation vectorielle continue pour une seule chaîne:

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);

Compter les jetons

Lorsque vous utilisez de longues requêtes, il peut être utile de compter les jetons avant d'envoyer du contenu au modèle. Les exemples suivants montrent comment utiliser countTokens() pour différents cas d'utilisation:

// 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}');

Options pour contrôler la génération de contenu

Vous pouvez contrôler la génération de contenu en configurant les paramètres du modèle et en utilisant les paramètres de sécurité.

Notez que la transmission de generationConfig ou safetySettings à une méthode de requête de modèle (telle que generateContent) remplacera complètement l'objet de configuration portant le même nom transmis dans getGenerativeModel.

Configurer les paramètres du modèle

Chaque requête que vous envoyez au modèle inclut des valeurs de paramètre qui contrôlent la manière dont le modèle génère une réponse. Le modèle peut générer différents résultats pour différentes valeurs de paramètre. En savoir plus sur les paramètres de modèle La configuration est conservée pendant la durée de vie de votre instance de modèle.

final generationConfig = GenerationConfig(
  stopSequences: ["red"],
  maxOutputTokens: 200,
  temperature: 0.9,
  topP: 0.1,
  topK: 16,
);
final model = GenerativeModel(
  // The Gemini 1.5 models are versatile and work with most use cases
  model: 'gemini-1.5-flash',
  apiKey: apiKey,
  generationConfig: generationConfig,
);

Utiliser les paramètres de sécurité

Vous pouvez utiliser les paramètres de sécurité pour ajuster la probabilité d'obtenir des réponses susceptibles d'être considérées comme dangereuses. Par défaut, les paramètres de sécurité bloquent le contenu dont la probabilité est moyenne et/ou élevée d'être dangereux pour toutes les dimensions. En savoir plus sur les paramètres de sécurité

Pour définir un paramètre de sécurité, procédez comme suit:

final safetySettings = [
  SafetySetting(HarmCategory.harassment, HarmBlockThreshold.high)
];
final model = GenerativeModel(
  // The Gemini 1.5 models are versatile and work with most use cases
  model: 'gemini-1.5-flash',
  apiKey: apiKey,
  safetySettings: safetySettings,
);

Vous pouvez également définir plusieurs paramètres de sécurité:

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

Étapes suivantes

  • La conception de requêtes est le processus de création de requêtes qui permettent d'obtenir la réponse souhaitée en utilisant des modèles de langage. Pour rédiger des réponses précises et de haute qualité à partir d'un modèle de langage, il est essentiel de rédiger des requêtes bien structurées. Découvrez les bonnes pratiques pour rédiger des requêtes.

  • Gemini propose plusieurs variantes de modèles pour répondre aux besoins de différents cas d'utilisation, tels que les types et la complexité des entrées, les implémentations de chat ou d'autres tâches liées au langage de dialogue, ainsi que les contraintes de taille. En savoir plus sur les modèles Gemini disponibles