Gains :
- Peut décrire la structure de base d'une requête API LLM (point de terminaison, modèle, messages, max_tokens)
- Comprend la différence entre les rôles système, utilisateur et assistant et l'historique des conversations sans état
- Peut lire et interpréter les champs (blocs de contenu, stop_reason, utilisation) de la réponse renvoyée
Dans les modules précédents, nous avons utilisé l'intelligence artificielle depuis une fenêtre de discussion. Mais si vous souhaitez intégrer l’IA dans votre propre produit, automatisation ou flux de travail, une interface de chat ne suffira pas ; Vous devez vous connecter au modèle par programme, c'est-à-dire avec du code ou un outil d'automatisation. Le nom de ce pont est API (Application Programming Interface, le contrat qui permet à deux logiciels de communiquer avec certaines règles). Lorsque vous aurez terminé cette unité, vous saurez ce qui constitue une requête API LLM (Large Language Model), à quoi servent les rôles de message et comment lire la réponse. C’est la base sur laquelle le reste du module sera construit.
Comment fonctionne l'API ?
Le flux de base de l'API est le suivant : vous envoyez une requête dans un certain format ; Le serveur renvoie une réponse dans un format spécifique. Dans les LLM, il s'agit généralement d'un appel HTTP (HTTP : protocole standard d'acheminement des requêtes-réponses sur le web) vers une seule adresse (endpoint, l'adresse fixe sur le serveur qui gère votre requête). Par exemple, dans une API de messagerie, toutes les requêtes sont envoyées à une seule adresse et sont transportées dans le corps au format JSON (JavaScript Object Notation — un format de texte composé de paires clé/valeur qui peuvent être lues à la fois par les humains et les machines).
Dans une requête, vous précisez au moins ces trois choses :
- Modèle : quel modèle vous utiliserez (par exemple un modèle rapide et bon marché ou un modèle puissant).
- max_tokens : Le nombre maximum de jetons (la plus petite unité dans laquelle le texte est traité, qui sera traité en détail dans l'unité suivante) que le modèle peut produire ; c'est-à-dire la limite de sortie.
- messages : Liste des messages qui composent la conversation.
Étape par étape : comment configurer une demande
- Préparez le point de terminaison et les informations d’identification. Vous ajoutez votre clé API (la chaîne secrète qui prouve votre identité) à la requête dans un en-tête. Vous n'intégrez jamais la clé dans le code ; Nous couvrirons le stockage sûr dans l’unité 9.
- Sélectionnez le modèle et la limite de sortie. Modèle léger + petits max_tokens pour une tâche simple ; Modèle puissant + limite plus grande pour une tâche complexe.
- Configurez la liste des messages. List the system instruction, user message, and past rounds (if any).
- Envoyez la demande et analysez la réponse. Lisez le contenu du texte, le motif de l'arrêt et l'utilisation du jeton à partir du JSON renvoyé.
Rôles du message : système, utilisateur, assistant
Une conversation se compose de messages disposés dans une séquence et chaque message a un rôle. Le rôle détermine la manière dont le modèle traite ce texte.
Rôle
Qui écrit
Objectif
système
Développeur/opérateur
Instructions permanentes, personnalité et règles qui s'appliquent tout au long de la conversation
utilisateur
utilisateur final
La question ou la contribution actuelle de l'utilisateur
assistant
modèle
Réponse produite par le modèle (et réponses précédentes)
Le rôle système est disponible sous forme de champ système distinct dans le corps de la demande chez la plupart des fournisseurs ; l'utilisateur et l'assistant sont répertoriés séquentiellement dans la liste des messages. Critical point: the system instruction is the high-level instruction, the user message is the request to be answered at that moment.
{ "model": "claude-opus-4-8", "max_tokens": 1024, "system": "Vous êtes un assistant du support d'entreprise. Donnez une réponse courte, formelle et vérifiée. N'inventez pas d'informations dont vous n'êtes pas sûr.", "messages": [ { "role": "user", "content": "Comment démarrer mon processus de retour ?" } ]}
La parole est apatride
Voici l'idée fausse la plus courante : les appels d'API LLM sont sans état : le serveur ne conserve aucune mémoire entre deux requêtes. Le modèle ne se souvient pas de votre demande précédente. Si vous configurez une discussion à plusieurs tours, vous devrez renvoyer les tours précédents à chaque nouvelle demande. La « mémoire » du modèle est constituée d’une liste de messages que vous avez envoyés.
{ "model": "claude-opus-4-8", "max_tokens": 512, "messages": [ { "role": "user", "content": "Bonjour, je m'appelle Deniz." }, { "role": "assistant", "content": "Bonjour Deniz, comment puis-je t'aider ?" }, { "role": "user", "content": "Je viens de prononcer mon nom, vous vous en souvenez ?" } ]}
Répondre correctement au troisième message dépend de l’envoi des deux messages précédents. Si vous ne l'envoyez pas, le modèle ne connaîtra pas « Mer » et répondra de manière incorrecte. Cela affecte également directement le coût : plus la conversation est longue, plus la liste est longue, chaque requête consommant plus de jetons.
Astuce : Dans les conversations longues, résumer et déplacer les anciens tours (résumé + derniers tours) au lieu d'envoyer l'intégralité de l'historique réduit les coûts et préserve la fenêtre contextuelle. Nous approfondirons cela dans les unités 6 et 11.
Lire la réponse
Lorsque le modèle renvoie une réponse, vous recevez un objet structuré, pas du texte brut. Domaines typiques :
{ "id": "msg_01ABC...", "model": "claude-opus-4-8", "role": "assistant", "content": [ { "type": "text", "text": "Pour initier un retour, rendez-vous sur la page 'Mes commandes' de votre compte..." } ], "stop_reason": "end_turn", "usage": { "input_tokens": 47, "output_tokens": 88 }}
- contenu : la réponse elle-même ; Il s'agit d'une liste de blocs de contenu. Le champ de texte du bloc de texte est la réponse réelle.
- stop_reason : pourquoi le modèle s'est arrêté. end_turn = fin naturelle ; max_tokens = bloqué à la limite de sortie (la réponse peut être incomplète) ; refus = refusé pour des raisons de sécurité. Votre code doit toujours regarder stop_reason en premier.
- utilisation : numéros de jeton d’entrée et de sortie. C’est la base du suivi des coûts et des limites.
Attention : Si stop_reason vaut max_tokens, la réponse n'est pas terminée. Considérer cela comme une « réponse réussie » et afficher un demi-texte à l'utilisateur est l'une des erreurs les plus courantes en production. Soit augmentez max_tokens, soit utilisez le streaming.
Invite faible/Invite forte
Même tâche avec deux invites système différentes :
# FAIBLEVous êtes un assistant. Répondez aux questions.
# FORTVous êtes assistant support en entreprise. Règles : - S'appuyer uniquement sur les informations contenues dans le document de politique fourni ; Si cela ne figure pas dans le document, dites « Je n'ai pas cette information, je la transmets à l'unité compétente ». - Les réponses ne doivent pas dépasser 3 phrases, être formelles et claires. - Ne demandez pas de données personnelles (numéro d'identification TC, numéro de carte) et ne répétez pas. - Ne devinez pas si vous n'êtes pas sûr.
Version puissante ; Il définit le champ d'application, la forme, la marge de sécurité et le comportement dans l'incertitude. La cohérence des résultats du modèle découle directement de cette clarté.
Trois mini-étuis
Cas 1 — Bot de support (piège à l’apatridie). Une équipe de commerce électronique a mis le bot en ligne ; Lorsque l'utilisateur a dit "annuler la commande précédente", le bot "a oublié" le numéro de commande. Raison : ils envoyaient chaque demande avec seulement le dernier message. Solution : ils ont ajouté les 6 derniers tours à la liste des messages. Résultat : le contexte est préservé, mais les entrées par requête sont passées de 40 jetons à environ 600 jetons ; nous aborderons la leçon sur les coûts dans l'unité 2.
Cas 2 — Résumé du contrat incomplet. Une équipe juridique faisait rédiger des contrats de 10 pages ; max_tokens : 300 restaient faibles, les résumés coupaient au milieu d'une phrase. stop_reason était max_tokens à chaque fois mais personne ne regardait. augmentation de max_tokens à 1 500 et ajout de la vérification stop_reason ; Le taux de synthèse tronquée est passé de 18% à 0%.
Cas 3 — Mélange des rôles. Une équipe marketing écrivait toutes les instructions dans le message utilisateur, laissant le système vide. Lorsque l'entrée de l'utilisateur était mélangée à des instructions, le modèle se conformait parfois à la commande de l'utilisateur d'« oublier les règles précédentes ». Ils ont transféré des règles permanentes dans le système ; En séparant les entrées des utilisateurs des instructions, les violations des règles ont considérablement diminué.
Erreurs courantes
- Oublier d'envoyer le passé : On pense que le modèle « ne se souvient pas » ; alors qu'il est apatride. Vous portez le contexte.
- Ne pas regarder `stop_reason` : la réponse arrêtée avec max_tokens est considérée comme terminée.
- Intégration de l'instruction dans `user` : règles persistantes dans le système ; la saisie instantanée est transmise à l'utilisateur. Le mixage crée des failles de sécurité.
- Confondre « contenu » avec une chaîne simple : la réponse est une liste de blocs ; lisez le champ de texte du premier bloc de texte, vérifiez son type avant d'obtenir le contenu[0] avec un index aveugle.
- Intégrer la clé dans le code : Utiliser une variable d'environnement (unité 9).
Plus profond : blocs de contenu et réponses en plusieurs parties
Comprendre pourquoi le champ de contenu de la réponse est une liste est fondamental pour les fonctionnalités avancées que vous rencontrerez plus tard. Parfois, le modèle renvoie non pas un seul bloc de texte, mais plusieurs blocs : un bloc de réflexion, suivi d'un bloc de texte ; ou un bloc de texte suivi d'un bloc d'utilisation d'outil. C'est pourquoi compter aveuglément content[0] comme une « réponse » est fragile. La bonne approche consiste à parcourir la liste et à la trier par type : vous collectez le contenu textuel des blocs dont le champ de type est texte et traitez les autres types (réflexion, outil) séparément.
En pratique, cette distinction vous permet d'enregistrer le raisonnement du modèle (le cas échéant) sans le révéler à l'utilisateur, de rediriger les appels d'outils vers une logique séparée et d'imprimer uniquement la réponse réelle à l'écran. Au fur et à mesure que le module progresse (en particulier dans les unités 4 et 11), vous verrez à quel point cette structure de blocs est utile pour valider et diriger la sortie.
Autre point pratique : vous pouvez accéder au même modèle depuis différentes plateformes prestataires (API directe, via un fournisseur cloud). Bien que l'adresse du point de terminaison et le format d'authentification puissent changer, les concepts de base tels que les rôles de message, l'apatridie et la structure de réponse restent les mêmes. Les bases de cette unité s’appliquent donc quelle que soit la plateforme que vous utilisez.
En résumé
Une requête API LLM comprend le modèle, la limite de sortie et la liste de messages ; les rôles (système, utilisateur, assistant) déterminent le comportement du modèle. Les appels sont apatrides : vous portez le contexte à chaque requête. La réponse est un objet structuré ; La lecture et l’interprétation des champs content, stop_reason et use sont la base de la durabilité en production.
Tâche de candidature
Choisissez une tâche dans votre propre profession (par exemple trier les e-mails entrants, créer de brefs résumés). Sur un morceau de papier : (1) écrivez l'invite système avec 4 à 5 règles, (2) configurez un exemple de message utilisateur et un historique de 2 tours le cas échéant, (3) déterminez une valeur raisonnable pour max_tokens et écrivez la justification, (4) listez les valeurs stop_reason que vous gérerez dans la réponse renvoyée et comment.
liste de contrôle
- [ ] Je peux compter les trois parties obligatoires d'une requête (modèle, max_tokens, messages).
- [ ] Je peux expliquer la différence entre les rôles système, utilisateur et assistant.
- [ ] Je sais que les appels sont apatrides et que je dois porter le passé.
- Je peux lire et commenter le contenu de [ ], stop_reason et les champs d'utilisation.
- [ ] Avec max_tokens, je peux remarquer et gérer la réponse tronquée.