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

Pydantic BaseModel em Profundidade

Aula 6 de 12 Atualizada a 30 de julho de 2026 Programador
Nesta página
  1. Pydantic: O Parceiro Ideal
  2. Noções Básicas do Pydantic para Saídas Estruturadas
  3. Tipos Python Suportados
  4. Modelos Aninhados
  5. Enums com Pydantic
  6. Utilizar parse()
  7. Utilizar response_format
  8. Valores Padrão e Documentação
  9. Pontos-chave

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
  • Literal substitui enum para impor valores predefinidos
  • str | None torna um campo opcional (pode ser null)
  • Field(description=...) melhora a qualidade das respostas do modelo
  • Funciona com parse() (automático) e response_format (manual)