Sorties structurées pour les modèles Anthropic Claude sur Amazon Bedrock

Amazon Bedrock prend désormais en charge les sorties structurées pour tous les modèles Anthropic Claude, sur les points de terminaison bedrock-runtime et bedrock-mantle, là où le modèle est disponible.

Que vous appeliez Claude via Boto3 et les API bedrock-runtime ou via l'API Messages et le point de terminaison bedrock-mantle, vous pouvez désormais recevoir des réponses JSON conformes au schéma, respectant une structure définie. Vous n'avez plus besoin d'analyse personnalisée, de logique de nouvelle tentative ni de post-traitement.

Applications pratiques

Avec les sorties structurées pour Claude sur Amazon Bedrock, vous pouvez automatiser des tâches fiables et conformes aux schémas dans tous les secteurs. Les exemples incluent l'extraction de chaque champ requis à partir de rapports financiers et de documents de conformité, l'analyse de notes cliniques pour les Dossiers de Santé Électroniques (DSE) et l'enrichissement de catalogues de produits avec des résultats cohérents et validés. Vous pouvez également analyser des contrats pour en extraire les clauses clés, les parties et les obligations, ou alimenter un routage intelligent des tickets d'assistance où les intentions, les sentiments et les entités correspondent toujours au modèle de données de votre application.

Ce qui change avec les sorties structurées sur Amazon Bedrock

Les sorties structurées utilisent le décodage contraint pour appliquer votre schéma JSON pendant la génération des tokens, et non après coup. Le modèle ne produit pas de tokens qui violeraient votre schéma. Cela transforme le formatage de la sortie de probabiliste en déterministe.

Deux mécanismes complémentaires sont désormais disponibles sur les deux points de terminaison Amazon Bedrock :

Ce que cela signifie pour vous

Chaque réponse est un JSON valide, vous ne rencontrez donc plus d' JSON.parse() erreurs ni d'exceptions d'analyse. Les réponses sont également sûres au niveau des types : les types de champs sont appliqués et les champs obligatoires sont toujours présents. Comme les sorties respectent toujours votre schéma, vous n'avez pas besoin de nouvelles tentatives pour gérer les violations de schéma, ce qui rend votre intégration plus fiable. Les sorties structurées limitent également les réponses aux seuls champs définis par votre schéma, ce qui réduit le nombre de tokens de sortie et peut diminuer les coûts d'inférence pour les charges de travail à fort volume. Ces propriétés rendent les sorties structurées prêtes pour la production, vous permettant ainsi de déployer à grande échelle sans code de validation de schéma supplémentaire.

Modèles pris en charge et disponibilité

Les sorties structurées fonctionnent avec l' inférence par lots, vous pouvez donc traiter de grands volumes de requêtes de manière asynchrone tout en recevant des sorties conformes au schéma. Sur le point de terminaison bedrock-runtime, cela fonctionne également avec l'inférence inter-Régions, vous pouvez donc l'utiliser dans les Régions AWS sans configuration supplémentaire. Si vous avez besoin de réponses en temps réel, vous pouvez diffuser des réponses structurées sous forme d'événements typés.

Fonctionnement

Lorsque vous effectuez une requête avec un schéma JSON, voici ce qui se passe en coulisses :

1. Validation du schéma – Amazon Bedrock valide votre schéma JSON par rapport au sous-ensemble JSON Schema Draft 2020-12 pris en charge.
2. Compilation de la grammaire – Pour les nouveaux schémas, Amazon Bedrock compile un artefact de grammaire (la première requête peut prendre légèrement plus de temps).
3. Mise en cache – Les grammaires compilées sont mises en cache pendant 24 heures, ce qui rend les requêtes suivantes plus rapides.
4. Génération contrainte – Le modèle génère des jetons qui produisent un JSON valide correspondant à votre schéma.

Considérations de performance

Pour des raisons de performance, la première requête avec un nouveau schéma peut prendre plus de temps car Amazon Bedrock compile un artefact de grammaire avant le début de la génération. Après cette compilation initiale, les requêtes suivantes utilisant le même schéma s'exécutent avec une surcharge minimale car la grammaire compilée est mise en cache. Ce cache est limité à votre compte et dure 24 heures à partir du premier accès. Modifier la structure de votre schéma JSON invalide le cache et déclenche une nouvelle compilation, tandis que modifier uniquement les champs name ou description laisse la grammaire en cache intacte.

Premiers pas : sorties structurées avec l'API InvokeModel (bedrock-runtime)

L'API InvokeModel prend le corps de requête natif d'Anthropic, donc le schéma va dans output_config.format en tant qu'objet JSON plutôt qu'en tant que chaîne JSON. L'exemple suivant montre comment extraire les données structurées d'un prospect à partir d'un e-mail client à l'aide de boto3 avec un modèle Anthropic Claude :

Python

import boto3
import json

REGION = "us-east-1" # Choose your preferred region
bedrock_runtime = boto3.client(service_name="bedrock-runtime", region_name=REGION)

# Define the JSON schema for structured output
schema = {
    "type": "object",
    "properties": {
        "name": {"type": "string", "description": "Customer name"},
        "email": {"type": "string", "description": "Customer email address"},
        "plan_interest": {"type": "string", "description": "Product plan of interest"},
        "demo_requested": {"type": "boolean", "description": "Whether a demo was requested"}
    },
    "required": ["name", "email", "plan_interest", "demo_requested"],
    "additionalProperties": False
}

# Make a request with structured outputs via the InvokeModel API
# (reusing the schema defined for the Converse example)
response = bedrock_runtime.invoke_model(
    modelId="global.anthropic.claude-sonnet-5-5",
    body=json.dumps({
        "anthropic_version": "bedrock-2023-05-31",
        "max_tokens": 512,
        "messages": [
            {"role": "user", "content": (
                "Paulo Santos (paulo@example.com) is interested in our Enterprise plan "
                "and wants to schedule a demo for next Tuesday at 2pm."
            )}
        ],
        "output_config": {"format": {"type": "json_schema", "schema": schema}}
    })
)

body = json.loads(response["body"].read())

# Check the stop reason before parsing
if body["stop_reason"] == "end_turn":
    result_text = next(b["text"] for b in body["content"] if b["type"] == "text")
    print(json.dumps(json.loads(result_text), indent=2))
elif body["stop_reason"] == "max_tokens":
    print("Response truncated: increase max_tokens and retry.")

JSON

{
    "name": "Paulo Santos",
    "email": "paulo@example.com",
    "plan_interest": "Enterprise",
    "demo_requested": true
}

La réponse est conforme à votre schéma. Aucune validation supplémentaire n'est requise.

Pour d’autres exemples d’utilisation de l’API, y compris l’API Messages, consultez le exemple de notebook.

Utilisation stricte des outils pour les flux de travail agentiques

Amazon Bedrock Mantle est conçu pour les applications agentiques avec des outils côté serveur, l’inférence en arrière-plan et des conversations avec état. Avec l’utilisation stricte des outils sur le point de terminaison bedrock-mantle, vous pouvez désormais garantir que les paramètres d’outil correspondent exactement à votre schéma d’entrée. L’exemple suivant montre comment définir un outil avec application stricte du schéma :

Import json
from anthropic import AnthropicBedrockMantle

# Reusing the client created in the Messages API example
client = AnthropicBedrockMantle(aws_region="us-east-1")

message = client.messages.create(
    model="anthropic.claude-sonnet-5",
    max_tokens=512,
    messages=[{"role": "user", "content": "What's the weather like in San Francisco?"}],
    tools=[
        {
            "name": "get_weather",
            "description": "Get the current weather for a specified location",
            "strict": True,
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "The city and state, e.g., San Francisco, CA"
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"],
                        "description": "Temperature unit"
                    }
                },
                "required": ["location", "unit"],
                "additionalProperties": False
            }
        }
    ]
)

#Tool inputs conform to the schema
for block in message.content:
    if block.type == "tool_use":
        print(f"Tool: {block.name}")
        print(f"Input: {json.dumps(block.input, indent=2)}")

Le paramètre strict: true contraint l’entrée d’outil du modèle à correspondre exactement à votre schéma. Le champ location est toujours une chaîne, et le champ unit est toujours soit celsius soit fahrenheit. Le modèle ne peut pas ajouter de champs en dehors de votre schéma, de sorte que l’entrée d’outil contient uniquement ce que votre schéma spécifie.

Ceci est particulièrement précieux pour les cas d’usage agentiques sur Amazon Bedrock Mantle, où les modèles orchestrent des flux de travail en plusieurs étapes avec des outils côté serveur comme la recherche web et l’interpréteur de code.

Principaux cas d’usage des sorties structurées de Claude

Les sorties structurées réduisent le plus la complexité de la gestion des erreurs dans trois schémas courants :

• Extraction de données : Extrayez des champs de factures, de contrats, d’e-mails et de transcriptions vers un JSON qui correspond toujours à votre schéma, prêt à être chargé dans des bases de données ou des systèmes de gestion de la relation client (CRM).
• Appels d’outils d’agent fiables : Validez les arguments d’outil par rapport à leurs schémas au moment de la génération, afin que les flux de travail d’agent en plusieurs étapes s’exécutent sans échecs dus à une entrée mal formée.
• Classification à grande échelle : Classez les tickets, les prospects ou le contenu par intention, priorité et sentiment pour le routage, la modération et l’évaluation.

Claude Haiku 5.5 gère de manière fiable les charges de travail rapides et répétitives telles que les résumés, les compactages, les requêtes de base de données et les demandes de classification. L’exemple suivant montre comment classifier et acheminer les données entrantes à l’aide de l’API Invoke et de Haiku 5.5 :

import boto3
import json

REGION = "us-east-1" # Choose your preferred region
bedrock_runtime = boto3.client(service_name="bedrock-runtime", region_name=REGION)

# Classification schema: enums restrict output to a fixed set of labels
schema = {
    "type": "object",
    "properties": {
        "category": {
            "type": "string",
            "enum": ["billing", "technical", "account", "sales", "other"],
            "description": "Primary ticket category"
        },
        "priority": {
            "type": "string",
            "enum": ["low", "medium", "high", "urgent"],
            "description": "Urgency based on business impact"
        },
        "sentiment": {
            "type": "string",
            "enum": ["positive", "neutral", "negative"],
            "description": "Customer sentiment"
        },
        "escalate": {"type": "boolean", "description": "Whether a human should review immediately"},
        "reason": {"type": "string", "description": "One-sentence justification for the classification"}
    },
    "required": ["category", "priority", "sentiment", "escalate", "reason"],
    "additionalProperties": False
}

ticket = (
    "Our production API calls have been failing with 500 errors since this morning. "
    "We're losing orders every minute. This is the second outage this month!"
)

# Make a request with structured outputs via the InvokeModel API
response = bedrock_runtime.invoke_model(
    modelId="global.anthropic.claude-haiku-5-5",
    body=json.dumps({
        "anthropic_version": "bedrock-2023-05-31",
        "max_tokens": 512,
        "system": "You are a support ticket classifier. Classify the ticket accurately.",
        "messages": [
            {"role": "user", "content": f"Classify this support ticket:\n\n{ticket}"}
        ],
        "output_config": {"format": {"type": "json_schema", "schema": schema}}
    })
)

body = json.loads(response["body"].read())

# Check the stop reason before parsing
if body["stop_reason"] == "end_turn":
    result_text = next(b["text"] for b in body["content"] if b["type"] == "text")
    result = json.loads(result_text)
    print(json.dumps(result, indent=2))
    # Route the ticket based on the guaranteed-valid labels
    if result["escalate"]:
        print(f"Escalating to on-call: {result['category']} / {result['priority']}")
elif body["stop_reason"] == "max_tokens":
    print("Response truncated: increase max_tokens and retry.")

Exigences et bonnes pratiques

Pour utiliser efficacement les sorties structurées sur Amazon Bedrock, suivez ces recommandations :

1. Définissez additionalProperties: false sur tous les objets: ceci est requis pour que les sorties structurées fonctionnent. Sans cela, votre schéma ne sera pas accepté.
2. Utilisez des noms de champs et des descriptions explicites: les modèles utilisent les noms de propriétés et les descriptions pour comprendre quelles données extraire. Des noms clairs comme customer_email sont plus performants que des noms génériques comme field1.
3. Utilisez enum pour les valeurs contraintes: lorsqu’un champ a un ensemble limité de valeurs valides, utilisez enum pour contraindre les options.
4. Commencez simplement, puis ajoutez de la complexité: Commencez avec les champs minimum requis et ajoutez de la complexité de manière incrémentale. Les schémas basiques compilent plus rapidement, sont plus faciles à déboguer et gardent votre charge utile de requête légère, car le schéma compte dans la taille de charge utile de l'API Converse.
5. Réutilisez les schémas pour bénéficier de la mise en cache: Structurez votre application pour réutiliser les schémas entre les requêtes. Le cache de grammaire de 24 heures améliore les performances pour les requêtes répétées.
6. Vérifiez la raison d'arrêt dans chaque réponse: Deux scénarios peuvent produire des réponses non conformes : les refus (lorsque le modèle décline pour des raisons de sécurité) et les limites de jetons (lorsque max_tokens est atteinte avant la fin). Gérez ces deux cas dans votre code.
7. Testez avec des données réalistes avant le déploiement: Validez vos schémas avec des entrées représentatives de la production. Les cas particuliers dans les données réelles révèlent souvent des problèmes de conception de schéma.

Pour des bonnes pratiques supplémentaires et des recommandations de conception de schémas, consultez Structured outputs dans le Amazon Bedrock User Guide.

Fonctionnalités JSON Schema prises en charge

1. Tous les types de base : object, array, string, integer, number, boolean, null.
2. enum (chaînes, nombres, booléens ou nulls uniquement).
3. const, anyOf, allOf (avec des limitations).
4. $ref, $def, et definitions (références internes uniquement).
5. Formats de chaînes : date-time, time, date, duration, email, hostname, uri, ipv4, ipv6, uuid.
6. Tableau minItems (uniquement les valeurs 0 et 1).

Non pris en charge

Ces mots-clés sont acceptés par l'API mais ne sont pas appliqués pendant la génération. Une requête qui les inclut renvoie une réponse réussie, et le modèle peut toujours renvoyer des valeurs qui les violent. Validez ces contraintes dans votre application plutôt que de vous fier au schéma pour les appliquer.

1. Schémas récursifs.
2. références $ref externes.
3. Contraintes numériques (minimum, maximum, multipleOf).
4. Contraintes de chaîne (minLength, maxLength).
5. additionalProperties défini sur autre chose que false.

Conclusion

Les sorties structurées pour les modèles Anthropic Claude sur Amazon Bedrock offrent la fiabilité qu'exigent les applications d'IA en production. Elles sont disponibles dès maintenant sur les points de terminaison bedrock-runtime et bedrock-mantle. En combinant le format de sortie JSON Schema et l'utilisation stricte d'outils, vous pouvez créer des pipelines de données qui ne nécessitent aucune validation supplémentaire. Vous pouvez également créer des flux de travail agentiques fiables et des applications d'IA en production sans logique d'analyse ni de réessai personnalisée.

Les sorties structurées pour Claude sur Amazon Bedrock sont désormais généralement disponibles. Pour en savoir plus, consultez la documentation Amazon Bedrock et explorez notre notebook d'exemple.

Quels flux de travail un JSON validé et conforme au schéma pourrait-il améliorer dans votre organisation ? Partagez vos retours et vos questions dans les commentaires.

À propos des auteurs