Pydantic BaseModel em Profundidade
Nesta página
Pydantic: O Parceiro Ideal
O Pydantic é a biblioteca Python padrão para validação de dados. Com as saídas estruturadas do Grok, torna-se uma ferramenta essencial: define os seus esquemas como classes Python e o modelo preenche essas classes automaticamente.
Noções Básicas do Pydantic para Saídas Estruturadas
Cria um modelo Pydantic herdando de BaseModel. Cada atributo com uma anotação de tipo torna-se um campo no esquema JSON:
from pydantic import BaseModel
class Produto(BaseModel):
nome: str
preco: float
em_stock: bool
categoria: str
Este modelo gera automaticamente o esquema JSON equivalente. Não precisa de escrever mais nada.
Tipos Python Suportados
Eis o mapeamento entre tipos Python e tipos JSON Schema:
class ExemploCompleto(BaseModel):
# Escalares
texto: str # → "type": "string"
numero: float # → "type": "number"
inteiro: int # → "type": "number"
ativo: bool # → "type": "boolean"
# Opcionais
nota: str | None # → anyOf string/null
# Coleções
etiquetas: list[str] # → array of strings
pontuacoes: list[float] # → array of numbers
# Enumerações
nivel: str # + enum in Field
Modelos Aninhados
O verdadeiro poder do Pydantic reside no aninhamento de modelos:
class Morada(BaseModel):
rua: str
cidade: str
codigo_postal: str
pais: str
class Competencia(BaseModel):
nome: str
nivel: str # "iniciante", "intermedio", "experto"
anos: int
class Candidato(BaseModel):
primeiro_nome: str
apelido: str
email: str
morada: Morada
competencias: list[Competencia]
disponivel: bool
expectativa_salarial: float | None
Quando passa Candidato como response_format, o modelo preencherá toda a hierarquia: a morada completa, cada competência com os seus detalhes e assim sucessivamente.
Enums com Pydantic
Para impor valores predefinidos, utilize o Literal do Python:
from typing import Literal
class Ticket(BaseModel):
titulo: str
descricao: str
prioridade: Literal["baixa", "media", "alta", "critica"]
estado: Literal["aberto", "em_curso", "resolvido", "fechado"]
tipo: Literal["bug", "funcionalidade", "documentacao"]
O modelo só pode devolver os valores listados. Qualquer outro valor é impossível.
Utilizar parse()
response, ticket = client.chat.parse(
model="grok-4.20-0309-reasoning",
messages=[{
"role": "user",
"content": "The login button does not work on mobile"
}],
response_format=Ticket
)
print(ticket.prioridade) # "alta"
print(ticket.tipo) # "bug"
print(ticket.estado) # "aberto"
Utilizar response_format
response = client.chat.create(
model="grok-4.20-0309-reasoning",
messages=[{
"role": "user",
"content": "The login button does not work on mobile"
}],
response_format=Ticket
)
ticket = Ticket.model_validate_json(
response.choices[0].message.content
)
Valores Padrão e Documentação
Pode adicionar descrições aos seus campos com Field. Estas descrições ajudam o modelo a compreender melhor o que espera:
from pydantic import BaseModel, Field
class AnaliseSentimento(BaseModel):
texto_original: str = Field(
description="The text analyzed as is"
)
sentimento: Literal["positivo", "negativo", "neutro"] = Field(
description="The dominant sentiment of the text"
)
score_confianca: float = Field(
description="Confidence score between 0.0 and 1.0"
)
palavras_chave: list[str] = Field(
description="The 3 to 5 most significant keywords"
)
As descrições em Field são incluídas no esquema JSON enviado ao modelo. Melhoram a qualidade das respostas.
Pontos-chave
- O Pydantic converte automaticamente as suas classes Python em esquemas JSON
- Aninhar modelos permite estruturar dados complexos
Literalsubstituienumpara impor valores predefinidosstr | Nonetorna um campo opcional (pode sernull)Field(description=...)melhora a qualidade das respostas do modelo- Funciona com
parse()(automático) eresponse_format(manual)