Comment des programmes se parlent sur un réseau
HTTP est la façon dont deux programmes se parlent sur un réseau : l’un envoie une requête et l’autre renvoie une réponse. JSON est le format de texte qu’ils utilisent le plus souvent pour les données.
Toute API de modèle fonctionne ainsi. Quand vous savez lire une requête et une réponse, vous pouvez les utiliser toutes.
À la fin de cette leçon
Remarque
Je peux lire et écrire une requête HTTP et un corps JSON.
Mots clés
| Mot | Ce que ça veut dire | Exemple |
|---|---|---|
| Requête | ce qu’un programme envoie pour demander quelque chose | |
| Réponse | ce qui revient en réponse à une requête | |
| En-tête | un détail nommé sur une requête ou une réponse | content-type |
| Code d’état | un nombre qui dit comment la requête s’est passée | 200 |
| JSON | un format de texte pour des données faites de clés et de valeurs |
Les cellules que les étudiants remplissent restent vides dans cet aperçu.
Une requête a quatre parties
La méthode dit quoi faire : GET lit et POST envoie des données. L’URL dit où. Les en-têtes ajoutent des détails, comme le type des données. Le corps contient les données elles-mêmes.
Une API de modèle reçoit un POST dont le corps JSON contient vos messages.
Exemple travaillé : une requête, partie par partie
| Partie | Ce qu’elle contient | Dans notre appel |
|---|---|---|
| Méthode | Quoi faire | POST |
| URL | Où l’envoyer | http://ai:4000/v1/chat/completions |
| En-tête | Le type du corps | content-type: application/json |
| Corps | Les données, en JSON | model, messages, max_tokens |
Les cellules que les étudiants remplissent restent vides dans cet aperçu.
Afficher la requête qu’un script enverrait
docker exec -w /home/node/project agent node -e "const corps={model:'lab',messages:[{role:'user',content:'Dites bonjour'}],max_tokens:20};console.log('POST /v1/chat/completions');console.log('content-type: application/json');console.log(JSON.stringify(corps,null,2))"Affichée ici, non exécutée. Créez un compte gratuit pour appuyer sur Exécuter et la saisir dans le terminal de votre propre labo.
JSON : du texte, des clés, des valeurs
JSON écrit des données sous forme de texte. Un objet est une paire d’accolades autour de paires "clé": valeur. Une liste est entre crochets. Les clés sont toujours entre guillemets doubles.
Votre programme transforme des données en texte JSON pour les envoyer (JSON.stringify), puis le texte JSON en données pour les lire (JSON.parse).
Une réponse a un état et un corps
Le premier élément d’une réponse est le code d’état. Un nombre de 200 à 299 veut dire que tout a marché. Un nombre de 400 à 499 veut dire que la requête est fautive. Un 500 ou plus veut dire que le problème vient du service.
Lisez l’état avant de lire le corps.
Exemple travaillé : les codes d’état courants
| État | Sens | Ce que vous faites |
|---|---|---|
| 200 | Tout a marché | Lire le corps |
| 400 | La requête est incorrecte | Corriger le corps |
| 401 | Clé absente ou fausse | Vérifier la clé |
| 403 | Accès refusé | Lire le message |
| 429 | Trop de requêtes | Attendre, puis réessayer |
| 503 | Service pas prêt | Réessayer plus tard |
Les cellules que les étudiants remplissent restent vides dans cet aperçu.
Appeler un modèle et lire l’état
docker exec -w /home/node/project agent node -e "const u=(process.env.AI_URL||'http://ai:4000')+'/v1/chat/completions';const montrer=(s,t,k,m)=>{console.log('Statut : '+s);console.log('Type de contenu : '+t);console.log('Clés de premier niveau : '+k);console.log('Réponse : '+m)};(async()=>{try{const r=await fetch(u,{method:'POST',headers:{'content-type':'application/json',authorization:'Bearer lab'},body:JSON.stringify({model:'lab',messages:[{role:'user',content:'Dites bonjour en trois mots.'}],max_tokens:20})});const j=await r.json();if(r.ok===false)throw new Error(r.status+' '+j.error.message);montrer(r.status,r.headers.get('content-type'),Object.keys(j).join(', '),j.choices[0].message.content)}catch(e){console.log('Aucune réponse ('+e.message+'). Exemple enregistré :');montrer(200,'application/json','id, object, model, choices, usage','Bonjour à vous, ami.')}})()"Affichée ici, non exécutée. Créez un compte gratuit pour appuyer sur Exécuter et la saisir dans le terminal de votre propre labo.
Une erreur fréquente
Attention
Beaucoup de gens pensent que l’état 200 veut dire que la réponse est juste. Il veut seulement dire que la requête a marché. Un modèle peut renvoyer 200 avec une réponse fausse ou étrange. Vérifiez l’état d’abord, puis le contenu.
Pour aller plus loin : changer la requête
Modifiez l’exécution qui affiche la requête. Ajoutez temperature: 0 au corps et relancez. Puis changez max_tokens en 5.
Notez à chaque fois quelle partie vous avez changée : la méthode, l’URL, un en-tête ou le corps.