Quando um código lê a resposta de um modelo, “quase com a forma certa” é um bug. O prompting de saída estruturada é o conjunto de práticas que fazem o modelo retornar dados que o seu programa consegue analisar sempre: um formato definido, restrições explícitas e validação.
Três níveis de confiabilidade
| Nível | Como | Garantia |
|---|---|---|
| Só o prompt | Descrever o formato no prompt | Nenhuma. Geralmente certo, às vezes não |
| Modo JSON | Pedir à API uma resposta JSON | JSON válido, mas não o seu esquema |
| Saída restrita por esquema | Fornecer um JSON Schema à API | A saída segue o esquema |
Use o nível mais forte que o seu provedor oferecer. OpenAI, Anthropic e Google oferecem, todos, uma forma de restringir uma resposta a um esquema ou ao esquema de entrada de uma ferramenta. O prompt continua importando em todos os níveis, porque um esquema controla a forma da saída e o prompt controla o seu conteúdo.
Escrevendo restrições de saída no prompt
Indique o formato, os campos, os tipos e os valores permitidos. Depois diga o que não deve aparecer.
Extract the order details from the email in the tags.
Return a JSON object with exactly these fields:
- "order_id": string, as written in the email
- "items": array of {"name": string, "quantity": integer}
- "total": number, without currency symbol
- "currency": one of "USD", "EUR", "GBP"
If a field is not present in the email, use null.
Return only the JSON object, with no explanation and no code fence.
<email>
{{email}}
</email>
Quatro detalhes desse prompt evitam a maior parte das falhas:
- “Exatamente estes campos” impede o modelo de acrescentar extras bem-intencionados.
- Valores permitidos para
currencyevitam “US dollars” e “$”. - Uma regra de nulo dá ao modelo uma forma correta de dizer “não encontrado”, para que ele não invente um valor.
- “Retorne apenas o JSON” remove a frase de comentário que quebra o
JSON.parse.
Projete o esquema para o modelo
Um esquema faz parte do prompt. O modelo lê nomes e descrições de campos como instruções.
- Nomeie os campos pelo que contêm.
shipping_addressé melhor queaddr2. - Acrescente descrições aos campos cujo significado não é óbvio, incluindo unidade e formato: “data ISO 8601, UTC”.
- Use enums sempre que um campo tiver um conjunto fixo de valores.
- Mantenha plano. O aninhamento profundo aumenta os erros. Divida uma extração muito complexa em prompts encadeados.
- Coloque o raciocínio antes da resposta. Se você quer uma explicação e um veredicto, ordene os campos
"reasoning"e depois"verdict". O modelo escreve os campos em ordem, então o raciocínio escrito primeiro pode informar o veredicto.
Além do JSON
Saída estruturada não é só JSON.
- Markdown com títulos fixos serve para respostas que pessoas leem: “Use exatamente estes títulos: Resumo, Riscos, Próximos passos.”
- Tags no estilo XML são fáceis de extrair com uma expressão regular e toleram texto livre dentro:
<answer>…</answer>. - Um único token é o formato mais confiável de todos. Para classificação, peça apenas o rótulo.
- CSV ou tabelas funcionam para dados pequenos e regulares; as regras de aspas ficam frágeis com texto livre.
Escolha o formato mais simples que transporte a informação.
Restrições de tamanho e conteúdo
As restrições de saída também cobrem tamanho e estilo:
- At most 3 bullet points, each under 20 words.
- Use only facts from the document. If the document does not say, write "not stated".
- Write in the present tense.
Dê os tamanhos em números. “Breve” não é uma restrição em que um parser ou um layout possa se apoiar.
Sempre valide
Mesmo com saída restrita por esquema, valide antes de usar os dados.
- Analise e verifique o esquema de cada resposta. Uma resposta pode ser cortada ao atingir o limite de tokens de saída, deixando um JSON truncado.
- Verifique a semântica que o esquema não consegue expressar: o total é igual à soma dos itens, a data não está no futuro.
- Decida o caminho de falha. Tente de novo uma vez incluindo no prompt o erro de validação e depois recorra a uma alternativa ou sinalize para revisão.
- Nunca execute saída estruturada às cegas. Um campo que vira uma cláusula SQL, um caminho de arquivo ou um argumento de shell precisa da mesma sanitização que a entrada de um usuário. Veja a segurança de prompts.
Modos de falha comuns
| Falha | Causa | Correção |
|---|---|---|
| Texto antes ou depois do JSON | Sem a instrução “apenas” | Acrescente-a, ou use o modo JSON |
| Envolvido em um bloco de código | Hábito do modelo | Diga “sem bloco de código”, ou remova no código |
| Valores inventados | Sem regra para dados ausentes | Acrescente uma regra de nulo ou “não informado” |
| Campos extras | Redação aberta | Diga “exatamente estes campos”; proíba propriedades adicionais |
| Saída truncada | Limite de saída atingido | Aumente o limite ou divida a tarefa |
| Grafia inconsistente de enums | Valores não listados | Liste os valores permitidos |
Verificando o prompt antes de executá-lo
Um formato de saída ausente é o achado mais frequente em prompts que alimentam código. O analisador de prompts do PromptFlowEngine o relata, junto com a falta de orientação de tamanho e as variáveis sem delimitação. O template de extração JSON é um exemplo completo que passa em todas as verificações.
Para ver como isso se encaixa no código de uma aplicação, veja a engenharia de prompts para desenvolvedores.