Ir para o conteúdo principal
Português— Escolher um idioma
Menu

JSON Garantido por Esquema

Aula 1 de 12 Atualizada a 28 de julho de 2026 Programador
Nesta página
  1. Por que as saídas estruturadas mudam tudo
  2. Como funciona
  3. Disponibilidade
  4. Sem vs. Com Saídas Estruturadas
  5. Duas abordagens disponíveis
  6. Pontos-chave

Por que as saídas estruturadas mudam tudo

Quando utiliza um modelo de linguagem em produção, precisa de respostas que o seu código possa consumir. Não texto livre, nem JSON aproximado — mas JSON garantidamente compatível com um esquema que você define. É exatamente isso que as saídas estruturadas da API Grok lhe oferecem.

O princípio é simples: fornece um esquema JSON ao modelo e a API garante que a resposta seguirá essa estrutura exatamente. Sem análise aleatória, sem expressões regulares frágeis, nem blocos try/catch para lidar com casos em que o modelo inventa um formato.

Como funciona

As saídas estruturadas baseiam-se num mecanismo de restrição aplicado durante a geração do texto. Em cada token produzido, o modelo fica restrito a gerar apenas tokens compatíveis com o esquema fornecido. O resultado: JSON que é sempre válido e sempre compatível.

Vejamos um exemplo concreto. Quer extrair informações de contacto de um e-mail:

from pydantic import BaseModel

class Contact(BaseModel):
    nom: str
    email: str
    entreprise: str
    telephone: str | None

# A resposta será SEMPRE um objeto Contact válido

Sem saídas estruturadas, o modelo poderia devolver o telefone como "tel", "phone" ou "numéro". Com um esquema, o campo chamar-se-á sempre telephone e o seu valor será sempre uma cadeia de caracteres ou null.

Disponibilidade

As saídas estruturadas são suportadas em todos os modelos de linguagem xAI: Grok 4.5, Grok 4.3, variantes grok-4.20 e versões posteriores. Independentemente do modelo que utilize, a funcionalidade está disponível sem custos extras nem configuração adicional.

100%
JSON válido garantido
7
Tipos suportados
Todos
Modelos xAI
2
Métodos de chamada

Sem vs. Com Saídas Estruturadas

Eis o que obtém sem e com esta funcionalidade:

Sem saídas estruturadas:

  • O modelo pode devolver texto livre, JSON parcial ou um formato inesperado
  • Deve analisar manualmente e gerir erros
  • Os nomes dos campos podem variar de um pedido para outro
  • O seu pipeline falha assim que o modelo altera o formato

Com saídas estruturadas:

  • O JSON é sempre sintaticamente válido
  • A estrutura corresponde exatamente ao esquema fornecido
  • Os tipos são respeitados (cadeia de caracteres, número, booleano, etc.)
  • O seu código pode consumir a resposta diretamente

Duas abordagens disponíveis

A API Grok oferece dois métodos para utilizar saídas estruturadas:

  • parse(): Método automático que devolve diretamente um objeto tipado. Ideal para a maioria dos casos.
  • response_format: Método manual que devolve uma cadeia JSON. Oferece mais controlo, mas a análise fica a seu cargo.

Irá descobrir estes dois métodos em detalhe nas próximas lições.

Pontos-chave

  • As saídas estruturadas garantem JSON compatível com o seu esquema em todas as chamadas
  • A restrição é aplicada durante a geração, não depois
  • Todos os modelos de linguagem xAI suportam esta funcionalidade
  • Estão disponíveis dois métodos: parse() (automático) e response_format (manual)
  • Esta é a base de qualquer pipeline de produção fiável com a API Grok