View a markdown version of this page

Ottieni risultati JSON convalidati dai modelli - Amazon Bedrock
VantaggiCome funzionaFunzionalità dello schema JSON supportateAPI o funzionalità supportateModelli supportatiRichieste di esempio

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Ottieni risultati JSON convalidati dai modelli

Structured outputs è una funzionalità di Amazon Bedrock che garantisce che le risposte dei modelli siano conformi agli schemi JSON e alle definizioni degli strumenti definiti dall'utente, riducendo la necessità di meccanismi di analisi e convalida personalizzati nelle distribuzioni di IA di produzione.

Vantaggi

Gli output strutturati risolvono le sfide critiche nelle applicazioni AI di produzione:

  • Garantisce la conformità dello schema: elimina i tassi di errore e i cicli di ripetizione dovuti agli approcci basati sui prompt

  • Complessità di sviluppo ridotta: elimina la necessità di una logica di analisi e convalida personalizzata

  • Costi operativi ridotti: riduce le richieste e i nuovi tentativi non riusciti

  • Affidabilità della produzione: consente l'implementazione sicura di applicazioni AI che richiedono output prevedibili e leggibili dalla macchina

Come funziona

Gli output strutturati limitano le risposte del modello a seguire uno schema specifico, garantendo un output valido e analizzabile per l'elaborazione a valle. È possibile utilizzare gli output strutturati attraverso due meccanismi complementari:

Formato di output dello schema JSON

Per le InvokeModel API con modelli Anthropic Claude, usa il output_config.format campo di richiesta. Per i modelli a peso aperto, utilizza il campo di response_format richiesta. Per le API Converse, usa il campo di outputConfig.textFormat richiesta. La risposta del modello sarà conforme allo schema JSON specificato.

Uso rigoroso degli strumenti

Aggiungi il strict: true flag alle definizioni degli strumenti per abilitare la convalida dello schema sui nomi e sugli input degli strumenti. Le chiamate agli strumenti del modello seguiranno quindi lo schema di input dello strumento definito.

Questi meccanismi possono essere utilizzati indipendentemente o insieme nella stessa richiesta. Fai riferimento alla documentazione dell'API Bedrock per maggiori dettagli.

Richiedi flusso di lavoro

Quanto segue descrive come Amazon Bedrock elabora le richieste con output strutturati:

  1. Richiesta iniziale: includi uno schema JSON tramite il response_format parametrooutputConfig.textFormat,output_config.format, o una definizione di strumento con il strict: true flag nella tua richiesta di inferenza.

  2. Convalida dello schema: Amazon Bedrock convalida il formato dello schema JSON rispetto al sottoinsieme JSON Schema Draft 2020-12 supportato. Se lo schema contiene funzionalità non supportate, Amazon Bedrock restituisce immediatamente un errore 400.

  3. First-time compilazione: per i nuovi schemi, Amazon Bedrock compila la grammatica, operazione che può richiedere alcuni minuti.

  4. Memorizzazione nella cache: le grammatiche compilate correttamente vengono memorizzate nella cache per 24 ore dal primo accesso. Le grammatiche memorizzate nella cache sono crittografate con chiavi gestite. AWS

  5. Richieste successive: schemi identici dello stesso account utilizzano grammatiche memorizzate nella cache, con conseguente latenza di inferenza paragonabile alle richieste standard con un sovraccarico minimo.

  6. Risposta: ricevi risposte di inferenza standard con una rigorosa conformità allo schema.

Funzionalità dello schema JSON supportate

Sono supportate le seguenti funzionalità JSON Schema Draft 2020-12:

  • Tutti i tipi di base:object,,,array,,string, integer number boolean null

  • enum(solo stringhe, numeri, valori booleani o valori nulli)

  • const,, (con anyOf limitazioniallOf)

  • $ref,$def, e definitions (solo riferimenti interni)

  • Formati di stringa: date-timetime,date,duration,email,hostname,,uri,ipv4,ipv6, uuid

  • Array minItems (solo valori 0 e 1)

Le seguenti funzionalità non sono supportate:

  • Schemi ricorsivi

  • $refRiferimenti esterni

  • Vincoli numerici (minimum,,maximum) multipleOf

  • Vincoli di stringa (,) minLength maxLength

  • additionalPropertiesimpostato su un valore diverso da false

API o funzionalità supportate

Puoi utilizzare output strutturati per le seguenti funzionalità di Amazon Bedrock:

API o funzionalità Supportato Note
Converse e API ConverseStream Sì Inferenza conversazionale.
InvokeModelInvokeModelWithResponseStreame API Sì Single-turn inferenza.
Cross-Region inferenza Sì Funziona senza alcuna configurazione aggiuntiva.
Inferenza in batch Sì Funziona senza alcuna configurazione aggiuntiva.
AnthropicAPI dei messaggi sull'bedrock-mantleendpoint () https://bedrock-mantle.{region}.api.aws/anthropic/v1/messages No Il output_config.format parametro viene rifiutato con un errore 400. Per utilizzare output strutturati con Anthropic Claude i modelli, invia la richiesta tramite l'API Converse o l' InvokeModel API sull'bedrock-runtimeendpoint.
Nota

Gli output strutturati sono incompatibili con le citazioni per i modelli antropici. Se abiliti le citazioni mentre usi gli output strutturati, il modello restituirà un errore 400.

Modelli supportati

Per vedere quali modelli supportano gli output strutturati, accedi subito alla sezione Modelli e seleziona il modello che ti interessa.

Richieste di esempio

Formato di output dello schema JSON

Gli esempi seguenti mostrano come utilizzare il formato di output dello schema JSON con output strutturati.

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 antropico)

{
  "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 modelli)

{
  "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"
  }
}

Uso rigoroso degli strumenti

Gli esempi seguenti mostrano come utilizzare il campo rigoroso con l'uso dello strumento.

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 antropico)

{
  "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 modelli)

{
  "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
}