Saída Estruturada de LLM

O Que Esta Habilidade Faz

Extrai dados tipados e validados das respostas da API de LLM em vez de analisar texto livre. Esta habilidade cobre as três abordagens principais: response_format da OpenAI com JSON Schema, o bloco tool_use da Anthropic para extração estruturada e responseSchema do Google no Gemini. Você aprenderá quando cada abordagem funciona, quando falha e como construir lógica de retentativa em torno de falhas de validação de esquema que todo sistema de produção encontra.

Quando Usar Esta Habilidade

• O usuário precisa extrair dados estruturados (objetos JSON, arrays, enums) de uma resposta de LLM
• O usuário está construindo um pipeline onde a saída do LLM alimenta diretamente o código (gravações em banco de dados, chamadas de API, renderização de UI)
• O usuário pergunta sobre response_format, json_mode, json_object ou json_schema na OpenAI
• O usuário pergunta sobre o uso de blocos tool_use ou tool_result da Anthropic para extração de dados (não para execução real de ferramentas)
• O usuário pergunta sobre esquemas Zod com zodResponseFormat() do pacote npm openai
• O usuário precisa analisar a saída do LLM em modelos Pydantic usando instructor, marvin ou validação manual
• O usuário está recebendo JSON malformado, campos ausentes ou tipos incorretos das respostas do LLM e precisa de uma correção
• O usuário pergunta sobre controlled generation, constrained decoding ou grammar-based sampling em modelos locais

NÃO use esta habilidade quando:

• O usuário deseja geração de texto livre (resumos, ensaios, chat)
• O usuário está perguntando sobre Zod para validação de formulário ou validação de entrada de API (use zod-validation-expert em vez disso)
• O usuário precisa de engenharia de prompt para melhor qualidade de texto (não estrutura)
• O usuário deseja chamar ferramentas/APIs externas reais (esta habilidade cobre o uso de tool_use como um hack de saída estruturada, não orquestração real de ferramentas)

Fluxo de Trabalho Principal

1. Identifique o esquema de destino. Pergunte ao usuário quais campos ele precisa extrair. Defina cada campo com seu tipo, se é obrigatório ou opcional, e valores de enum válidos, se aplicável. Não prossiga sem um esquema concreto.

2. Escolha o método apropriado para o provedor:

   • OpenAI (gpt-4o, gpt-4o-mini): Use response_format: { type: "json_schema", json_schema: { ... } }. Isso permite Saídas Estruturadas com conformidade de esquema garantida por meio de decodificação restrita.
   • Anthropic (Claude): Defina uma única ferramenta com o esquema de destino como input_schema e defina tool_choice: { type: "tool", name: "extract_data" }. Claude retorna os dados estruturados no bloco de conteúdo tool_use.
   • Google (Gemini): Use generationConfig.responseSchema com um objeto JSON Schema e defina responseMimeType: "application/json".
   • Modelos locais (llama.cpp, vLLM): Use gramáticas GBNF ou o sinalizador --json-schema para decodificação restrita no nível do token.

3. Escreva a definição do esquema no idioma do usuário. Para Python, defina uma BaseModel Pydantic. Para TypeScript, defina um esquema Zod e converta-o com zodResponseFormat(). Para chamadas de API brutas, escreva JSON Schema diretamente.

4. Inclua descrições em nível de campo no esquema. Cada campo deve ter uma string description que informa ao modelo o que colocar lá. Os modelos usam essas descrições como instruções de prompt implícitas — um campo descrito como "The user's sentiment as positive, negative, or neutral" produz melhores resultados do que um sentiment: str nu sem contexto.

5. Defina o prompt do sistema para reforçar a estrutura. Diga ao modelo que seu trabalho é extração de dados, não conversação. Exemplo: "You are a data extraction system. Analyze the input and return the requested fields. Do not include explanations outside the JSON structure."

6. Se estiver usando o modo json_schema da OpenAI, defina "strict": true na definição do esquema. Isso ativa a decodificação restrita, onde o modelo só pode emitir tokens que estejam em conformidade com o esquema. Sem strict: true, o modelo ainda pode produzir JSON inválido.

7. Se estiver usando a abordagem tool_use da Anthropic, extraia os dados estruturados de response.content encontrando o bloco onde type == "tool_use" e lendo seu campo input. Não analise os blocos de texto — os dados estruturados residem exclusivamente no bloco tool_use.

8. Valide a resposta contra o esquema no código da sua aplicação. Mesmo com decodificação restrita, valide com model_validate() do Pydantic ou .parse() do Zod antes de passar os dados adiante. Isso captura problemas semânticos (strings vazias, números fora do intervalo) que a conformidade do esquema por si só não pode evitar.

…