Padrões complexos: listas aninhadas, enums, uniões
Nesta página
Padrões complexos: listas aninhadas, enums, uniões
Os casos de extração simples (um objeto plano com campos de texto) são fáceis de gerir. Os verdadeiros desafios surgem com estruturas complexas: listas de objetos aninhados, tipos condicionais e campos polimórficos. Esta lição mostra-lhe como conceber esquemas robustos para estes casos avançados.
Listas aninhadas
O padrão mais comum em produção envolve extrair uma lista de objetos onde cada objeto contém as suas próprias sub-listas. O esquema abaixo descreve um programa de formação com três níveis: o objeto do programa com o seu título e duração, um vetor de módulos, cada um com um título e objetivos textuais, e finalmente as lições de cada módulo, descritas por um título, uma duração em minutos e um tipo restrito por um enum.
O que o modelo deve conseguir fazer aqui vai além da leitura: precisa de associar cada lição ao módulo correto, o que significa que deve compreender uma hierarquia por vezes transmitida apenas pelos níveis de cabeçalho. Daí os campos muito concretos no terceiro nível — uma duração em minutos em vez de uma “duração” genérica expressa por vezes em horas, outras em sessões. Quanto mais precisos forem os nós folha da árvore, menos o modelo hesita.
import json
from openai import OpenAI
client = OpenAI()
# Schema: extract a training program with modules and lessons
formation_schema = {
"type": "object",
"properties": {
"titre": {"type": "string"},
"duree_totale_heures": {"type": "number"},
"modules": {
"type": "array",
"items": {
"type": "object",
"properties": {
"titre_module": {"type": "string"},
"objectifs": {
"type": "array",
"items": {"type": "string"}
},
"lecons": {
"type": "array",
"items": {
"type": "object",
"properties": {
"titre_lecon": {"type": "string"},
"duree_minutes": {"type": "integer"},
"type": {
"type": "string",
"enum": ["theorie", "pratique",
"évaluation"]
}
},
"required": ["titre_lecon",
"duree_minutes", "type"],
"additionalProperties": False
}
}
},
"required": ["titre_module", "objectifs", "lecons"],
"additionalProperties": False
}
}
},
"required": ["titre", "duree_totale_heures", "modules"],
"additionalProperties": False
}
Enums para restringir valores
Os enums são a forma mais fiável de limitar os valores possíveis de um campo. A Saída Estruturada aplica-os ao nível da geração: ao contrário de uma instrução escrita no prompt, não podem ser ignorados num dia de fadiga estatística. Isto torna-os valiosos quando o valor extraído alimenta uma instrução switch, uma coluna indexada ou uma regra de encaminhamento — três locais onde um valor inesperado não causa um erro grave, mas sim silêncio.
O esquema de classificação que se segue organiza os pedidos recebidos ao longo de quatro eixos: categorie_principale localiza o departamento relevante, sous_categorie refina-o dentro desse departamento, priorite serve para ordenar a fila e action_requise determina o que fazer com o ticket. Um ponto de design merece atenção: os doze valores de sous_categorie estão achatados em vez de anexados à sua categoria pai, porque o modo estrito não oferece dependência condicional entre dois enums. Nada impede, portanto, a combinação “juridique” e “recrutement”, e esta consistência deve ser verificada após a receção.
# Multi-level classification system
classification_schema = {
"type": "object",
"properties": {
"categorie_principale": {
"type": "string",
"enum": ["technique", "commercial", "juridique",
"rh", "finance"]
},
"sous_categorie": {
"type": "string",
"enum": [
"bug", "feature", "performance",
"devis", "facturation", "contrat",
"recrutement", "conge", "formation",
"budget", "audit", "conformite"
]
},
"priorite": {
"type": "string",
"enum": ["critique", "haute", "moyenne", "basse"]
},
"action_requise": {
"type": "string",
"enum": ["repondre", "escalader", "archiver",
"planifier", "deleguer"]
}
},
"required": ["categorie_principale", "sous_categorie",
"priorite", "action_requise"],
"additionalProperties": False
}
Simulação de uniões de tipos
O JSON Schema suporta anyOf para tipos condicionais, mas a Saída Estruturada estrita da OpenAI tem limitações. O padrão recomendado é utilizar um campo discriminador: define um único objeto, suficientemente amplo para cobrir todos os casos, e um campo type indica qual está a descrever.
# Pattern: an event can be a meeting, a task, or a reminder
event_schema = {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": ["reunion", "tache", "rappel"]
},
"titre": {"type": "string"},
"date": {"type": "string"},
"heure_debut": {"type": ["string", "null"]},
"heure_fin": {"type": ["string", "null"]},
"participants": {
"type": "array",
"items": {"type": "string"}
},
"lieu": {"type": ["string", "null"]},
"priorite": {
"type": ["string", "null"],
"enum": ["haute", "moyenne", "basse", None]
},
"description": {"type": "string"}
},
"required": ["type", "titre", "date", "heure_debut",
"heure_fin", "participants", "lieu",
"priorite", "description"],
"additionalProperties": False
}
O truque consiste em tornar nulo qualquer campo específico de um único tipo, utilizando a notação "type": ["string", "null"]. Para uma reunião, participants e lieu são preenchidos; para um lembrete, são iguais a null. O seu código lê então primeiro o discriminador e sabe imediatamente quais as chaves que fazem sentido — exatamente a leitura que faria de uma união etiquetada numa linguagem tipada. O preço a pagar, um esquema mais verboso e nulls para gerir, continua a ser preferível a três chamadas separadas.
Objetos recursivos
Para estruturas em árvore — menus, organigramas, fios de discussão — utilize $defs para referências recursivas. O princípio consiste em nomear a forma repetitiva uma vez e depois referenciá-la a partir de si mesma. Aqui, um comentário contém um vetor de respostas onde cada elemento é, por sua vez, um comentário: a profundidade não é fixa no momento da escrita, segue a do documento analisado. Esta é a única forma razoável de processar um fio de discussão sem saber antecipadamente se tem dois ou sete níveis de respostas.
# Structure of a comment with nested replies
comment_schema = {
"type": "object",
"properties": {
"commentaires": {
"type": "array",
"items": {"$ref": "#/$defs/comment"}
}
},
"required": ["commentaires"],
"additionalProperties": False,
"$defs": {
"comment": {
"type": "object",
"properties": {
"auteur": {"type": "string"},
"contenu": {"type": "string"},
"sentiment": {
"type": "string",
"enum": ["positif", "negatif", "neutre"]
},
"reponses": {
"type": "array",
"items": {"$ref": "#/$defs/comment"}
}
},
"required": ["auteur", "contenu", "sentiment",
"reponses"],
"additionalProperties": False
}
}
}
Padrão: extração de múltiplas entidades
Quando um texto contém vários tipos de entidades, a tentação é executar uma extração por família. O esquema de múltiplas entidades faz melhor: solicita pessoas, organizações, datas e valores numa única passagem. O benefício não é apenas poupar chamadas; é que o modelo vê o texto uma vez e pode relacionar o que lá encontra — associando uma pessoa à sua organização, ligando um valor ao contexto que lhe dá significado.
A duplicação nas datas, date_brute e date_iso, merece ser mantida tal como está nos seus próprios esquemas: preserva a formulação original para auditoria, fornecendo simultaneamente um valor normalizado. O campo contexte, presente nas datas e nos valores, desempenha o mesmo papel: sem ele, ninguém saberá se 12.000 euros foram um orçamento, uma penalização ou um orçamento anual.
multi_entity_schema = {
"type": "object",
"properties": {
"personnes": {
"type": "array",
"items": {
"type": "object",
"properties": {
"nom": {"type": "string"},
"role": {"type": "string"},
"organisation": {"type": ["string", "null"]}
},
"required": ["nom", "role", "organisation"],
"additionalProperties": False
}
},
"organisations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"nom": {"type": "string"},
"type": {
"type": "string",
"enum": ["entreprise", "association",
"administration", "autre"]
},
"secteur": {"type": ["string", "null"]}
},
"required": ["nom", "type", "secteur"],
"additionalProperties": False
}
},
"dates": {
"type": "array",
"items": {
"type": "object",
"properties": {
"date_brute": {"type": "string"},
"date_iso": {"type": "string"},
"contexte": {"type": "string"}
},
"required": ["date_brute", "date_iso", "contexte"],
"additionalProperties": False
}
},
"montants": {
"type": "array",
"items": {
"type": "object",
"properties": {
"valeur": {"type": "number"},
"devise": {"type": "string"},
"contexte": {"type": "string"}
},
"required": ["valeur", "devise", "contexte"],
"additionalProperties": False
}
}
},
"required": ["personnes", "organisations", "dates", "montants"],
"additionalProperties": False
}
Melhores práticas para esquemas complexos
Quatro hábitos evitam a maioria das desilusões. Comece simples: valide um objeto plano nos seus dados reais antes de adicionar qualquer aninhamento, caso contrário não saberá se uma falha provém do esquema ou da dificuldade da tarefa. Em seguida, abandone o campo opcional, que o modo estrito proíbe, e torne-o nulo em vez disso. Respeite também um limite empírico — além de três ou quatro níveis de aninhamento a qualidade diminui, e é melhor dividir a extração em duas passagens: primeiro a lista de módulos, depois uma chamada por módulo para detalhar as suas lições. Por fim, tenha em mente a divisão de trabalho: o esquema e os seus enums restringem a estrutura, o prompt do sistema guia o conteúdo. Se o modelo ordenar corretamente mas extrair a informação errada, é o prompt que precisa de ajustar.
O caso que testa tudo: o organigrama
Aborde o caso recursivo, a parte mais educativa da lição. Defina um esquema para extrair o organigrama de uma empresa, onde cada colaborador pode ter subordinados que são, por sua vez, colaboradores. Teste-o num texto que descreva uma organização de quinze a vinte pessoas, escrito em prosa e não como uma lista: é aqui que o modelo deve inferir as linhas de reporte a partir de frases como “reporta a” ou “dentro da equipa de”.
Verifique se as relações hierárquicas estão corretamente aninhadas, atentando para pessoas mencionadas longe do seu gestor — este é o ponto de rutura habitual. Por fim, adicione enums nos papéis (direção, gestão, operacional) e observe se a restrição melhora ou degrada a linha de reporte: forçar uma categorização pode ajudar o modelo ou empurrá-lo para escolhas arbitrárias em perfis híbridos.
Pontos-chave
- As listas aninhadas são o padrão mais comum em produção
- Os enums são aplicados ao nível da geração — explore-os
- Simule uniões com um campo discriminador e campos nulos
$defspermite estruturas recursivas (comentários, árvores)- Limite a profundidade de aninhamento a 3-4 níveis