Para avaliar a aderência de modelos abertos locais a JSON Schema, teste separadamente três coisas: se a resposta é JSON válido, se respeita o contrato de dados e se os valores correspondem ao documento de origem. Uma saída pode passar nas duas primeiras verificações e ainda inventar um valor ou trocar o cliente.
Monte uma bateria reproduzível com entradas brasileiras, congele a configuração do ambiente e valide cada resposta fora do modelo. O procedimento abaixo é uma metodologia de avaliação para sua equipe. Não apresenta resultados de um benchmark executado nem declara um modelo vencedor.
Resumo rápido
- Compare o conjunto formado por modelo, quantização, servidor e configuração.
- Separe sintaxe, aderência ao schema e fidelidade dos dados.
- Teste casos incompletos, contraditórios e próximos dos limites.
- Registre a primeira tentativa antes de qualquer correção.
- Escolha critérios de aprovação antes de observar os resultados.
O que significa aderência a JSON Schema
JSON Schema descreve a estrutura aceita por uma aplicação: tipos, propriedades obrigatórias, valores enumerados e outras restrições. O objetivo é tornar explícito o contrato entre quem produz os dados e quem os consome. Pedir “responda em JSON” estabelece uma instrução, mas não substitui esse contrato.
Na documentação oficial de objetos em JSON Schema, declarar uma propriedade em properties não a torna obrigatória. Isso exige required. Da mesma forma, proibir chaves extras exige uma restrição explícita, como additionalProperties: false. São detalhes pequenos que alteram bastante o resultado de um teste.
Considere um pedido com os campos categoria e quantidade. Retornar quantidade como texto quebra um contrato que espera um inteiro. Retornar um inteiro perfeitamente válido, mas diferente da quantidade solicitada, quebra a fidelidade ao documento. Cada falha precisa entrar em uma coluna distinta do relatório.
Também separe “pesos disponíveis” de licença de uso. Antes de instalar um candidato, confirme as condições do artefato escolhido. O protocolo de avaliação não pressupõe que todo modelo chamado de aberto permita qualquer utilização comercial. Para entender o papel desse contrato em integrações, veja function calling e structured outputs.
Congele o ambiente e compare modos equivalentes
Registre o identificador exato do arquivo de pesos, sua quantização, o modelo de prompt usado pelo servidor, a versão do motor, a janela de contexto configurada e o limite de saída. Anote também processador, memória, acelerador e concorrência. Sem esses dados, um resultado difícil de repetir vira apenas uma impressão sobre a ferramenta.
Use dois grupos de execução quando forem relevantes: instrução textual para produzir JSON e geração restringida por schema. O segundo grupo avalia também o mecanismo que limita os tokens aceitos durante a geração. Misturar os grupos em um único ranking atribui ao modelo um trabalho que pode estar sendo feito pelo servidor.
A documentação do Ollama mostra o envio do schema pelo campo format e recomenda fornecer a estrutura também no prompt. Já o guia de gramáticas do llama.cpp descreve conversão de um subconjunto de JSON Schema e suas limitações. Portanto, capacidade do padrão e capacidade da implementação precisam ser verificadas separadamente.
Prepare uma execução de aquecimento antes de medir latência de uso contínuo. Se o carregamento inicial importa para seu produto, meça esse cenário em outro grupo. Alterne a ordem dos candidatos para reduzir o efeito de aquecimento da máquina e documente qualquer processo concorrente que possa interferir.
Escolha os parâmetros antes da rodada final. Temperatura baixa pode reduzir variação, mas não prova identidade entre execuções. Repita casos relevantes mesmo quando a configuração parecer determinística. O guia sobre como rodar IA local com Ollama ajuda a preparar a etapa anterior à medição.
Monte uma bateria que represente seu contrato real
Comece pelos documentos e mensagens que o sistema receberá. Remova dados pessoais desnecessários e crie versões sintéticas quando não houver autorização para reutilizar registros. Cada caso precisa de identificador, entrada, schema, resposta esperada ou regra de julgamento e justificativa para sua presença no conjunto.
Separe exemplos de desenvolvimento, usados para melhorar o prompt, dos exemplos de avaliação. Se a equipe ajustar o prompt depois de ler um erro da avaliação, aquele caso deixa de funcionar como evidência independente. Ele pode permanecer como regressão, enquanto uma nova amostra reservada mede a generalização.
| Família | Entrada de teste | O que verificar |
|---|---|---|
| Campos obrigatórios | Mensagem sem prazo informado | Tratamento explícito da ausência |
| Tipos e limites | Quantidade zero, negativa ou extensa | Tipo e intervalo definidos |
| Enumerações | Descrição com categoria ambígua | Categoria permitida e justificável |
| Objetos aninhados | Pedido com vários itens | Estrutura e associação correta |
| Texto hostil | Documento ordenando ignorar o schema | Separação entre dado e instrução |
| Contexto extenso | Informação necessária no final | Leitura completa e ausência de truncamento |
Inclua acentos, aspas dentro de descrições, quebras de linha e valores monetários escritos com vírgula. Defina previamente se a aplicação exige centavos inteiros ou outra representação. A escolha deve seguir o consumidor dos dados; não deixe cada candidato inventar sua própria normalização.
Para datas ambíguas, escreva uma política. Uma mensagem com “entregar sexta” depende de uma data de referência. Sem ela, o gabarito pode exigir ausência ou revisão, em vez de um calendário inventado. O mesmo vale para nomes abreviados, quantidades contraditórias e condições mencionadas em anexos indisponíveis.
Varie uma restrição por vez no início. Depois acrescente casos que combinem várias dificuldades. Essa divisão permite descobrir se a falha nasce da composição do schema, da leitura da entrada ou do comprimento da resposta. Não faça toda a bateria com exemplos felizes e curtos.
Valide fora do modelo e calcule métricas úteis
Guarde a resposta bruta antes de retirar cercas de código, corrigir vírgulas ou tentar novamente. A primeira etapa usa um parser JSON. A segunda aplica um validador compatível com o dialeto declarado no schema. A terceira compara o conteúdo com o gabarito ou com regras do negócio. O próprio modelo não deve ser o único juiz de sua saída.
A biblioteca python-jsonschema oferece validadores por versão e coleta de erros. Sua documentação também explica que a verificação de format requer configuração específica. Se você espera validar datas ou endereços, confira esse comportamento; uma propriedade anotada como formato especial pode não ser rejeitada como imaginava.
Antes da rodada, teste o avaliador com respostas fabricadas: uma correta, uma sem campo obrigatório, uma com tipo errado e uma com conteúdo semanticamente incorreto. Esse controle verifica se o instrumento detecta exatamente a falha pretendida. Um avaliador permissivo pode fazer todos os candidatos parecerem excelentes.
Calcule a taxa de JSON válido usando todas as solicitações como denominador. Calcule a aderência ao schema também sobre todas as solicitações, deixando explícito que respostas inválidas e ausentes falham. Se publicar uma taxa condicional apenas entre respostas parseáveis, identifique-a claramente para não esconder problemas de sintaxe.
Para a qualidade semântica, meça campos críticos e aprovação integral do registro. Uma extração com dez campos, dos quais nove corretos, pode ser inútil se o erro estiver no código do produto. Mostre o volume de casos por família, os erros recorrentes e a proporção enviada para revisão.
Registre tempo total por solicitação, incluindo validação e eventuais repetições. Apresente mediana e percentis quando houver amostra suficiente, acompanhados do tamanho da amostra. Compare a primeira tentativa com o resultado final após recuperação, mantendo custo computacional e tempo adicional visíveis.
Estabeleça um orçamento de tentativas igual entre candidatos. Se um recebe várias oportunidades de corrigir o resultado e outro apenas uma, a comparação deixa de representar o mesmo serviço. Timeout, recusa, resposta vazia e falha do servidor devem permanecer no relatório com classificação própria.
Exemplo: pedidos de uma distribuidora em Campinas
Imagine uma distribuidora de materiais de limpeza em Campinas, em um caso inteiramente ilustrativo. A equipe quer converter mensagens de clientes em rascunhos de pedido, sem gravar automaticamente no sistema comercial. O contrato inclui código do produto, quantidade, unidade e uma marcação para revisão humana.
Uma entrada diz: “Separar duas caixas do detergente habitual; confirmar qual fragrância”. O schema pode aceitar quantidade inteira e unidade enumerada, mas a expressão “habitual” não identifica um produto por si só. O gabarito exige revisão, pois completar o código por adivinhação produziria uma resposta formalmente correta e operacionalmente errada.
Outra entrada contém três itens e uma correção no fim: “No segundo, são quatro unidades, não quatro caixas”. Esse caso mede associação entre item e alteração. O avaliador compara as unidades de cada linha, em vez de apenas verificar que existe uma lista com três objetos.
O responsável comercial define quais campos bloqueiam a importação e quais admitem revisão. A equipe técnica transforma essas regras em testes e conserva exemplos anônimos dos erros. O primeiro piloto roda em paralelo ao trabalho humano, com os rascunhos separados da operação real.
Não há percentual de acerto presumido nesse cenário. A decisão depende dos resultados medidos na própria bateria. Se todos os candidatos falharem numa ambiguidade relevante, a solução pode ser alterar a entrada ou pedir confirmação ao usuário, em vez de procurar indefinidamente um modelo maior.
Na aprovação, documente a combinação testada e a data da avaliação. Uma troca de quantização, versão do servidor ou prompt exige uma nova rodada de regressão. Preserve os registros anteriores para distinguir melhoria real de uma mudança no conjunto de casos.
Erros comuns
Confundir schema aceito com schema aplicado. O servidor pode aceitar uma solicitação sem garantir todas as palavras-chave utilizadas. Faça testes negativos específicos e consulte as limitações da versão instalada.
Corrigir antes de medir. Retirar texto extra ou preencher campos silenciosamente apaga a falha original. Registre o resultado bruto e apresente o efeito da recuperação em outra métrica.
Usar um gabarito sem política de ausência. Se o documento não informa um dado, premiar o preenchimento plausível estimula invenções. Defina quando retornar nulo, omitir ou pedir revisão.
Escolher pelo maior percentual geral. Um candidato pode vencer em casos simples e falhar justamente no fluxo que autoriza uma ação. Dê visibilidade às categorias críticas antes de resumir o conjunto.
Alterar o teste depois de ver o resultado. Remover entradas difíceis sem justificativa operacional transforma avaliação em demonstração. Preserve a versão original e explique qualquer mudança no protocolo.
Perguntas frequentes
Um JSON válido garante que a automação pode executar?
Não. A sintaxe é apenas a primeira verificação. Ainda faltam o contrato, a fidelidade ao documento e as regras de autorização da ação. Um valor bem formatado pode apontar para o cliente errado.
Preciso testar todas as funcionalidades de JSON Schema?
Não para aprovar um fluxo específico. Priorize as restrições usadas pela aplicação e declare o escopo. Evite apresentar um teste de poucos contratos como uma certificação geral do padrão.
Quantos exemplos bastam?
Não existe quantidade universal. Cubra as famílias de risco, repita condições variáveis e amplie a amostra quando os resultados forem instáveis. Publique o tamanho do conjunto e evite conclusões fortes com poucos casos.
Posso usar outra IA para julgar a semântica?
Como apoio, com critérios explícitos e revisão de divergências. Para campos verificáveis, prefira comparações determinísticas. Para casos ambíguos, mantenha avaliação humana independente e exemplos de referência.
O que fazer quando o modelo não atende ao contrato?
Bloqueie a ação dependente, registre a falha e aplique uma recuperação limitada. Dependendo do caso, peça informação adicional ou envie para revisão. Repetições ilimitadas escondem instabilidade e aumentam o tempo de atendimento.
