Blog

Comment utiliser Vercel AI SDK: Guide pour débutants

Rebecca Kovács

Rebecca Kovács

10 June 2025

Comment utiliser Vercel AI SDK: Guide pour débutants

Bienvenue dans le guide définitif du Vercel AI SDK pour débutants. Dans un monde où l'intelligence artificielle transforme rapidement le paysage numérique, la capacité d'intégrer l'IA dans les applications web est passée d'une spécialisation de niche à une compétence essentielle pour les développeurs modernes. Ce guide est conçu pour vous faire passer d'un débutant curieux à un développeur d'applications IA compétent.

Pendant longtemps, combler le fossé entre un puissant Grand Modèle de Langage (LLM) et une interface web conviviale a été une entreprise complexe. Les développeurs devaient se débattre avec des API de fournisseurs disparates, gérer des états complexes et implémenter manuellement des fonctionnalités telles que le streaming de réponses. Le Vercel AI SDK a été créé pour résoudre exactement ces problèmes. C'est une boîte à outils TypeScript-first qui fournit une couche d'abstraction unifiée et élégante sur les complexités de la construction d'expériences basées sur l'IA.

Ce n'est pas seulement un guide de démarrage rapide. Au cours de ce tutoriel, nous construirons un chatbot IA complet et riche en fonctionnalités, de A à Z, en utilisant Next.js et le modèle Gemini de Google. Nous irons bien au-delà d'un simple exemple "hello world". Vous apprendrez :

À la fin de ce guide complet, vous aurez non seulement un chatbot fonctionnel et avancé, mais aussi les connaissances conceptuelles approfondies nécessaires pour construire en toute confiance vos propres applications uniques et puissantes basées sur l'IA avec le Vercel AI SDK.

💡
Vous voulez un excellent outil de test d'API qui génère de belles documentations d'API ?

Vous voulez une plateforme intégrée, tout-en-un, pour que votre équipe de développeurs travaille ensemble avec une productivité maximale ?

Apidog répond à toutes vos demandes et remplace Postman à un prix beaucoup plus abordable !
button

Chapitre 1 : Fondations et Configuration

Toute grande structure a besoin d'une base solide. Dans ce chapitre, nous allons configurer notre environnement de développement, installer les outils nécessaires et mettre en ordre nos clés API. Nous prendrons également un moment pour comprendre le "pourquoi" derrière chaque choix que nous faisons.

Prérequis

Avant d'écrire une seule ligne de code, assurons-nous que votre boîte à outils est prête.

  1. Naviguez vers Google AI Studio.
  2. Connectez-vous avec votre compte Google.
  3. Cliquez sur "Get API key" (Obtenir une clé API), puis sur "Create API key in new project" (Créer une clé API dans un nouveau projet).
  4. Copiez la clé générée et stockez-la en lieu sûr pour l'instant. Traitez cette clé comme un mot de passe ; ne l'exposez jamais publiquement.

Étape 1 : Initialisation du Projet Next.js

Nous utiliserons Next.js, le framework React de premier choix pour construire des applications de qualité production. Son paradigme App Router s'intègre parfaitement à la nature centrée sur le serveur des applications IA.

Ouvrez votre terminal et exécutez cette commande pour créer un nouveau projet :

npx create-next-app@latest vercel-ai-tutorial

L'installateur vous posera plusieurs questions. Utilisez ces paramètres pour suivre sans problème :

Une fois l'installation terminée, naviguez dans le répertoire de votre projet nouvellement créé :

cd vercel-ai-tutorial

Étape 2 : Installation du Vercel AI SDK

Maintenant, ajoutons les paquets du AI SDK à notre projet.

npm install ai @ai-sdk/react @ai-sdk/google zod

Décortiquons ce que fait chacun de ces paquets :

Étape 3 : Sécurisation de Votre Clé API

Ne codez jamais en dur une clé API dans le code de votre application. C'est un risque de sécurité majeur. La norme professionnelle est d'utiliser des variables d'environnement. Next.js a un support intégré pour cela avec les fichiers .env.local.

Créez le fichier à la racine de votre projet :

touch .env.local

Maintenant, ouvrez ce nouveau fichier et ajoutez votre clé Google AI :

# .env.local
# Ce fichier est pour le développement local et NE DOIT PAS être committé sur git.
GOOGLE_GENERATIVE_AI_API_KEY=VOTRE_CLE_API_GOOGLE_AI

Remplacez VOTRE_CLE_API_GOOGLE_AI par la clé que vous avez copiée précédemment. Next.js charge automatiquement ce fichier et rend la clé disponible sur le serveur, ce qui est exactement là où nous en avons besoin.

Chapitre 2 : Construction de la Structure du Chatbot

Avec notre projet configuré, il est temps de construire les composants principaux de notre application : le point de terminaison API côté serveur qui communique avec l'IA, et l'interface utilisateur côté client avec laquelle les utilisateurs interagiront.

L'Architecture Client-Serveur d'une Application IA

Notre chatbot aura deux parties principales :

  1. Une Route API Côté Serveur (/api/chat/route.ts) : C'est un environnement sécurisé qui s'exécute sur un serveur. Son travail principal est de recevoir l'historique du chat depuis le navigateur de l'utilisateur, d'ajouter notre clé API secrète, de transmettre la requête au service Google AI, puis de streamer la réponse à l'utilisateur. Garder cette logique sur le serveur est essentiel pour la sécurité—cela garantit que notre clé API n'est jamais exposée au public.
  2. Une Interface Utilisateur Côté Client (page.tsx) : C'est le composant React qui s'exécute dans le navigateur de l'utilisateur. Il est responsable de l'affichage de l'historique du chat, de la capture de l'entrée utilisateur et de l'envoi de cette entrée à notre route API.

Cette séparation est fondamentale pour construire des applications web sécurisées et performantes.

Étape 4 : Création du Gestionnaire de Route API

Créons le point de terminaison côté serveur. Dans votre répertoire src/app, créez un nouveau dossier api, et à l'intérieur de celui-ci, un autre dossier chat. Enfin, créez un fichier nommé route.ts à l'intérieur du dossier chat.

Le chemin final devrait être src/app/api/chat/route.ts.

Remplissez ce fichier avec le code suivant :

// src/app/api/chat/route.ts

import { google } from '@ai-sdk/google';
import { streamText } from 'ai';

// Configuration spécifique à Vercel pour permettre le streaming des réponses jusqu'à 30 secondes
export const maxDuration = 30;

// Le gestionnaire de route API principal
export async function POST(req: Request) {
  try {
    // Extraire le tableau `messages` du corps de la requête
    const { messages } = await req.json();

    // Appeler le fournisseur d'IA avec l'historique de la conversation
    const result = await streamText({
      model: google('models/gemini-1.5-pro-latest'),
      // Le tableau `messages` fournit au modèle le contexte de la conversation
      messages,
    });

    // Répondre avec une réponse en streaming
    return result.toDataStreamResponse();
  } catch (error) {
    // C'est une bonne pratique de gérer les erreurs potentielles
    if (error instanceof Error) {
      return new Response(JSON.stringify({ error: error.message }), { status: 500 });
    }
    return new Response(JSON.stringify({ error: 'Une erreur inconnue est survenue' }), { status: 500 });
  }
}

Décortiquons ce fichier crucial :

Étape 5 : Conception de l'Interface Utilisateur

Maintenant, la partie amusante : construire l'interface utilisateur. Grâce au paquet @ai-sdk/react, c'est étonnamment simple. Ouvrez le fichier de la page principale à src/app/page.tsx et remplacez tout son contenu par ce qui suit :

// src/app/page.tsx

'use client';

import { useChat } from '@ai-sdk/react';
import { useRef, useEffect } from 'react';

export default function Chat() {
  const { messages, input, handleInputChange, handleSubmit, isLoading, error } = useChat();

  // Une référence au conteneur de messages scrollable
  const messagesContainerRef = useRef<HTMLDivElement>(null);

  // Effet pour faire défiler vers le bas du conteneur de messages chaque fois que les messages changent
  useEffect(() => {
    if (messagesContainerRef.current) {
      messagesContainerRef.current.scrollTop = messagesContainerRef.current.scrollHeight;
    }
  }, [messages]);

  return (
    <div className="flex flex-col h-screen bg-gray-50">
      {/* Conteneur de messages */}
      <div ref={messagesContainerRef} className="flex-1 overflow-y-auto p-8 space-y-4">
        {messages.map(m => (
          <div
            key={m.id}
            className={`flex gap-3 ${m.role === 'user' ? 'justify-end' : 'justify-start'}`}
          >
            {/* Afficher l'avatar de l'utilisateur */}
            {m.role === 'user' && (
              <div className="w-10 h-10 rounded-full bg-blue-500 flex items-center justify-center text-white font-bold">U</div>
            )}

            {/* Bulle de message */}
            <div
              className={`max-w-xl p-3 rounded-2xl shadow-md whitespace-pre-wrap ${
                m.role === 'user'
                  ? 'bg-blue-500 text-white rounded-br-none'
                  : 'bg-white text-black rounded-bl-none'
              }`}
            >
              <span className="font-bold block">{m.role === 'user' ? 'Vous' : 'Assistant IA'}</span>
              {m.content}
            </div>

            {/* Afficher l'avatar de l'IA */}
            {m.role !== 'user' && (
              <div className="w-10 h-10 rounded-full bg-gray-700 flex items-center justify-center text-white font-bold">IA</div>
            )}
          </div>
        ))}
      </div>

      {/* Formulaire de saisie */}
      <div className="p-4 bg-white border-t">
        <form onSubmit={handleSubmit} className="flex items-center gap-4 max-w-4xl mx-auto">
          <input
            className="flex-1 p-3 border rounded-full focus:outline-none focus:ring-2 focus:ring-blue-500"
            value={input}
            placeholder="Posez-moi une question..."
            onChange={handleInputChange}
            disabled={isLoading}
          />
          <button
            type="submit"
            className="px-6 py-3 bg-blue-500 text-white rounded-full font-semibold hover:bg-blue-600 disabled:bg-blue-300 disabled:cursor-not-allowed"
            disabled={isLoading}
          >
            Envoyer
          </button>
        </form>
        {error && (
          <p className="text-red-500 mt-2 text-center">{error.message}</p>
        )}
      </div>
    </div>
  );
}

C'est une quantité de code significative, mais la majeure partie sert à créer une interface utilisateur soignée avec Tailwind CSS. Concentrons-nous sur la logique :

Étape 6 : Exécutez Votre Application

Vous avez maintenant construit un chatbot IA complet et bien structuré. Lançons-le !

npm run dev

Naviguez vers http://localhost:3000 dans votre navigateur. Vous devriez être accueilli par une interface de chat soignée. Posez-lui une question. Vous verrez votre message apparaître instantanément, et la réponse de l'IA sera streamée jeton par jeton.

Chapitre 3 : Capacités Avancées - Donner des Super-pouvoirs à Votre Chatbot

Notre chatbot est intelligent, mais ses connaissances sont limitées à ses données d'entraînement. Il ne peut pas accéder à des informations en direct ni effectuer d'actions dans le monde réel. Dans ce chapitre, nous allons lui donner des "Outils" pour surmonter ces limitations.

Que Sont les Outils ?

Un Outil est une fonction que vous définissez et que le LLM peut choisir d'exécuter. Vous décrivez l'outil au modèle, et lorsqu'il pense que l'outil est nécessaire pour répondre à la requête d'un utilisateur, il met en pause sa génération de texte et produit à la place un objet spécial "appel d'outil". Votre code exécute alors la fonction avec les arguments fournis par le modèle, et le résultat est renvoyé au modèle. Le modèle utilise ensuite cette nouvelle information pour générer sa réponse finale, plus précise.

Donnons à notre chatbot deux outils :

  1. Un outil pour obtenir la météo actuelle d'un lieu.
  2. Un outil pour convertir les températures de Fahrenheit en Celsius.

Cela permettra à notre bot de répondre à des questions comme "Quelle est la météo à Londres en Celsius ?"—une tâche nécessitant plusieurs étapes et des données externes.

Étape 7 : Mise à Jour de l'API pour Supporter les Outils

Nous devons définir nos outils dans l'appel streamText sur le serveur. Ouvrez src/app/api/chat/route.ts et modifiez-le pour inclure la nouvelle définition tools.

// src/app/api/chat/route.ts
import { google } from '@ai-sdk/google';
import { streamText, tool } from 'ai';
import { z } from 'zod';

export const maxDuration = 30;

export async function POST(req: Request) {
  const { messages } = await req.json();

  const result = await streamText({
    model: google('models/gemini-1.5-pro-latest'),
    messages,
    // Définir les outils que le modèle peut utiliser
    tools: {
      getWeather: tool({
        description: 'Get the current weather for a specific location. Always returns temperature in Fahrenheit.',
        parameters: z.object({
          location: z.string().describe('The city and state, e.g., San Francisco, CA'),
        }),
        execute: async ({ location }) => {
          // Dans une vraie application, vous feriez une requête à une vraie API météo
          console.log(`Fetching weather for ${location}`);
          return {
            temperature: Math.floor(Math.random() * (100 - 30 + 1) + 30),
            high: Math.floor(Math.random() * (100 - 80 + 1) + 80),
            low: Math.floor(Math.random() * (50 - 30 + 1) + 30),
            conditions: ['Sunny', 'Cloudy', 'Rainy'][Math.floor(Math.random() * 3)],
          };
        },
      }),
      convertFahrenheitToCelsius: tool({
        description: 'Convert a temperature from Fahrenheit to Celsius.',
        parameters: z.object({
          temperature: z.number().describe('The temperature in Fahrenheit'),
        }),
        execute: async ({ temperature }) => {
          console.log(`Converting ${temperature}°F to Celsius`);
          return {
            celsius: Math.round((temperature - 32) * (5 / 9)),
          };
        },
      }),
    },
  });

  return result.toDataStreamResponse();
}

Analysons l'objet tools :

Étape 8 : Activation des Appels d'Outils Multi-étapes dans l'Interface Utilisateur

Définir les outils sur le serveur ne suffit pas. Par défaut, lorsque le modèle effectue un appel d'outil, la conversation s'arrête. Nous devons indiquer à notre hook useChat d'envoyer automatiquement le résultat de cet appel d'outil au modèle afin qu'il puisse continuer son raisonnement et formuler une réponse finale.

C'est incroyablement simple. Dans src/app/page.tsx, mettez à jour l'initialisation du hook useChat :

// src/app/page.tsx

// ...
export default function Chat() {
  const { messages, input, handleInputChange, handleSubmit, isLoading, error } = useChat({
    // Indiquer au hook d'envoyer automatiquement les résultats des outils au modèle
    experimental_sendExtraToolMessages: true,
  });
  // ... reste du composant
}

C'est tout. La propriété experimental_sendExtraToolMessages: true active le flux d'utilisation d'outils en plusieurs étapes.

Étape 9 : Une Meilleure Interface Utilisateur pour les Invocations d'Outils

Notre interface utilisateur actuelle n'affiche que m.content. Lorsqu'un outil est appelé, l'information intéressante se trouve dans une propriété différente de l'objet message. Créons un composant dédié pour afficher joliment les appels d'outils.

Tout d'abord, mettons à jour la boucle principale des messages dans src/app/page.tsx pour afficher ces invocations.

// src/app/page.tsx

// ... à l'intérieur de l'instruction return du composant Chat
<div ref={messagesContainerRef} className="flex-1 overflow-y-auto p-8 space-y-4">
  {messages.map(m => (
    <div
      key={m.id}
      className={`flex gap-3 ${m.role === 'user' ? 'justify-end' : 'justify-start'}`}
    >
      {/* ... avatars ... */}
      <div
        className={`max-w-xl p-3 rounded-2xl shadow-md whitespace-pre-wrap ${
          m.role === 'user'
            ? 'bg-blue-500 text-white rounded-br-none'
            : 'bg-white text-black rounded-bl-none'
        }`}
      >
        <span className="font-bold block">{m.role === 'user' ? 'Vous' : 'Assistant IA'}</span>

        {/* Afficher les invocations d'outils */}
        {m.toolInvocations?.map(tool => (
          <div key={tool.toolCallId} className="my-2 p-2 bg-gray-100 rounded text-sm text-gray-700">
            <p className="font-semibold">Appel d'outil : `{tool.toolName}`</p>
            <pre className="mt-1 p-1 bg-gray-200 rounded text-xs">
              {JSON.stringify(tool.args, null, 2)}
            </pre>
          </div>
        ))}

        {m.content}
      </div>
      {/* ... avatars ... */}
    </div>
  ))}
  {isLoading && messages[messages.length - 1]?.role === 'assistant' && (
      <div className="flex justify-start p-8 space-x-3">
          <div className="w-10 h-10 rounded-full bg-gray-700 flex items-center justify-center text-white font-bold">IA</div>
          <div className="p-3 rounded-2xl shadow-md bg-white">
              <div className="typing-indicator">
                  <span></span><span></span><span></span>
              </div>
          </div>
      </div>
  )}
</div>
// ...

J'ai également ajouté un simple indicateur de saisie qui apparaît pendant que l'assistant réfléchit. Vous devrez ajouter un peu de CSS pour cela. Dans votre fichier src/app/globals.css, ajoutez :

/* src/app/globals.css */

.typing-indicator span {
  height: 8px;
  width: 8px;
  background-color: #9E9EA1;
  border-radius: 50%;
  display: inline-block;
  animation: a 1.2s infinite ease-in-out;
}
.typing-indicator span:nth-child(1) { animation-delay: -0.4s; }
.typing-indicator span:nth-child(2) { animation-delay: -0.2s; }
@keyframes a {
  0%, 60%, 100% { transform: scale(0.2); }
  30% { transform: scale(1); }
}

Maintenant, exécutez à nouveau l'application. Demandez-lui : "Quelle est la météo à New York en Celsius ?" Vous verrez une chaîne d'événements fascinante se dérouler dans votre interface utilisateur :

  1. Le modèle appellera d'abord l'outil getWeather. Vous verrez l'appel d'outil rendu dans l'interface utilisateur.
  2. Le résultat (une température aléatoire en Fahrenheit) est renvoyé au modèle.
  3. Le modèle, sachant qu'il a besoin de Celsius, appellera alors l'outil convertFahrenheitToCelsius, en utilisant la température du résultat du premier outil comme entrée.
  4. Enfin, avec la température en Celsius en main, il générera une réponse en langage naturel répondant à votre question originale.

C'est le pouvoir de construire des Agents IA, et le Vercel AI SDK rend cette orchestration complexe remarquablement simple.

Chapitre 4 : Où Aller à Partir d'Ici ?

Vous avez construit avec succès un chatbot avancé basé sur l'IA. Vous êtes passé d'une page blanche à une application riche en fonctionnalités capable de streamer des réponses, de gérer les états de chargement et d'erreur, et de tirer parti des outils pour interagir avec des données externes de manière multi-étapes.

Ce guide vous a donné une base solide, mais ce n'est que le début. Le Vercel AI SDK a encore plus à offrir. Voici quelques pistes pour votre exploration continue :

L'avenir du développement web est intelligent, interactif et personnalisé. Avec le Vercel AI SDK, vous possédez maintenant les outils et les connaissances pour être à l'avant-garde de cette révolution. Bon développement !

💡
Vous voulez un excellent outil de test d'API qui génère de belles documentations d'API ?

Vous voulez une plateforme intégrée, tout-en-un, pour que votre équipe de développeurs travaille ensemble avec une productivité maximale ?

Apidog répond à toutes vos demandes et remplace Postman à un prix beaucoup plus abordable !
button

Pratiquez le Design-first d'API dans Apidog

Découvrez une manière plus simple de créer et utiliser des API

S'inscrire gratuitementTélécharger