JSON Garantido por Esquema
Nesta página
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.
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) eresponse_format(manual) - Esta é a base de qualquer pipeline de produção fiável com a API Grok