Uma mudança fundamental na geração de JSON estruturado
A AWS anunciou uma novidade no Amazon Bedrock que redefine como os desenvolvedores trabalham com respostas estruturadas de modelos de inteligência artificial. A capacidade de saídas estruturadas representa um avanço significativo: pela primeira vez, é possível garantir que as respostas JSON dos modelos de fundação estejam sempre em conformidade com um esquema especificado, através de decodificação restrita.
Essa transformação muda fundamentalmente a arquitetura dos aplicativos. Em vez de criar elaborados sistemas de validação, tratamento de erros e lógica de reprocessamento quando a IA retorna dados mal formatados, os desenvolvedores agora podem construir com confiança, sabendo que cada resposta respeitará exatamente o formato esperado.
Os casos de uso potenciais são diversos: pipelines de extração de dados sem necessidade de validação, sistemas de agentes de IA que chamam funções externas com segurança, e arquiteturas de aplicação simplificadas que dispensam lógica de retry. Um notebook Jupyter companion fornece exemplos práticos para todas as funcionalidades abordadas.
Os desafios tradicionais com geração de JSON
Historicamente, obter dados estruturados de modelos de linguagem era um processo frágil. Os desenvolvedores precisavam elaborar prompts detalhados, esperar pelo melhor resultado e construir sistemas complexos de tratamento de erros. Mesmo com prompts cuidadosamente preparados, problemas recorrentes surgem:
- Falhas de análise: JSON sintaticamente inválido que quebra chamadas de json.loads()
- Campos ausentes: Pontos de dados necessários não retornam nas respostas
- Incompatibilidades de tipo: Strings onde inteiros são esperados, quebra processamento downstream
- Violações de esquema: Respostas que tecnicamente são JSON válido, mas não correspondem ao modelo de dados esperado
Em sistemas em produção, esses problemas se multiplicam. Uma única resposta malformada pode atravessar um pipeline inteiro, exigindo reprocessamentos que aumentam latência e custos. Para fluxos de trabalho com agentes, parâmetros inválidos podem quebrar completamente chamadas de função.
Considere um exemplo concreto: um sistema de reservas que necessita do campo passageiros: int. Sem imposição de esquema, o modelo pode retornar passageiros: "dois" ou passageiros: "2"—ambos são JSON sintaticamente válido, mas semanticamente incorretos para a assinatura da função.
Como as saídas estruturadas transformam a situação
As saídas estruturadas no Amazon Bedrock não representam uma melhoria incremental—trata-se de um deslocamento fundamental de formatação probabilística para determinística. Através de decodificação restrita, o Bedrock força as respostas do modelo a estarem em conformidade com o esquema JSON especificado.
Dois mecanismos complementares estão disponíveis:
- Formato de saída JSON Schema: Controla o formato da resposta do modelo. Ideal para extração de dados, geração de relatórios e respostas prontas para APIs.
- Uso de ferramenta restrita: Valida parâmetros de ferramentas. Essencial para fluxos de trabalho com agentes, chamadas de função e automação em múltiplas etapas.
Essas funcionalidades podem ser usadas independentemente ou em conjunto, oferecendo controle preciso sobre tanto o que o modelo retorna quanto como chama suas funções.
Os benefícios entregues são significativos:
- Sempre válido: Sem erros de JSON.parse() ou exceções de análise
- Type-safe: Tipos de campos são impostos e campos obrigatórios sempre estão presentes
- Confiável: Sem necessidade de reprocessamentos por violações de esquema
- Pronto para produção: Deploy com confiança em escala empresarial
O funcionamento técnico das saídas estruturadas
As saídas estruturadas utilizam amostragem restrita com artefatos de gramática compilados. Quando uma requisição é feita, o Bedrock executa as seguintes etapas:
- Validação de esquema: O Amazon Bedrock valida o esquema JSON contra um subconjunto suportado do JSON Schema Draft 2020-12
- Compilação de gramática: Para esquemas novos, o Bedrock compila uma gramática (a primeira requisição pode levar mais tempo)
- Cache: Gramáticas compiladas são mantidas em cache por 24 horas, acelerando requisições subsequentes
- Geração restrita: O modelo gera tokens que produzem JSON válido correspondendo ao esquema
Considerações de desempenho
A latência inicial é um fator importante a considerar. A compilação inicial pode adicionar latência para esquemas novos. Entretanto, requisições subsequentes com esquemas idênticos têm overhead mínimo, pois a gramática compilada permanece em cache.
O escopo do cache é por conta, durando 24 horas a partir do primeiro acesso. Alterar a estrutura do esquema JSON ou do esquema de entrada de uma ferramenta invalida o cache, mas modificar apenas nomes ou campos de descrição não.
Começando com saídas estruturadas
O seguinte exemplo demonstra saídas estruturadas usando a Converse API:
import boto3
import json
# Initialize the Bedrock Runtime client
bedrock_runtime = boto3.client(
service_name='bedrock-runtime',
region_name='us-east-1' # Choose your preferred region
)
# Define your JSON schema
extraction_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 the request with structured outputs
response = bedrock_runtime.converse(
modelId="us.anthropic.claude-opus-4-5-20251101-v1:0",
messages=[
{
"role": "user",
"content": [
{
"text": "Extract the key information from this email: John Smith (john@example.com) is interested in our Enterprise plan and wants to schedule a demo for next Tuesday at 2pm."
}
]
}
],
inferenceConfig={
"maxTokens": 1024
},
outputConfig={
"textFormat": {
"type": "json_schema",
"structure": {
"jsonSchema": {
"schema": json.dumps(extraction_schema),
"name": "lead_extraction",
"description": "Extract lead information from customer emails"
}
}
}
}
)
# Parse the schema-compliant JSON response
result = json.loads(response["output"]["message"]["content"][0]["text"])
print(json.dumps(result, indent=2))
A saída obtida está em conformidade total com o esquema—sem validação adicional necessária:
{
"name": "John Smith",
"email": "john@example.com",
"plan_interest": "Enterprise",
"demo_requested": true
}
Requisitos e melhores práticas
Para utilizar saídas estruturadas efetivamente, algumas orientações devem ser seguidas:
Configuração de esquema obrigatória
Configure additionalProperties: false em todos os objetos. Essa é uma configuração necessária para que saídas estruturadas funcionem. Sem ela, o esquema não será aceito:
{
"type": "object",
"properties": {
"name": {"type": "string"}
},
"required": ["name"],
"additionalProperties": false
}
Nomes e descrições descritivas
Use nomes de propriedade e descrições claros. Os modelos utilizam nomes de propriedades e descrições para compreender quais dados extrair. Nomes descritivos como customer_email têm melhor desempenho do que nomes genéricos como field1.
Enumerações para valores restritos
Quando um campo possui um conjunto limitado de valores válidos, use enum para restringir opções. Isso melhora a precisão e garante valores válidos.
Incrementalismo na construção
Comece com os campos mínimos necessários e adicione complexidade gradualmente. Esquemas básicos compilam mais rapidamente e são mais fáceis de manter.
Reutilização de esquemas
Estruture sua aplicação para reutilizar esquemas entre requisições. O cache de gramática de 24 horas melhora significativamente o desempenho para consultas repetidas.
Verificação de stopReason
Verifique stopReason em cada resposta. Dois cenários podem produzir respostas não conformes: recusas (quando o modelo declina por razões de segurança) e limites de token (quando max_tokens é atingido antes da conclusão). Trate ambos os casos no seu código.
Teste com dados realistas
Valide seus esquemas contra inputs representativos de produção. Casos extremos em dados reais frequentemente revelam problemas de design de esquema.
Recursos JSON Schema suportados
Os seguintes recursos são suportados:
- Todos os tipos básicos: object, array, string, integer, number, boolean, null
- enum (strings, números, booleanos ou nulls apenas)
- const, anyOf, allOf (com limitações)
- $ref, $def e definitions (apenas referências internas)
- Formatos de string: date-time, time, date, duration, email, hostname, uri, ipv4, ipv6, uuid
- Array minItems (apenas valores 0 e 1)
Não suportados: Esquemas recursivos, referências externas de $ref, restrições numéricas (minimum, maximum, multipleOf), restrições de string (minLength, maxLength), additionalProperties definido como qualquer valor diferente de false.
Uso restrito de ferramentas para fluxos de trabalho com agentes
Ao construir aplicações onde modelos chamam ferramentas, configure strict: true na definição da ferramenta para restringir parâmetros de ferramentas a corresponderem exatamente com seu esquema de entrada:
import boto3
import json
bedrock_runtime = boto3.client('bedrock-runtime', region_name='us-east-1')
response = bedrock_runtime.converse(
modelId="us.anthropic.claude-opus-4-5-20251101-v1:0",
messages=[
{
"role": "user",
"content": [{"text": "What's the weather like in San Francisco?"}]
}
],
inferenceConfig={"maxTokens": 1024},
toolConfig={
"tools": [
{
"toolSpec": {
"name": "get_weather",
"description": "Get the current weather for a specified location",
"strict": True, # Enable strict mode
"inputSchema": {
"json": {
"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 content_block in response["output"]["message"]["content"]:
if "toolUse" in content_block:
tool_input = content_block["toolUse"]["input"]
print(f"Tool: {content_block['toolUse']['name']}")
print(f"Input: {json.dumps(tool_input, indent=2)}")
Com strict: true, as saídas estruturadas garantem que:
- O campo location é sempre uma string
- O campo unit é sempre celsius ou fahrenheit
- Nenhum campo inesperado aparece na entrada
Aplicações práticas em diversos setores
Os exemplos e notebooks demonstram casos de uso que atravessam múltiplas indústrias:
- Serviços financeiros: Extrair dados estruturados de relatórios de earnings, aplicações de crédito e documentos de conformidade. Com saídas estruturadas, todos os campos obrigatórios estão presentes e corretamente tipados para processamento downstream.
- Healthcare: Analisar notas clínicas em registros estruturados conformes com esquema. Extrair informações de pacientes, diagnósticos e planos de tratamento em JSON validado para integração com sistemas EHR.
- Ecommerce: Construir pipelines confiáveis de enriquecimento de catálogo de produtos. Extrair especificações, categorias e atributos de descrições de produtos com resultados consistentes e confiáveis.
- Legal: Analisar contratos e extrair termos-chave, partes, datas e obrigações em formatos estruturados adequados para sistemas de gerenciamento de contratos.
- Atendimento ao cliente: Construir sistemas inteligentes de roteamento de tickets e resposta, onde intents extraídos, sentimentos e entidades correspondem ao modelo de dados da aplicação.
Escolhendo a abordagem correta
Os testes revelaram padrões claros sobre quando usar cada funcionalidade:
Use JSON Schema output format quando:
- Você precisa da resposta do modelo em uma estrutura específica
- Construindo pipelines de extração de dados
- Gerando respostas prontas para API
- Criando relatórios ou resumos estruturados
Use strict tool use quando:
- Construindo sistemas de agentes que chamam funções externas
- Implementando fluxos de trabalho multi-etapas com cadeias de ferramentas
- Exigindo tipos de parâmetro validados para chamadas de função
- Conectando IA a bancos de dados, APIs ou serviços externos
Use ambos em conjunto quando:
- Construindo agentes complexos que precisam de chamadas de ferramenta validadas e respostas finais estruturadas
- Criando sistemas onde resultados de ferramentas intermediárias alimentam saídas estruturadas
- Implementando fluxos de trabalho empresariais exigindo conformidade de esquema de ponta a ponta
Comparação de APIs: Converse versus InvokeModel
Tanto a Converse API quanto a InvokeModel API suportam saídas estruturadas, com formatos de parâmetro ligeiramente diferentes:
| Aspecto |
Converse API |
InvokeModel (Anthropic Claude) |
InvokeModel (modelos open-weight) |
| Localização do esquema |
outputConfig.textFormat |
output_config.format |
response_format |
| Flag strict de ferramenta |
toolSpec.strict |
tools[].strict |
tools[].function.strict |
| Formato de esquema |
String JSON em jsonSchema.schema |
Objeto JSON em schema |
Objeto JSON em json_schema.schema |
| Melhor para |
Fluxos de trabalho conversacionais |
Inferência single-turn (Claude) |
Inferência single-turn (open-weight) |
Nota: A InvokeModel API utiliza nomes de campos de requisição diferentes dependendo do tipo de modelo. Para modelos Anthropic Claude, use output_config.format para saídas JSON schema. Para modelos open-weight, use response_format em seu lugar.
Escolha a Converse API para conversas multi-turn e a InvokeModel API quando você necessita acesso direto ao modelo com formatos de requisição específicos do provedor.
Modelos suportados e disponibilidade
Saídas estruturadas está geralmente disponível em todas as regiões comerciais da AWS para provedores de modelo Amazon Bedrock selecionados:
- Anthropic
- DeepSeek
- Google
- MiniMax
- Mistral AI
- Moonshot AI
- NVIDIA
- OpenAI
- Qwen
A funcionalidade funciona perfeitamente com:
- Inferência entre regiões: Use saídas estruturadas entre regiões da AWS sem configuração adicional
- Inferência em lote: Processe grandes volumes com saídas conformes com esquema
- Streaming: Transmita respostas estruturadas com ConverseStream ou InvokeModelWithResponseStream
Conclusão
A capacidade de saídas estruturadas no Amazon Bedrock reduz significativamente a incerteza da geração de JSON por IA através de respostas validadas e conformes com esquema. Utilizando formato de saída JSON Schema e uso restrito de ferramentas, os desenvolvedores podem construir pipelines confiáveis de extração de dados, fluxos de trabalho robustos com agentes e aplicações de IA prontas para produção—sem lógica personalizada de análise ou validação.
Seja extraindo dados de documentos, construindo automação inteligente ou criando APIs alimentadas por IA, as saídas estruturadas entregam a confiabilidade que suas aplicações exigem.
Saídas estruturadas está agora geralmente disponível no Amazon Bedrock. Para usar saídas estruturadas com as APIs Converse, atualize para o AWS SDK mais recente. Para saber mais, consulte a documentação do Amazon Bedrock e explore o notebook de exemplo.
Fonte
Structured outputs on Amazon Bedrock: Schema-compliant AI responses (https://aws.amazon.com/blogs/machine-learning/structured-outputs-on-amazon-bedrock-schema-compliant-ai-responses/)
