View a markdown version of this page

Obtenez des résultats JSON validés à partir de modèles - Amazon Bedrock
AvantagesComment ça marcheFonctionnalités du schéma JSON prises en chargeAPI ou fonctionnalités prises en chargeModèles pris en chargeExemples de demandes

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Obtenez des résultats JSON validés à partir de modèles

Les sorties structurées sont une fonctionnalité d'Amazon Bedrock qui garantit que les réponses des modèles sont conformes aux schémas JSON définis par l'utilisateur et aux définitions d'outils, réduisant ainsi le besoin de mécanismes d'analyse et de validation personnalisés dans les déploiements d'IA de production.

Avantages

Les sorties structurées répondent aux défis critiques des applications d'IA de production :

  • Garantit la conformité du schéma : élimine les taux d'erreur et les boucles de nouvelles tentatives liés aux approches basées sur des instructions

  • Complexité de développement réduite : élimine le besoin d'une logique d'analyse et de validation personnalisée

  • Réduction des coûts d'exploitation : réduit les demandes infructueuses et les nouvelles tentatives

  • Fiabilité de la production : permet de déployer en toute confiance des applications d'IA nécessitant des résultats prévisibles et lisibles par machine

Comment ça marche

Les sorties structurées obligent les réponses du modèle à suivre un schéma spécifique, garantissant ainsi une sortie valide et analysable pour le traitement en aval. Vous pouvez utiliser des sorties structurées par le biais de deux mécanismes complémentaires :

Format de sortie du schéma JSON

Pour InvokeModel l'API avec les modèles Anthropic Claude, utilisez le champ de output_config.format requête. Pour les modèles de poids ouverts, utilisez le champ de response_format demande. Pour les API Converse, utilisez le champ de outputConfig.textFormat requête. La réponse du modèle sera conforme au schéma JSON spécifié.

Utilisation stricte des outils

Ajoutez l'strict: trueindicateur aux définitions d'outils pour permettre la validation du schéma sur les noms et les entrées des outils. Les appels d'outils du modèle suivront alors le schéma d'entrée d'outil défini.

Ces mécanismes peuvent être utilisés indépendamment ou conjointement dans le cadre d'une même demande. Reportez-vous à la documentation de l'API Bedrock pour plus de détails.

Flux de travail des demandes

Ce qui suit décrit comment Amazon Bedrock traite les demandes avec des sorties structurées :

  1. Demande initiale — Vous incluez soit un schéma JSON via le response_format paramètre outputConfig.textFormatoutput_config.format,, soit une définition d'outil avec l'strict: trueindicateur dans votre demande d'inférence.

  2. Validation du schéma — Amazon Bedrock valide le format de schéma JSON par rapport au sous-ensemble JSON Schema Draft 2020-12 pris en charge. Si le schéma contient des fonctionnalités non prises en charge, Amazon Bedrock renvoie immédiatement une erreur 400.

  3. First-time compilation — Pour les nouveaux schémas, Amazon Bedrock compile la grammaire, ce qui peut prendre quelques minutes.

  4. Mise en cache — Les grammaires correctement compilées sont mises en cache pendant 24 heures à compter du premier accès. Les grammaires mises en cache sont chiffrées à l'aide AWS-managed de clés.

  5. Demandes ultérieures : les schémas identiques provenant du même compte utilisent des grammaires mises en cache, ce qui entraîne une latence d'inférence comparable à celle des demandes standard avec une surcharge minimale.

  6. Réponse — Vous recevez des réponses d'inférence standard respectant strictement le schéma.

Fonctionnalités du schéma JSON prises en charge

Les fonctionnalités suivantes du projet de schéma JSON 2020-12 sont prises en charge :

  • Tous les types de base : objectarray,string,integer,number,boolean, null

  • enum(chaînes, nombres, booléens ou nuls uniquement)

  • const,anyOf, allOf (avec restrictions)

  • $ref$def, et definitions (références internes uniquement)

  • Formats de chaînes : date-time timedate,,duration,email,hostname,uri,ipv4,ipv6, uuid

  • Tableau minItems (valeurs 0 et 1 uniquement)

Les fonctionnalités suivantes ne sont pas prises en charge :

  • Schémas récursifs

  • $refRéférences externes

  • Contraintes numériques (minimum,maximum,multipleOf)

  • Contraintes de chaîne (minLength,maxLength)

  • additionalPropertiesréglé sur une valeur autre que false

API ou fonctionnalités prises en charge

Vous pouvez utiliser des sorties structurées pour les fonctionnalités Amazon Bedrock suivantes :

Converse et ConverseStream API : utilisez des sorties structurées avec Converse et les ConverseStream API pour l'inférence conversationnelle.

InvokeModel et InvokeModelWithResponseStream API : utilisez des sorties structurées avec les InvokeModelWithResponseStream API InvokeModel and pour une inférence en un tour.

Cross-Region inférence — Utilisez des sorties structurées dans le cadre de l'inférence interrégionale sans aucune configuration supplémentaire.

Inférence par lots : utilisez des sorties structurées dans le cadre de l'inférence par lots sans aucune configuration supplémentaire.

API Anthropic Messages sur le bedrock-mantle terminal — Les sorties structurées ne sont pas prises en charge sur le chemin de l'API Anthropic-style Messages (https://bedrock-mantle.{region}.api.aws/anthropic/v1/messages). Le output_config.format paramètre est rejeté avec une erreur 400. Pour utiliser des sorties structurées avec Anthropic Claude des modèles, envoyez la demande via l'API Converse ou l' InvokeModel API du point de bedrock-runtime terminaison.

Note

Les sorties structurées sont incompatibles avec les citations pour les modèles anthropiques. Si vous activez les citations lorsque vous utilisez des sorties structurées, le modèle renverra une erreur de 400.

Modèles pris en charge

Pour savoir quels modèles prennent en charge les sorties structurées, consultez la section Modèles en un coup d'œil et sélectionnez le modèle qui vous intéresse.

Exemples de demandes

Format de sortie du schéma JSON

Les exemples suivants montrent comment utiliser le format de sortie du schéma JSON avec des sorties structurées.

API Converse

{
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "text": "Given the following unstructured data, extract it into the provided structure."
        },
        {
          "text": "..."
        }
      ]
    }
  ],
  "outputConfig": {
    "textFormat": {
      "type": "json_schema",
      "structure": {
        "jsonSchema": {
          "schema": "{\"type\": \"object\", \"properties\": {\"title\": {\"type\": \"string\", \"description\": \"title\"}, \"summary\": {\"type\": \"string\", \"description\": \"summary\"}, \"next_steps\": {\"type\": \"string\", \"description\": \"next steps\"}}, \"required\": [\"title\", \"summary\", \"next_steps\"], \"additionalProperties\": false}",
          "name": "data_extraction",
          "description": "Extract structured data from unstructured text"
        }
      }
    }
  }
}

InvokeModel (Claude anthropique)

{
  "anthropic_version": "bedrock-2023-05-31",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Given the following unstructured data, extract it into the provided structure."
        },
        {
          "type": "text",
          "text": "..."
        }
      ]
    }
  ],
  "max_tokens": 3000,
  "temperature": 1.0,
  "output_config": {
    "format": {
      "type": "json_schema",
      "schema": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string",
            "description": "title"
          },
          "summary": {
            "type": "string",
            "description": "summary"
          },
          "next_steps": {
            "type": "string",
            "description": "next steps"
          }
        },
        "required": [
          "title",
          "summary",
          "next_steps"
        ],
        "additionalProperties": false
      }
    }
  }
}

InvokeModel (Open-weight modèles)

{
  "messages": [
    {
      "role": "user",
      "content": "Given the following unstructured data, extract it into the provided structure."
    },
    {
      "role": "user",
      "content": "..."
    }
  ],
  "inferenceConfig": {
    "maxTokens": 3000,
    "temperature": 1.0
  },
  "response_format": {
    "json_schema": {
      "name": "summarizer",
      "schema": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string",
            "description": "title"
          },
          "summary": {
            "type": "string",
            "description": "summary"
          },
          "next_steps": {
            "type": "string",
            "description": "next steps"
          }
        },
        "required": [
          "title",
          "summary",
          "next_steps"
        ],
        "additionalProperties": false
      }
    },
    "type": "json_schema"
  }
}

Utilisation stricte des outils

Les exemples suivants montrent comment utiliser le champ strict dans le cadre de l'utilisation d'outils.

API Converse

{
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "text": "What's the weather like in New York?"
        }
      ]
    }
  ],
  "toolConfig": {
    "tools": [
      {
        "toolSpec": {
          "name": "get_weather",
          "description": "Get the current weather for a specified location",
          "strict": true,
          "inputSchema": {
            "json": {
              "type": "object",
              "properties": {
                "location": {
                  "type": "string",
                  "description": "The city and state, e.g. San Francisco, CA"
                },
                "unit": {
                  "type": "string",
                  "enum": [
                    "fahrenheit",
                    "celsius"
                  ],
                  "description": "The temperature unit to use"
                }
              },
              "required": [
                "location",
                "unit"
              ]
            }
          }
        }
      }
    ]
  }
}

InvokeModel (Claude anthropique)

{
  "anthropic_version": "bedrock-2023-05-31",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "What's the weather like in San Francisco?"
        }
      ]
    }
  ],
  "max_tokens": 3000,
  "temperature": 1.0,
  "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": [
              "fahrenheit",
              "celsius"
            ],
            "description": "The temperature unit to use"
          }
        },
        "required": [
          "location",
          "unit"
        ],
        "additionalProperties": false
      }
    }
  ]
}

InvokeModel (Open-weight modèles)

{
  "messages": [
    {
      "role": "user",
      "content": "What's the weather like in San Francisco?"
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get the current weather for a specified location",
        "strict": true,
        "parameters": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "The city and state, e.g. San Francisco, CA"
            },
            "unit": {
              "type": "string",
              "enum": [
                "fahrenheit",
                "celsius"
              ],
              "description": "The temperature unit to use"
            }
          },
          "required": [
            "location",
            "unit"
          ]
        }
      }
    }
  ],
  "tool_choice": "auto",
  "max_tokens": 2000,
  "temperature": 1.0
}