View a markdown version of this page

Obtenha resultados JSON validados a partir de modelos - Amazon Bedrock
BenefíciosComo funcionaRecursos compatíveis do esquema JSONAPIs ou recursos compatíveisModelos compatíveisExemplo de solicitações

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Obtenha resultados JSON validados a partir de modelos

As saídas estruturadas são um recurso do Amazon Bedrock que garante que as respostas do modelo estejam em conformidade com os esquemas JSON e as definições de ferramentas definidos pelo usuário, reduzindo a necessidade de mecanismos personalizados de análise e validação nas implantações de IA de produção.

Benefícios

As saídas estruturadas abordam desafios críticos em aplicativos de IA de produção:

  • Garante a conformidade do esquema — elimina as taxas de erro e os ciclos de repetição a partir de abordagens baseadas em prompts

  • Complexidade de desenvolvimento reduzida — elimina a necessidade de lógica personalizada de análise e validação

  • Custos operacionais mais baixos — reduz as falhas nas solicitações e novas tentativas

  • Confiabilidade de produção — permite a implantação confiável de aplicativos de IA que exigem saídas previsíveis e legíveis por máquina

Como funciona

As saídas estruturadas restringem as respostas do modelo a seguirem um esquema específico, garantindo uma saída válida e analisável para processamento posterior. Você pode usar saídas estruturadas por meio de dois mecanismos complementares:

Formato de saída do esquema JSON

Para InvokeModel API com modelos Anthropic Claude, use o campo de output_config.format solicitação. Com modelos de peso aberto, use o campo de response_format solicitação. Para APIs Converse, use o campo de outputConfig.textFormat solicitação. A resposta do modelo estará em conformidade com o esquema JSON especificado.

Uso estrito de ferramentas

Adicione o strict: true sinalizador às definições da ferramenta para permitir a validação do esquema em nomes e entradas de ferramentas. As chamadas de ferramentas do modelo seguirão então o esquema de entrada de ferramentas definido.

Esses mecanismos podem ser usados de forma independente ou em conjunto na mesma solicitação. Consulte a documentação da API Bedrock para obter mais detalhes.

Solicitar fluxo de trabalho

A seguir, descrevemos como o Amazon Bedrock processa solicitações com saídas estruturadas:

  1. Solicitação inicial — Você inclui um esquema JSON por meio do response_format parâmetro outputConfig.textFormatoutput_config.format, ou uma definição de ferramenta com o strict: true sinalizador em sua solicitação de inferência.

  2. Validação do esquema — O Amazon Bedrock valida o formato do esquema JSON em relação ao subconjunto JSON Schema Draft 2020-12 compatível. Se o esquema contiver recursos não compatíveis, o Amazon Bedrock retornará um erro 400 imediatamente.

  3. First-time compilação — Para novos esquemas, o Amazon Bedrock compila a gramática, o que pode levar alguns minutos.

  4. Armazenamento em cache — As gramáticas compiladas com sucesso são armazenadas em cache por 24 horas a partir do primeiro acesso. As gramáticas em cache são criptografadas com chaves AWS gerenciadas.

  5. Solicitações subsequentes — Esquemas idênticos da mesma conta usam gramáticas em cache, resultando em latência de inferência comparável às solicitações padrão com sobrecarga mínima.

  6. Resposta — Você recebe respostas de inferência padrão com estrita conformidade com o esquema.

Recursos compatíveis do esquema JSON

Os seguintes recursos do JSON Schema Draft 2020-12 são suportados:

  • Todos os tipos básicos:object,array,string,integer,number,boolean, null

  • enum(somente cadeias de caracteres, números, booleanos ou nulos)

  • const,anyOf, allOf (com limitações)

  • $ref,$def, e definitions (somente referências internas)

  • Formatos de sequência de caracteres: date-time time date durationemail,hostname,,uri,ipv4,ipv6, uuid

  • Matriz minItems (somente valores 0 e 1)

Os seguintes recursos não são suportados:

  • Esquemas recursivos

  • $refReferências externas

  • Restrições numéricas (minimum,,maximum) multipleOf

  • Restrições de string (minLength,maxLength)

  • additionalPropertiesdefinido para qualquer coisa diferente de false

APIs ou recursos compatíveis

Você pode usar saídas estruturadas nos seguintes recursos do Amazon Bedrock:

API ou recurso Suportado Observações
Converse e APIs ConverseStream Sim Inferência conversacional.
InvokeModele InvokeModelWithResponseStream APIs Sim Single-turn inferência.
Cross-Region inferência Sim Funciona sem nenhuma configuração adicional.
Inferência em lote Sim Funciona sem nenhuma configuração adicional.
AnthropicAPI de mensagens no bedrock-mantle endpoint () https://bedrock-mantle.{region}.api.aws/anthropic/v1/messages Não O output_config.format parâmetro é rejeitado com um erro 400. Para usar saídas estruturadas com Anthropic Claude modelos, envie a solicitação por meio da API Converse ou da InvokeModel API no bedrock-runtime endpoint.
nota

Os resultados estruturados são incompatíveis com as citações de modelos antrópicos. Se você habilitar as citações ao usar saídas estruturadas, o modelo retornará um erro 400.

Modelos compatíveis

Para ver quais modelos suportam saídas estruturadas, acesse os modelos rapidamente e selecione o modelo em que você está interessado.

Exemplo de solicitações

Formato de saída do esquema JSON

Os exemplos a seguir mostram como usar o formato de saída do esquema JSON com saídas estruturadas.

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 antrópico)

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

{
  "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 estrito de ferramentas

Os exemplos a seguir mostram como usar o campo estrito com o uso da ferramenta.

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 antrópico)

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

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