Accéder à l'API

Quand on développe une application alimentée par Claude, il est essentiel de comprendre le cycle complet d’une requête API — pas seulement pour la culture : chaque étape de ce cycle correspond à une décision d’architecture, un paramètre à régler ou un coût à maîtriser. Voici ce qui se passe, de bout en bout, quand un utilisateur envoie un message à votre application.

Le flux complet d’une requête

Le parcours d’un message utilisateur jusqu’à la réponse de Claude suit cinq étapes distinctes : requête vers votre serveur, requête vers Vertex AI, traitement par le modèle, réponse vers le serveur, puis réponse vers le client. Deux allers-retours emboîtés, donc : le navigateur ou l’application mobile parle à votre serveur, et votre serveur parle à Vertex AI. Cette architecture n’est pas une option de confort — elle est obligatoire, et la raison mérite d’être comprise.

Pourquoi un serveur intermédiaire est indispensable

Ne faites jamais de requêtes API directement depuis le code côté client. Les requêtes nécessitent des identifiants secrets — sur Vertex, les credentials Google Cloud de votre projet — qui doivent rester protégés. Tout ce qui vit dans le code client est public par nature : il suffit d’ouvrir les outils de développement du navigateur pour lire les requêtes et ce qu’elles transportent. Des identifiants exposés, c’est votre quota et votre facture au service du premier venu. Votre serveur agit donc comme intermédiaire sécurisé : les secrets n’existent que chez lui, et c’est lui qui parle à Vertex AI au nom de tous vos utilisateurs.

Construire la requête API

Votre serveur communique avec Vertex AI via les SDK Anthropic ou les SDK officiels Google Vertex — Anthropic fournit des SDK pour Python, TypeScript, Go et Ruby ; ce cours utilise Python. Chaque requête doit inclure ces champs obligatoires :

• Identifiants : authentifient votre requête (sur Vertex : les credentials Google, configurés en leçon suivante)
• Model : nom du modèle spécifique à utiliser
• Messages : liste contenant le texte de l’utilisateur
• Max Tokens : limite le nombre de tokens que le modèle peut générer

Ces quatre champs reviendront dans chaque requête du cours — les trois derniers sous exactement ces noms dans le SDK.

Le processus de génération de texte

Une fois la requête reçue, que fait le modèle ? Quatre étapes, utiles à connaître car plusieurs paramètres de l’API s’y rattachent directement.

Tokenisation

Claude découpe le texte en fragments appelés tokens — des mots entiers, des parties de mots, des espaces ou des symboles. C’est l’unité qui compte partout dans l’API : les limites, les coûts et le paramètre max_tokens s’expriment en tokens, pas en caractères.

Embedding

Chaque token est converti en un embedding : une longue liste de nombres représentant toutes les significations possibles du mot. Le texte devient une matière que le modèle peut réellement manipuler — des nombres.

Contextualisation

Comme un mot peut avoir plusieurs sens, Claude utilise le contexte pour déterminer la bonne interprétation. Le mot « quantum » peut désigner la physique, l’informatique, ou simplement « très petit » : l’embedding de chaque token est ajusté en fonction des mots voisins, jusqu’à ce que chaque mot porte le sens que cette phrase lui donne.

Génération

Les embeddings contextualisés passent par une couche de sortie qui produit des probabilités pour chaque mot suivant possible. Point important : Claude ne choisit pas toujours le mot le plus probable — il utilise un mélange de probabilité et d’aléatoire pour des réponses plus naturelles. C’est pourquoi deux exécutions de la même requête peuvent différer, et c’est ce dosage qu’un paramètre nommé température permettra de régler.

Conditions d’arrêt

La génération est une boucle — un token, puis le suivant — et après chaque token généré, Claude vérifie s’il doit s’arrêter :

• Max tokens atteint : la limite spécifiée est-elle dépassée ?
• Fin naturelle : un token de fin de séquence a-t-il été généré ?
• Séquence d’arrêt : une phrase d’arrêt prédéfinie a-t-elle été rencontrée ?

Chacune de ces conditions correspond à un levier que vous contrôlerez : le plafond max_tokens, et les séquences d’arrêt personnalisées d’une prochaine leçon.

La réponse

La réponse de Vertex AI contient trois informations :

• Message : le texte généré
• Usage : nombre de tokens en entrée et en sortie
• Stop Reason : raison de l’arrêt de la génération

Le texte est ce que l’utilisateur attend ; les deux autres champs sont pour vous. Usage permet de suivre les coûts requête par requête, et Stop Reason dit pourquoi la génération s’est terminée — fin naturelle ou plafond atteint, ce qui signale une réponse tronquée. Votre serveur transmet ensuite le texte généré à votre application cliente, et le cycle est bouclé.

Points clés à retenir

• Le flux fait toujours deux sauts : client → votre serveur → Vertex AI — jamais de raccourci
• Les identifiants restent côté serveur : le code client est public par nature
• Quatre champs par requête : identifiants, modèle, messages, max_tokens
• Génération = tokenisation → embeddings → contextualisation → boucle de sortie probabiliste
• Lisez usage (coûts) et stop_reason (réponse complète ou tronquée) dans chaque réponse