Lição 2 de 3 · 8 minutos

Receba saídas estruturadas

Envie um JSON Schema para o modelo retornar JSON no seu formato e valide o resultado antes de usá-lo.

Envie um JSON Schema com a solicitação, e o modelo retorna JSON nesse formato em vez de texto livre. Use isso quando você quer dados de volta, como campos extraídos de um e-mail. Use chamadas de ferramentas quando você quer que o modelo peça ao seu app para fazer algo.

typeO que você recebe
json_schemaJSON que segue o seu schema. Use este por padrão.
json_objectAlgum objeto JSON válido, sem formato garantido.
textTexto simples (o padrão).

O formato vai em response_format no /v1/chat/completions, em text.format no /v1/responses e em output_config.format no /v1/messages (só json_schema).

{
  "model": "openai/gpt-6-astra",
  "messages": [
    { "role": "user", "content": "Return the city and weather for London." }
  ],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "weather",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "city": { "type": "string" },
          "weather": { "type": "string" }
        },
        "required": ["city", "weather"],
        "additionalProperties": false
      }
    }
  }
}

O JSON volta como string no conteúdo da mensagem. Antes de interpretá-lo, verifique se houve recusa, conteúdo ausente ou um finish_reason diferente de stop. Depois valide o objeto interpretado, por exemplo com Zod. Se a validação falhar, tente de novo uma vez com o erro no prompt e então retorne uma falha segura. Cada nova tentativa é cobrada, e JSON válido ainda não prova que os valores estão corretos.

O Phaseo nunca descarta response_format. Ele só roteia uma solicitação json_schema para provedores que aceitam saídas estruturadas; se nenhum provedor do modelo aceitar, a solicitação falha com 400 validation_error. As páginas de modelo indicam o suporte com structured_outputs, que é um indicador de capacidade, não um campo da solicitação.

Confira o que você aprendeu

Você envia response_format com json_schema para um modelo cujos provedores não aceitam saídas estruturadas. O que acontece?

Aplique

O seu leitor de faturas usa json_schema e, de vez em quando, a resposta falha na sua verificação com Zod porque total está ausente. O que o código deve fazer?

Mostrar a resposta

Primeiro confira se finish_reason é stop, já que uma resposta cortada não pode ser válida. Depois tente de novo uma vez com o erro de validação no prompt e, se falhar outra vez, retorne uma falha segura em vez de adivinhar. Acompanhe as falhas por modelo e por versão do schema para perceber quando uma mudança em qualquer um deles piora as coisas.

Resumo

Use json_schema para dados que você precisa em um formato fixo e sempre valide o resultado no seu próprio código antes de confiar nele.

Links relacionados

O progresso fica salvo neste navegador.

Verificado em 17 de novembro de 2026