Paramètres du modèle — API Anthropic — Fondamentaux

Objectifs

Comprendre le rôle de max_tokens
Utiliser temperature pour contrôler les réponses
Maîtriser stop_sequences et le prompt système

Les trois paramètres obligatoires

Vous les avez déjà utilisés sans qu’on s’y attarde : chaque requête à Claude nécessite trois arguments, et l’API refusera l’appel s’il en manque un.

model : le nom du modèle
max_tokens : le nombre maximal de tokens à générer
messages : la liste des messages

Autour de ce socle gravitent des paramètres facultatifs qui changent radicalement le comportement du modèle. Cette leçon leur est consacrée, mais elle commence par la brique qui les sous-tend tous.

Les tokens

Les LLM ne raisonnent pas en mots entiers mais en tokens — des fragments de mots. Pour Claude, un token représente environ 3,5 caractères en anglais, la valeur variant selon la langue : un texte français ou allemand consommera davantage de tokens qu’un texte anglais de longueur équivalente, ce qui a des conséquences directes sur votre facture et sur vos quotas.

Le mécanisme est simple. Quand vous envoyez un prompt, il est d’abord converti en tokens, puis le modèle génère sa réponse un token à la fois, chacun étant choisi en fonction de tout ce qui précède. Cette génération séquentielle explique pourquoi une réponse longue prend mécaniquement plus de temps qu’une réponse courte, et pourquoi tous les paramètres qui suivent agissent, d’une manière ou d’une autre, sur ce flux de tokens.

max_tokens

max_tokens fixe un plafond sur le nombre de tokens que Claude peut générer. C’est une limite haute, pas une consigne de longueur, et cette distinction est la source d’un malentendu tenace. Avec max_tokens=10, la réponse sera brutalement tronquée après dix tokens, souvent au milieu d’un mot, et le stop_reason de la réponse vaudra "max_tokens". Avec une valeur élevée, Claude génère jusqu’à ce qu’il ait fini son propos et le stop_reason vaudra "end_turn". En revanche, augmenter max_tokens ne force pas Claude à générer davantage : cela lui en donne seulement la possibilité. Si vous voulez une réponse plus longue, demandez-la dans le prompt.

Reste à choisir la valeur. Les tokens entrants et sortants comptent dans les limites de votre organisation, un plafond démesuré vous expose donc à saturer vos quotas ; plus Claude génère de tokens, plus la requête prend de temps de calcul ; mais une valeur trop basse produit des réponses tronquées, inutilisables en aval. Estimez la longueur maximale plausible de votre cas d’usage, prenez une marge au-dessus, puis surveillez le stop_reason : s’il revient à "max_tokens", votre estimation était fausse.

stop_sequences

Là où max_tokens coupe sur un décompte, stop_sequences coupe sur un motif. Vous définissez des chaînes de caractères qui, une fois générées, arrêtent immédiatement la génération. L’usage classique consiste à récupérer un objet JSON sans le commentaire que Claude serait tenté d’ajouter après : on s’arrête à l’accolade fermante.

response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=500,
    stop_sequences=["}"],
    messages=[
        {"role": "user", "content": "Génère un objet JSON representant une personne"}
    ]
)

Trois détails d’implémentation vous éviteront des surprises. La séquence d’arrêt n’est pas incluse dans la sortie : dans l’exemple ci-dessus, vous devrez recoller vous-même l’accolade fermante avant de parser le JSON. Le stop_reason vaudra "stop_sequence", ce qui vous permet de distinguer cet arrêt d’une troncature. Et vous pouvez fournir plusieurs séquences d’arrêt : la génération s’interrompt à la première rencontrée.

Température

La temperature contrôle la « créativité » des réponses, sur une échelle allant de 0 à 1. Proche de 0, le modèle privilégie systématiquement le token le plus probable : les réponses deviennent déterministes et prévisibles. Proche de 1, il accepte des continuations moins évidentes, ce qui produit des réponses variées et plus créatives. Comparez les deux appels suivants sur une dizaine d’exécutions et l’effet saute aux yeux.

# Analytique : temperature basse
response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=100,
    temperature=0,
    messages=[{"role": "user", "content": "Nomme un animal"}]
)

# Creatif : temperature haute
response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=100,
    temperature=1,
    messages=[{"role": "user", "content": "Invente un nom de planete alien"}]
)

Avec temperature=0, Claude répond presque toujours la même chose ; avec temperature=1, chaque réponse est différente. La règle pratique en découle : température proche de 0 pour les tâches analytiques — extraction, classification, tout ce que vous devez pouvoir reproduire et tester —, proche de 1 pour les tâches créatives où la répétition serait un défaut.

Le prompt système

Le paramètre system est optionnel et se distingue des messages : il ne fait pas partie de la conversation, il en définit le cadre. Vous y placez des instructions de haut niveau, un rôle, un contexte global.

response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=500,
    system="Tu es un expert en astronomie. Réponds toujours de manière concise.",
    messages=[
        {"role": "user", "content": "Qu'est-ce qu'un trou noir ?"}
    ]
)

Ce cadre s’applique à toute la conversation, quel que soit le nombre de tours échangés ensuite. Réservez-le donc au ton, au contexte et au rôle. Les instructions détaillées, les exemples et les documents à traiter, eux, doivent aller dans le premier message user : c’est là que Claude les traite le mieux, et cela vous évite un prompt système qui enfle jusqu’à devenir illisible.

Mise en pratique

Rassemblez ces paramètres dans une fonction generate_questions(topic, num_questions) qui génère num_questions questions stimulantes sur le topic donné. Utilisez system pour définir un rôle d’expert, max_tokens pour limiter la réponse, et stop_sequences pour arrêter la génération après le bon nombre de questions : si vous en demandez trois, arrêtez-vous à "4.". C’est l’occasion de vérifier que la séquence d’arrêt n’apparaît effectivement pas dans la sortie.