D3 · Prompt Engineering and Structured Output

Ce domaine vaut environ 12 des 60 items et correspond aux scénarios Structured Data Extraction et CI/CD. Il traite un prompt comme une conception de système, non une astuce textuelle : structure stable pour le caching, critères de réussite explicites, frontières de contenu claires et — surtout — obtenir du modèle une sortie fiable lisible par machine et la valider. La décision la plus testée est quelle route de sortie structurée utiliser, y compris la restriction de Fable 5.1 qui interdit le forçage du tool choice.

Objectifs d’apprentissage

À la fin de cette page, vous devriez savoir :

1. Traiter un prompt comme un système versionné et modulaire avec un préfixe stable cachable et une séparation des rôles system/user.
2. Écrire des critères de réussite et barèmes explicites et utiliser des balises XML comme frontières de contenu.
3. Sélectionner de bons exemples few-shot et choisir entre chaîne de pensée et extended thinking.
4. Utiliser le prefilling pour orienter la forme de la sortie.
5. Choisir la bonne route de sortie structurée — schéma JSON output_config.format, tool-use-comme-schéma, ou strict tools — y compris la règle Fable 5.1 de non-forçage du tool choice.
6. Concevoir des schémas (enums, required, nullable, descriptions) et bâtir une boucle de reprise sur validation avec retour d’erreur et parsing défensif.
7. Construire des pipelines d’extraction pour des documents hétérogènes avec des métriques par type (anti-pattern 10) et gérer les stop reasons refusal et max_tokens.
8. Concevoir des prompts evaluator-optimizer et éviter l’auto-revue dans la même session (anti-pattern 9).

3.1 Le prompt comme conception de système

Un prompt de production est un artefact d’ingénierie dont les parties changent à des rythmes différents. Ordonnez-les pour que le contenu stable soit placé en premier et puisse être mis en cache.

[ system role ]  stable: role, rules, output contract, tools  ← cache_control here
        +
[ user role ]    variable: the specific task, the document, the question

• Rôles system vs user. Placez les instructions durables, le contrat de sortie et les contraintes dans le prompt system ; placez la tâche spécifique et les données dans les tours user.
• Préfixe stable pour le caching. Les lectures de cache coûtent ~0,1× l’entrée de base ; placez le system prompt, les définitions d’outils et tout long document de référence en premier et marquez le dernier bloc stable avec cache_control: {"type": "ephemeral"}. Préfixe cachable minimum ~1024 tokens (2048 sur Haiku).
• Assemblage modulaire et versionnage. Construisez les prompts à partir de blocs composables (rôle, règles, schéma, exemples) et versionnez-les pour pouvoir évaluer et revenir en arrière. Traitez les changements de prompt comme des changements de code.

system = [
    {"type": "text", "text": ROLE_AND_RULES},                       # stable
    {"type": "text", "text": OUTPUT_CONTRACT},                      # stable
    {"type": "text", "text": REFERENCE_DOC,
     "cache_control": {"type": "ephemeral"}},                       # stable, cache boundary
]
messages = [{"role": "user", "content": task_specific_input}]        # variable

3.2 Critères de réussite et barèmes explicites

Des instructions vagues produisent une sortie vague. Énoncez à quoi ressemble le bon résultat — des critères mesurables et, pour les tâches jugées, un barème.

Les barèmes pilotent aussi les boucles evaluator-optimizer (§3.10) et les evals : l’évaluateur note contre les mêmes critères explicites donnés au générateur.

3.3 Les balises XML comme frontières de contenu

Claude est entraîné à respecter les balises de style XML. Utilisez-les pour séparer les instructions des données et délimiter les régions de sortie — cela réduit le risque d’injection et rend le parsing déterministe.

<instructions>Extract the invoice total. Return only the value.</instructions>
<document>
{ untrusted document text here }
</document>

Envelopper le contenu non fiable dans une balise clairement nommée améliore à la fois la précision et signale au modèle que le texte enclos est des données, non des instructions — une première ligne de défense contre l’injection de prompt indirecte.

3.4 Sélection des exemples few-shot

Les exemples few-shot enseignent le format et la gestion des cas limites. Sélectionnez-les délibérément :

• Représentatifs de la distribution réelle, y compris les cas difficiles/limites qui vous importent.
• Cohérents dans le format — le modèle imite la forme, donc toute incohérence se propage.
• Assez divers pour couvrir les classes, mais pas au point de gonfler le contexte (et le coût).
• Corrects — un mauvais exemple est pire qu’aucun.

Pour l’extraction, un exemple par type de document bat généralement dix exemples d’un seul type.

3.5 Chaîne de pensée vs extended thinking

Sur les modèles actuels le thinking est adaptive ; budget_tokens est retiré sur Fable 5.x / Opus 5 / Sonnet 5 (erreur 400) et seul Haiku 4.5 utilise encore budget_tokens. Les niveaux d’effort sont low | medium | high (default) | xhigh — utilisez xhigh pour le travail de codage/agentique le plus difficile sur Opus 5 / Fable 5.1. Sur Fable 5.1 le thinking est toujours actif.

3.6 Prefilling

Préremplissez le début du tour assistant pour contraindre la forme de la sortie — forcer du JSON, sauter le préambule, ou verrouiller un format.

messages = [
    {"role": "user", "content": "Return the extracted fields."},
    {"role": "assistant", "content": "{"},        # prefill: forces the model to continue JSON
]

Le prefilling est une orientation légère, non une garantie. Pour des garanties fortes utilisez les structured outputs ou les strict tools (ci-après). Note : le prefilling s’articule mal avec l’extended thinking sur les modèles où le thinking doit venir en premier — préférez-y les structured outputs.

3.7 Sortie structurée : les trois routes

C’est la table de décision à plus forte valeur du domaine.

# Route 1: structured outputs via output_config.format
resp = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": f"<document>{doc}</document> Extract fields."}],
    output_config={"format": {"type": "json_schema", "schema": INVOICE_SCHEMA}},
)

# Route 3: strict tool as a schema (works on Fable 5.1 with tool_choice: auto)
tools = [{
    "name": "record_invoice",
    "description": "Record the extracted invoice fields.",
    "strict": True,
    "input_schema": INVOICE_SCHEMA,
}]
resp = client.messages.create(
    model="claude-fable-5-1",
    max_tokens=1024,
    tools=tools,
    tool_choice={"type": "auto"},   # NOT {"type":"tool"} or "any" on Fable 5.1
    messages=[{"role": "user", "content": prompt}],
)

3.8 Conception de schémas

Un bon schéma est auto-documenté et contraignant.

{
  "type": "object",
  "properties": {
    "invoice_number": { "type": "string", "description": "The vendor invoice ID as printed." },
    "total": { "type": "number", "description": "Grand total in the invoice currency." },
    "currency": { "type": "string", "enum": ["USD", "EUR", "GBP"] },
    "due_date": { "type": ["string", "null"], "description": "ISO 8601 date, or null if absent." },
    "line_items": { "type": "array", "items": { "type": "object" } }
  },
  "required": ["invoice_number", "total", "currency"],
  "additionalProperties": false
}

• enum contraint un champ à des valeurs connues (empêche la dérive en texte libre).
• required force la présence ; omettez-en les champs optionnels.
• Nullable via "type": ["string", "null"] — modélisez le cas « absent » explicitement plutôt que d’inviter une valeur hallucinée.
• description sur chaque champ — le modèle les lit ; c’est le levier de précision le moins cher.
• additionalProperties: false garde la sortie serrée.

3.9 Boucle de reprise sur validation et parsing défensif

Même avec des schémas, validez et soyez prêt à réessayer avec un retour d’erreur spécifique.

import json, jsonschema

def extract_with_retry(client, prompt, schema, max_attempts=3):
    messages = [{"role": "user", "content": prompt}]
    for attempt in range(max_attempts):
        resp = client.messages.create(
            model="claude-opus-5", max_tokens=1024, messages=messages,
            output_config={"format": {"type": "json_schema", "schema": schema}},
        )
        if resp.stop_reason == "refusal":
            return {"status": "refused"}                 # ne pas réessayer aveuglément
        if resp.stop_reason == "max_tokens":
            raise OutputTruncated()                      # augmenter max_tokens et réessayer
        text = "".join(b.text for b in resp.content if b.type == "text")
        try:
            data = json.loads(text)                      # parsing défensif
            jsonschema.validate(data, schema)
            return {"status": "ok", "data": data}
        except (json.JSONDecodeError, jsonschema.ValidationError) as e:
            messages.append({"role": "assistant", "content": text})
            messages.append({"role": "user",
                             "content": f"That output failed validation: {e}. "
                                        f"Return only valid JSON matching the schema."})
    return {"status": "failed_validation"}

Points clés : renvoyez l’erreur spécifique pour que le modèle se corrige ; parsez défensivement (jamais eval) ; traitez refusal et max_tokens comme des issues distinctes, non des échecs de validation.

3.10 Pipelines d’extraction pour documents hétérogènes

Lorsque vous extrayez à partir de nombreux types de documents (factures, contrats, reçus), un unique chiffre de précision agrégé masque un type qui échoue lourdement.

                 ┌─► classify type ─┬─► invoice schema  ─► validate ─► metrics[invoice]
Document ─► route ┤                 ├─► contract schema ─► validate ─► metrics[contract]
                 └─────────────────┴─► receipt schema  ─► validate ─► metrics[receipt]
                          per-type accuracy, not one aggregate number

Conception : router par type → appliquer le schéma propre au type → valider → enregistrer les métriques par type. Reportez et alertez par type.

3.11 Gérer refusal et max_tokens

Traiter une sortie max_tokens comme un résultat complet et parsable est un piège de défaillance silencieuse.

3.12 Prompts evaluator-optimizer et indépendance

Pour une boucle générer-critiquer-raffiner, donnez à l’évaluateur le barème explicite et exécutez-le comme un contexte indépendant — une session vierge, idéalement un modèle différent. Réutiliser la conversation génératrice pour se noter elle-même conserve le biais de raisonnement qui a produit le défaut.

3.13 Patrons de conception de schémas pour les cas d’extraction difficiles

Au-delà des enums et des types nullable, plusieurs patrons de schéma décident si l’extraction est fiable sur des documents désordonnés.

{
  "type": "object",
  "oneOf": [
    { "properties": { "doc_type": { "const": "invoice" }, "total": { "type": "number" } },
      "required": ["doc_type", "total"] },
    { "properties": { "doc_type": { "const": "contract" }, "term_months": { "type": "integer" } },
      "required": ["doc_type", "term_months"] }
  ]
}

3.14 Un harnais robuste de reprise sur validation (avec retour d’erreur de schéma)

La boucle correcte à l’examen traite refusal et max_tokens comme des issues distinctes, renvoie l’erreur de validation spécifique, et ne parse jamais de façon non sûre.

import json, jsonschema
from jsonschema import Draft202012Validator

def extract(client, prompt, schema, model="claude-opus-5", max_attempts=3):
    messages = [{"role": "user", "content": prompt}]
    for attempt in range(max_attempts):
        resp = client.messages.create(
            model=model, max_tokens=2048, messages=messages,
            output_config={"format": {"type": "json_schema", "schema": schema}},
        )
        if resp.stop_reason == "refusal":
            return {"status": "refused"}                       # safety stop — do not bypass
        if resp.stop_reason == "max_tokens":
            return {"status": "truncated", "retry": "raise_limit_or_chunk"}  # not complete
        text = "".join(b.text for b in resp.content if b.type == "text")
        try:
            data = json.loads(text)                             # never eval()
            errors = sorted(Draft202012Validator(schema).iter_errors(data),
                            key=lambda e: e.path)
            if not errors:
                return {"status": "ok", "data": data}
            detail = "; ".join(f"{list(e.path)}: {e.message}" for e in errors[:5])
        except json.JSONDecodeError as e:
            detail = f"invalid JSON at pos {e.pos}: {e.msg}"
        messages += [
            {"role": "assistant", "content": text},
            {"role": "user", "content": f"Validation failed: {detail}. "
                                        f"Return ONLY valid JSON matching the schema."},
        ]
    return {"status": "failed_validation"}

import Ajv from 'ajv';
const ajv = new Ajv({ allErrors: true });

async function extract(client, prompt, schema, model = 'claude-opus-5', maxAttempts = 3) {
  const validate = ajv.compile(schema);
  const messages: any[] = [{ role: 'user', content: prompt }];
  for (let i = 0; i < maxAttempts; i++) {
    const resp = await client.messages.create({
      model, max_tokens: 2048, messages,
      output_config: { format: { type: 'json_schema', schema } },
    });
    if (resp.stop_reason === 'refusal') return { status: 'refused' };
    if (resp.stop_reason === 'max_tokens') return { status: 'truncated' }; // not complete
    const text = resp.content.filter(b => b.type === 'text').map(b => b.text).join('');
    try {
      const data = JSON.parse(text);                    // never eval / Function
      if (validate(data)) return { status: 'ok', data };
      const detail = (validate.errors ?? []).slice(0, 5)
        .map(e => `${e.instancePath} ${e.message}`).join('; ');
      messages.push({ role: 'assistant', content: text },
        { role: 'user', content: `Validation failed: ${detail}. Return ONLY valid JSON.` });
    } catch (e) {
      messages.push({ role: 'assistant', content: text },
        { role: 'user', content: `Invalid JSON: ${e}. Return ONLY valid JSON.` });
    }
  }
  return { status: 'failed_validation' };
}

3.15 Calcul de coût et de tokens de la sortie structurée

La sortie structurée n’est pas exempte de coût en tokens, et la verbosité du schéma apparaît sur la facture. Un modèle rapide :

Prompt = system(1,500) + tools/schema(800) + document(6,000) = 8,300 input tokens
Output = ~400 tokens of JSON

On Opus 5 ($5/M in, $25/M out):
  input  = 8,300 × $5  / 1e6 = $0.0415
  output =   400 × $25 / 1e6 = $0.0100
  per doc                     ≈ $0.0515

Cache the stable 2,300-token prefix (system + schema), read ≈ 0.1×:
  cached prefix = 2,300 × $0.5 / 1e6 = $0.00115 (vs $0.0115 uncached)
  → saves ≈ $0.0104 per doc; over 1M docs ≈ $10,400 saved.

Batch API (latency-tolerant) halves the remaining cost → ~$0.026/doc.

Idées reçues fréquentes

Étude de scénario — un pipeline d’extraction qui semble correct mais livre de mauvais contrats

Situation. Un pipeline extrait des champs de factures, contrats et reçus sur Fable 5.1 et écrit dans une base de données. Il reporte 96 % de précision globale, pourtant l’équipe juridique trouve sans cesse de mauvaises durées de contrat. Les ingénieurs forcent tool_choice sur un outil record et voient des 400 intermittents ; quand un gros contrat est traité, le JSON se termine parfois en milieu de tableau et le code écrit l’objet partiel. Une proposition est de « noter les sorties en demandant au modèle, dans le même chat, s’il est confiant ».

Trace de raisonnement d’expert.

1. Corriger d’abord les 400. Fable 5.1 interdit le tool_choice forcé. Basculez vers les structured outputs (output_config.format) ou un outil strict: true avec tool_choice: "auto" plus une instruction. Rejetez « réessayer avec backoff » (un 400 est déterministe) et "any" (aussi bloqué).

2. Corriger la troncature silencieuse. Un JSON se terminant en milieu de tableau avec stop_reason == max_tokens est une troncature, non un résultat. Augmentez max_tokens, ou découpez le contrat (ou bornez line_items avec maxItems), puis réessayez. N’écrivez jamais l’objet partiel.

3. Corriger la métrique. 96 % global masque un type défaillant (#10). Reportez la précision par type de document, alertez sur les contrats, et barrez la mise en production sur le pire type. Rejetez « échantillon plus grand » et « moyenner plus d’exécutions » — les deux agrègent encore.

4. Corriger la conception de l’évaluation. L’auto-confiance dans la même session est du #9 et relève aussi de la confiance auto-déclarée. Utilisez un juge indépendant (session vierge, idéalement un modèle différent) notant contre un barème écrit.

5. Durcir le schéma. Les contrats ont besoin d’une branche d’union discriminée avec term_months en entier typé et d’un nullable + indicateur found pour les clauses optionnelles afin que l’absence ne soit pas hallucinée.

Décision correcte à l’examen : structured outputs / strict tools (non choix forcé), gestion de la troncature par augmentation/découpage, métriques par type barrant sur le pire type, un évaluateur indépendant, et un schéma en union discriminée. Chaque option rejetée est un piège nommé (choix forcé Fable, troncature silencieuse, masquage agrégé #10, même-session #9).

Pièges d’examen dans ce domaine

Questions d’entraînement

Points clés à retenir

• Concevez les prompts comme des systèmes versionnés et modulaires : contenu stable en premier (rôle system, outils, docs) avec cache_control ; tâche variable en dernier.
• Énoncez des critères de réussite et des barèmes explicites ; utilisez des balises XML pour séparer les données non fiables des instructions.
• Choisissez la sortie structurée délibérément : output_config.format pour les garanties de schéma, tool-use-comme-schéma/strict pour l’émission d’enregistrements ; ne forcez jamais tool_choice sur Fable 5.1.
• Concevez les schémas avec enums, required, types nullable, descriptions, unions discriminées et tableaux bornés ; modélisez l’absence avec nullable + un indicateur found.
• Construisez une boucle de reprise sur validation qui renvoie l’erreur de schéma spécifique et parse sûrement (jamais eval) ; traitez refusal et max_tokens comme des issues distinctes.
• Découpez les métriques d’extraction par type de document et barrez sur le pire ; ne faites jamais confiance à un unique chiffre agrégé.
• Contrôlez le raisonnement avec l’adaptive thinking + effort (Opus/Sonnet/Fable) ; seul Haiku 4.5 utilise budget_tokens.
• Exécutez les évaluateurs comme des contextes indépendants ; sur Fable 5.1 gardez le harnais append-only et figez system/tools.
• Pour l’extraction de masse, mettez en cache le préfixe stable schéma/system et utilisez le Batch API (50 % de réduction) — les leviers de coût, non un modèle plus gros.