Premiers pas avec l'API Gemini dans les applications Web

Ce tutoriel explique comment accéder à l'API Gemini directement depuis votre application Web à l'aide du SDK JavaScript de Google AI. Vous pouvez utiliser ce SDK si vous ne souhaitez pas utiliser directement les API REST ou le code côté serveur (comme Node.js) pour accéder aux modèles Gemini dans votre application Web.

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

Ce tutoriel contient également des sections sur les cas d'utilisation avancés (tels que les jetons de comptage) et sur les options de contrôle de la génération de contenu.

Prérequis

Dans ce tutoriel, nous partons du principe que vous savez utiliser JavaScript pour développer des applications Web. Ce guide est indépendant du framework.

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

  • (Facultatif) Node.js
  • Navigateur Web récent

Configurer votre projet

Avant d'appeler l'API Gemini, vous devez configurer votre projet, ce qui implique d'obtenir une clé API et d'initialiser le modèle.

Configurer votre clé API

Pour utiliser l'API Gemini, vous avez besoin d'une clé API. Si vous n'en avez pas, créez-en une dans Google AI Studio.

Obtenir une clé API

Sécuriser votre clé API

Il est vivement recommandé de ne pas vérifier une clé API dans votre système de contrôle des versions. Vous devez transmettre votre clé API à votre application juste avant d'initialiser le modèle.

Tous les extraits de ce tutoriel supposent que vous accédez à votre clé API en tant que constante globale.

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.

<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 = "...";

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

      // ...

      const model = genAI.getGenerativeModel({ model: "MODEL_NAME"});

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

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-pro-vision est destiné à l'entrée multimodale). Dans ce guide, les instructions pour chaque implémentation listent le modèle recommandé pour chaque cas d'utilisation.

Implémenter des cas d'utilisation courants

Maintenant que votre projet est configuré, vous pouvez découvrir comment utiliser l'API Gemini pour mettre en œuvre différents cas d'utilisation:

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

Lorsque l'entrée de la requête n'inclut que du texte, utilisez le modèle gemini-pro avec la méthode generateContent pour générer une sortie textuelle:

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() {
  // For text-only input, use the gemini-pro model
  const model = genAI.getGenerativeModel({ model: "gemini-pro"});

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

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

Gemini fournit un modèle multimodal (gemini-pro-vision), qui vous permet de saisir à la fois du texte et des images. Veillez à consulter les exigences concernant les images pour les entrées.

Lorsque l'entrée de la requête comprend à la fois du texte et des images, utilisez le modèle gemini-pro-vision avec la méthode generateContent pour générer une sortie textuelle:

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() {
  // For text-and-images input (multimodal), use the gemini-pro-vision model
  const model = genAI.getGenerativeModel({ model: "gemini-pro-vision" });

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

Créer des conversations multitours (chat)

Gemini vous permet de créer des conversations de forme libre sur 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 l'historique de la conversation vous-même.

Pour créer une conversation multitour (telle qu'un chat), utilisez le modèle gemini-pro, puis initialisez le chat en appelant startChat(). Utilisez ensuite sendMessage() pour envoyer un nouveau message utilisateur, qui ajoutera également le message et la réponse à l'historique des discussions.

Deux options sont possibles pour role associé 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 le history existant.

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() {
  // For text-only input, use the gemini-pro model
  const model = genAI.getGenerativeModel({ model: "gemini-pro"});

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

Utiliser le streaming pour des interactions plus rapides

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

L'exemple suivant montre comment implémenter la diffusion en flux continu avec la méthode generateContentStream pour générer du texte à partir d'une invite de saisie de texte et d'image.

// ...

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

// ...

Vous pouvez utiliser une approche similaire pour les cas d'utilisation de la saisie de texte et du chat.

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

Consultez l'exemple de chat ci-dessus pour découvrir comment instancier un chat.

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

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 aideront à vous familiariser avec l'API Gemini. Cette section décrit certains cas d'utilisation qui peuvent être considérés comme plus avancés.

Compter les jetons

Lorsque vous utilisez des invites longues, 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
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 });

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

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

Configurer les paramètres du modèle

Chaque invite que vous envoyez au modèle inclut des valeurs de paramètres 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. Apprenez-en plus sur les paramètres de modèle. La configuration est conservée pendant toute la durée de vie de votre instance de modèle.

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

const model = genAI.getGenerativeModel({ model: "MODEL_NAME",  generationConfig });

Utiliser les paramètres de sécurité

Vous pouvez utiliser les paramètres de sécurité pour ajuster la probabilité de recevoir des réponses pouvant être considérées comme nuisibles. Par défaut, les paramètres de sécurité bloquent le contenu ayant une probabilité moyenne et/ou élevée d'être un contenu dangereux dans toutes les dimensions. En savoir plus sur les paramètres de sécurité

Voici comment définir un paramètre de sécurité:

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

// ...

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

const model = genAI.getGenerativeModel({ model: "MODEL_NAME", safetySettings });

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

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

Étapes suivantes

  • La conception d'invites est le processus de création d'invites 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 invites bien structurées. Découvrez les bonnes pratiques concernant la rédaction de requêtes.

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

  • Gemini propose des options pour demander des augmentations de la limite de débit. La limite de débit pour les modèles Geni Pro est de 60 requêtes par minute (tr/min).