Avant d’écrire la moindre ligne de code avec Claude, il est essentiel de comprendre quelques notions fondamentales : les tokens, la context window, le sampling, le non-déterminisme, le choix du modèle, les modes de prompting et les différentes façons d’accéder à l’API.
Ces concepts constituent la base sur laquelle reposent les usages plus avancés de Claude : tool use, agents, evals, streaming, traitements asynchrones ou encore architectures de production.
Dans cet article, nous allons parcourir ces fondations de manière pratique.
1. Les tokens : l’unité de base de Claude
Claude ne lit pas directement des caractères ou des mots. Il traite des tokens.
Un token peut correspondre à un mot entier, à une partie d’un mot, à un signe de ponctuation ou à d’autres fragments de texte. Le découpage dépend du tokenizer utilisé par le modèle.
Il faut donc éviter de raisonner uniquement en nombre de mots.
Tout ce que Claude traite consomme des tokens :
- le prompt utilisateur ;
- le
system prompt; - l’historique de la conversation ;
- les documents ajoutés au contexte ;
- les définitions des tools ;
- les
tool_result; - la réponse générée par Claude.
Les tokens ont deux conséquences directes : ils déterminent la quantité d’information que le modèle peut traiter et ils interviennent dans le coût d’utilisation de l’API.
À retenir
Pour une application utilisant Claude, il est préférable de raisonner en tokens, car c’est l’unité utilisée à la fois pour la facturation et pour mesurer la capacité de la context window.
2. La context window : un budget limité
La context window correspond au nombre total de tokens que le modèle peut prendre en compte dans une requête.
Elle contient notamment :
- le
system prompt; - les messages précédents ;
- les documents transmis ;
- les résultats des tools ;
- la réponse que Claude est en train de produire.
On peut donc considérer la context window comme un budget fixe de tokens.
Deux situations différentes peuvent se produire lorsque cette limite est atteinte.
L’entrée dépasse déjà la context window
Si les données envoyées sont trop volumineuses avant même que Claude commence à répondre, la requête est rejetée.
La limite est atteinte pendant la génération
Une requête peut tenir dans la fenêtre au départ, mais atteindre la limite pendant la génération de la réponse.
Dans ce cas, le modèle peut s’arrêter et retourner ce qu’il a déjà généré avec une stop reason indiquant que la limite de contexte a été atteinte.
Conséquence en production
Une conversation longue ne peut pas nécessairement conserver indéfiniment tout son historique.
L’application doit parfois :
- supprimer des messages anciens ;
- résumer une partie de l’historique ;
- ne conserver que les informations réellement utiles.
C’est un point important : les problèmes de context window apparaissent souvent beaucoup plus vite en production qu’en environnement de développement.
3. Sampling : pourquoi Claude ne répond pas toujours exactement de la même manière
Un LLM ne choisit pas systématiquement un unique prochain token.
À chaque étape, il calcule une distribution de probabilités parmi plusieurs tokens possibles, puis sélectionne un token à partir de cette distribution.
C’est ce mécanisme que l’on appelle le sampling.
Cela explique pourquoi le même prompt peut produire deux formulations différentes.
Par exemple, Claude peut répondre :
Le système doit vérifier les paramètres avant d’exécuter le tool.
Puis, avec exactement le même prompt :
L’application doit valider les arguments avant l’appel du tool.
Le sens peut être équivalent, mais la formulation diffère.
Certains modèles permettent ou ont permis de contrôler ce comportement via des paramètres tels que :
temperature, top_p ou top_k.
La prise en charge exacte de ces paramètres dépend toutefois du modèle utilisé et doit être vérifiée dans la documentation actuelle de l’API.
4. Non-déterminisme : une conséquence importante pour les tests
Le sampling implique qu’un LLM est non déterministe.
Autrement dit :
entrée identique ≠ sortie nécessairement identique.
Cela change complètement la manière de tester une fonctionnalité basée sur Claude.
Un test de ce type est fragile :
assert response == "La réponse exacte attendue"
Claude peut fournir une réponse parfaitement correcte avec une formulation différente.
Il vaut mieux vérifier des propriétés mesurables.
Par exemple :
- le JSON est valide ;
- le champ "status" existe ;
- la valeur appartient à une liste autorisée ;
- le résultat contient les informations obligatoires.
Lorsque la qualité dépend du sens de la réponse, les evals deviennent particulièrement importantes.
Une eval peut par exemple vérifier si :
- la réponse respecte les instructions ;
- une information importante a été oubliée ;
- le raisonnement produit un résultat correct ;
- une version de prompt est meilleure qu’une autre.
Principe essentiel
Il faut tester le comportement attendu, et non la formulation exacte produite par le modèle.
5. Choix du modèle et mode de raisonnement : deux décisions différentes
Le choix du modèle et le choix du mode de raisonnement sont deux paramètres conceptuellement distincts.
Le modèle détermine notamment le compromis entre :
- capacités ;
- coût ;
- latence.
Le mode de raisonnement détermine davantage la quantité de travail de raisonnement que le modèle peut consacrer à une requête.
Une tâche simple de classification ne nécessite généralement pas le même niveau de raisonnement qu’un problème complexe impliquant plusieurs étapes.
Exemple
Pour une tâche simple :
Classifie ce ticket dans l’une des catégories suivantes :
BUG, FEATURE, SUPPORT.
Un raisonnement approfondi est probablement inutile.
Pour une tâche plus complexe :
Analyse cette architecture distribuée,
identifie les risques de concurrence,
propose trois stratégies de correction
et compare leurs compromis.
Un mode de raisonnement plus poussé peut être pertinent.
Bonne pratique
Le raisonnement supplémentaire a un coût.
Il doit donc être utilisé lorsque la complexité de la tâche le justifie.
6. Zero-shot, one-shot et multi-shot prompting
Une autre décision importante concerne le nombre d’exemples fournis dans le prompt.
Zero-shot
Aucun exemple n’est fourni.
Classe ce message dans l’une des catégories suivantes :
BUG, FEATURE, SUPPORT.
Cette approche convient lorsque la tâche est simple et suffisamment claire.
One-shot
Un exemple est ajouté.
Exemple :
Entrée :
"L’application plante lorsque je clique sur Enregistrer."
Sortie :
BUG
Classe maintenant le message suivant :
...
L’exemple aide Claude à comprendre précisément le format attendu.
Multi-shot
Plusieurs exemples sont fournis.
Entrée : "L’application plante."
Sortie : BUG
Entrée : "Pouvez-vous ajouter un mode sombre ?"
Sortie : FEATURE
Entrée : "Comment modifier mon mot de passe ?"
Sortie : SUPPORT
Cette approche est également appelée few-shot prompting.
Elle est particulièrement utile lorsque la tâche comporte des nuances ou des cas limites.
7. Le compromis entre exemples, coût et qualité
Chaque exemple ajouté au prompt consomme des tokens.
Il occupe donc une partie de la context window et augmente le coût de chaque requête.
Il faut éviter deux extrêmes :
- fournir trop peu d’informations et obtenir des résultats instables ;
- ajouter de nombreux exemples inutiles.
Une bonne stratégie consiste à commencer avec le prompt le plus simple possible.
Puis :
- tester le résultat ;
- mesurer la qualité avec des evals ;
- ajouter un exemple si nécessaire ;
- mesurer à nouveau.
Un ou deux bons exemples peuvent parfois être plus efficaces qu’un long paragraphe d’instructions.
8. Le choix du modèle et le prompting sont liés
Un modèle plus performant peut parfois réussir une tâche en zero-shot alors qu’un modèle plus léger nécessite plusieurs exemples.
Cela crée un compromis intéressant.
On peut par exemple choisir entre :
Modèle plus performant
+
prompt court
ou :
Modèle moins coûteux
+
quelques exemples supplémentaires
Il n’existe pas de réponse universelle.
La bonne solution est celle qui atteint le niveau de qualité attendu avec un compromis acceptable entre :
- qualité ;
- coût ;
- latence.
Les evals permettent précisément de mesurer ce compromis.
9. Accéder à Claude : SDK ou API REST
Claude est accessible via une API HTTP REST.
Une application peut donc envoyer directement une requête HTTP contenant :
- une clé API ;
- des paramètres ;
- un body JSON.
Puis elle récupère une réponse JSON.
Il est également possible d’utiliser les SDK officiels.
Ils permettent notamment de simplifier :
- l’authentification ;
- la création des requêtes ;
- le parsing des réponses ;
- certains mécanismes de retries.
Conceptuellement :
Application
↓
SDK Anthropic
↓
API REST
↓
Claude
Le SDK ne constitue pas une API différente.
Il fournit une couche d’abstraction pratique au-dessus de la même API.
10. Requêtes synchrones
Le modèle le plus simple consiste à effectuer un appel synchrone.
Application
↓
requête
↓
Claude
↓
réponse complète
↓
Application
L’application attend que Claude ait terminé avant de traiter la réponse.
Cette approche convient notamment :
- aux petites réponses ;
- aux traitements backend ;
- aux tâches où la latence perçue n’est pas critique.
11. Streaming : afficher la réponse pendant sa génération
Pour une réponse longue, attendre l’intégralité de la génération peut donner l’impression que l’application est bloquée.
Le streaming permet de recevoir progressivement les morceaux de réponse.
Le fonctionnement devient :
Claude
↓
fragment 1
fragment 2
fragment 3
fragment 4
↓
Application
L’utilisateur commence donc à voir la réponse avant qu’elle soit terminée.
Claude utilise notamment des Server-Sent Events (SSE) pour transmettre ces événements sur la connexion HTTP.
L’application doit ensuite reconstituer la réponse complète.
12. Async : gérer plusieurs appels sans bloquer l’application
Pour certaines applications, attendre chaque requête l’une après l’autre serait inefficace.
Le SDK Python propose notamment un client asynchrone :
AsyncAnthropic
Il permet d’utiliser async/await.
Cela permet à l’application d’effectuer d’autres traitements pendant qu’elle attend la réponse de Claude.
En TypeScript, le client utilise déjà les Promise, ce qui permet également d’utiliser directement :
await
L’objectif n’est pas de rendre Claude lui-même plus rapide.
L’objectif est de permettre à l’application de gérer efficacement plusieurs opérations concurrentes.
13. Message Batches API : les traitements massifs hors ligne
L’asynchronisme applicatif et le traitement batch répondent à deux besoins différents.
La Message Batches API est destinée aux traitements volumineux qui n’ont pas besoin d’une réponse immédiate.
Le fonctionnement général est le suivant :
Application
↓
soumission d'un ensemble de requêtes
↓
Batch API
↓
traitement
↓
récupération des résultats
Ce type de mécanisme convient particulièrement aux :
- traitements offline ;
- pipelines de données ;
- campagnes d’evals ;
- traitements massifs.
Il est moins adapté lorsqu’un utilisateur attend directement une réponse dans une interface interactive.
14. Les notions essentielles à retenir
Pour développer efficacement avec Claude, plusieurs principes doivent être compris dès le départ.
Les tokens sont l’unité fondamentale du système.
Ils déterminent à la fois le coût et l’utilisation de la context window.
La context window est limitée.
Une application doit gérer son contexte plutôt que conserver indéfiniment tout l’historique.
Claude est non déterministe.
Les tests doivent vérifier des propriétés et des résultats attendus plutôt qu’une formulation exacte.
Zero-shot, one-shot et multi-shot sont des leviers de fiabilité.
Les exemples améliorent souvent les résultats, mais ils ont un coût en tokens.
Le choix du modèle doit être mesuré.
Il faut rechercher le meilleur compromis entre capacités, coût, latence et qualité.
SDK et REST permettent d’accéder à la même API.
Le SDK simplifie principalement le travail du développeur.
Streaming, async et batch répondent à des problèmes différents.
Le streaming améliore l’expérience utilisateur, l’async améliore la concurrence applicative et les batchs sont adaptés aux traitements massifs hors ligne.
Conclusion
Une intégration Claude fiable ne commence pas par un agent complexe ou par une architecture élaborée.
Elle commence par une bonne compréhension des mécanismes fondamentaux du modèle.
Tokens, context window, non-déterminisme, prompting, choix du modèle, streaming et async influencent directement la qualité, le coût et la robustesse d’une application.
Ces notions constituent également la base nécessaire pour comprendre ensuite des concepts plus avancés comme le tool use, les agents, MCP, les evals ou la sécurisation des applications basées sur les LLM.
Récapitulatif : 5 points essentiels à retenir
1. Les tokens sont l’unité d’entrée, de sortie et de coût
Raisonnez et établissez vos budgets en tokens plutôt qu’en mots, car c’est l’unité utilisée par l’API pour mesurer la consommation et par la context window pour déterminer sa capacité.
À retenir : coût et contexte se raisonnent en tokens.
2. La context window est un budget fixe de tokens contenant l’ensemble de la requête
La context window doit contenir tout le contexte nécessaire à l’appel : system prompt, messages, documents, définitions des tools, tool_result et génération du modèle.
Si l’entrée dépasse déjà la limite, la requête échoue avant la génération.
Si la limite est atteinte pendant la génération, la sortie est interrompue et renvoyée avec la stop reason :
model_context_window_exceeded
La gestion de l’historique — suppression, sélection ou résumé des informations — relève donc de l’application.
À retenir : gérer le contexte est une responsabilité applicative.
3. Le sampling rend la génération non déterministe
Un même prompt peut produire des formulations différentes à chaque exécution.
Il est donc peu fiable de tester une application LLM en comparant la réponse à un texte exact.
Il faut plutôt vérifier les propriétés attendues : structure, champs obligatoires, valeurs, respect des contraintes ou qualité sémantique.
C’est précisément l’un des rôles des evals.
À retenir : ne testez pas uniquement le texte produit ; testez le comportement attendu.
4. Le choix du modèle et le mode de raisonnement sont deux leviers distincts et combinables
Choisir un modèle et déterminer la quantité de raisonnement nécessaire sont deux décisions différentes.
L’objectif est d’utiliser le modèle le plus petit et le niveau de raisonnement et de prompting les plus simples qui satisfont vos evals.
N’ajoutez davantage de capacité, de raisonnement ou d’exemples que lorsque les résultats des evals montrent que cela est nécessaire.
À retenir :
Model + Reasoning + Prompting → Eval → Ajustement
La qualité doit être mesurée plutôt que supposée.
5. Un développeur accède à Claude via une API REST, généralement au moyen d’un SDK
Le SDK constitue une couche pratique au-dessus de l’API REST.
Le pattern d’appel doit ensuite être choisi selon les besoins de l’application :
- Synchronous : attendre la réponse complète.
- Streaming : afficher progressivement la réponse lorsqu’un utilisateur attend.
- Async/await : gérer efficacement plusieurs opérations concurrentes sans bloquer l’application.
- Batch : traiter de gros volumes hors ligne lorsqu’aucun utilisateur n’attend immédiatement le résultat.
À retenir : le choix dépend principalement de deux questions : un utilisateur attend-il la réponse ? et le traitement doit-il être réalisé en temps réel ou peut-il être effectué offline ?
Conclusion
Une intégration Claude fiable ne commence pas par un agent complexe ou par une architecture élaborée.
Elle commence par une bonne compréhension des mécanismes fondamentaux du modèle.
Tokens, context window, non-déterminisme, prompting, choix du modèle, streaming et async influencent directement la qualité, le coût et la robustesse d’une application.
Ces notions constituent également la base nécessaire pour comprendre ensuite des concepts plus avancés comme le tool use, les agents, MCP, les evals ou la sécurisation des applications basées sur les LLM.
