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

Definir Esquemas com Pydantic

Aula 7 de 12 Atualizada a 29 de julho de 2026 Programador
Nesta página
  1. Pydantic: A Base das Saídas Estruturadas Personalizadas em Python
  2. Definir um Modelo Simples
  3. Tipos que Vai Utilizar
  4. Modelos Aninhados
  5. Orientar o Modelo com Descrições
  6. A Validação é Gratuita
  7. Pontos-chave

Pydantic: A Base das Saídas Estruturadas Personalizadas em Python

O Pydantic é a biblioteca de validação de dados mais popular em Python. Permite-lhe definir modelos de dados com tipos estritos, que é exatamente o que a API da Mistral utiliza para Saídas Estruturadas Personalizadas. Se trabalha em Python, o Pydantic torna-se a sua ferramenta principal para descrever esquemas de saída: o que escrever numa classe é aquilo a que o modelo ficará restrito para produzir.

Aqui estão as boas notícias sobre a instalação: o Pydantic está incluído como dependência do SDK da Mistral. Se já tem o mistralai instalado, não precisa de fazer mais nada.

pip install mistralai
# Pydantic v2 é incluído automaticamente

Uma verificação rápida da versão evita surpresas, uma vez que a sintaxe do validador mudou entre as versões principais:

import pydantic
print(pydantic.__version__)  # 2.x necessário

Definir um Modelo Simples

Um modelo Pydantic é uma classe que herda de BaseModel, onde cada atributo é um campo com um tipo explícito.

from pydantic import BaseModel

class Contact(BaseModel):
    name: str
    email: str
    phone: str
    company: str

Este modelo diz à Mistral: «A sua saída deve ser um objeto JSON com exatamente estes 4 campos, todos do tipo string.» Não são necessárias instruções adicionais no prompt para obter esta estrutura.

Tipos que Vai Utilizar

O Pydantic suporta todos os tipos padrão do Python e a Mistral compreende-os todos. O modelo seguinte reúne-os num caso realista — análise de um ticket de suporte — e mostra como se combinam: tipos básicos para campos simples, Optional para um responsável ainda não designado, Enum para uma prioridade que só pode assumir quatro valores e listas para etiquetas e IDs relacionados.

from pydantic import BaseModel
from typing import Optional
from enum import Enum

class Priority(str, Enum):
    low = "low"
    medium = "medium"
    high = "high"
    critical = "critical"

class TicketAnalysis(BaseModel):
    # Tipos básicos
    title: str
    description: str
    ticket_id: int
    confidence: float
    is_urgent: bool

    # Tipos opcionais
    assignee: Optional[str] = None

    # Enums (valores restritos)
    priority: Priority

    # Listas
    tags: list[str]
    related_ids: list[int]

Eis a folha de referência correspondente:

TipoSignificado
strstring
intinteiro
floatnúmero decimal
boolbooleano (verdadeiro/falso)
list[T]lista de elementos do tipo T
Optional[T]campo que pode ser null
Enumvalor de um conjunto finito

Os Enums merecem uma menção especial: são a única forma de garantir que uma prioridade nunca será "very urgent" ou "P1" dependendo do humor do modelo.

Modelos Aninhados

Os dados do mundo real raramente são planos. Um contacto pertence a uma empresa, que tem um endereço. O Pydantic permite aninhar modelos tão profundamente quanto necessário, e a Mistral segue a hierarquia.

from pydantic import BaseModel
from typing import Optional

class Address(BaseModel):
    street: str
    city: str
    postal_code: str
    country: str

class Company(BaseModel):
    name: str
    industry: str
    address: Address  # Modelo aninhado

class Person(BaseModel):
    first_name: str
    last_name: str
    email: str
    role: str
    company: Company  # Aninhamento de dois níveis

O JSON gerado reproduz exatamente esta estrutura em árvore:

{
  "first_name": "Marie",
  "last_name": "Dupont",
  "email": "[email protected]",
  "role": "Sales Director",
  "company": {
    "name": "TechVision SAS",
    "industry": "Technology",
    "address": {
      "street": "42 rue de la Paix",
      "city": "Paris",
      "postal_code": "75002",
      "country": "France"
    }
  }
}

O mesmo mecanismo extrai vários itens de uma vez: um modelo envolve uma lista de outro modelo e obtém um catálogo completo numa única chamada.

from pydantic import BaseModel

class Product(BaseModel):
    name: str
    price: float
    category: str
    in_stock: bool

class Catalog(BaseModel):
    products: list[Product]
    total_count: int

Orientar o Modelo com Descrições

O nome de um campo não conta toda a história. score pode significar uma nota de 0 a 10, uma percentagem ou um valor entre 0 e 1 — o modelo tem de adivinhar. As descrições removem esta ambiguidade: são incluídas no esquema JSON enviado à Mistral e atuam como instruções por campo.

from pydantic import BaseModel, Field

class SentimentAnalysis(BaseModel):
    sentiment: str = Field(
        description="Sentimento geral: 'positive', 'negative' ou 'neutral'"
    )
    score: float = Field(
        description="Pontuação de confiança entre 0.0 e 1.0"
    )
    keywords: list[str] = Field(
        description="As 3-5 palavras-chave principais do texto"
    )
    summary: str = Field(
        description="Resumo num máximo de uma frase"
    )

Quanto mais precisas forem estas descrições, melhor será a qualidade da saída. Esta é a parte de maior alavancagem de toda a configuração: algumas palavras bem escolhidas substituem frequentemente um parágrafo inteiro de prompt.

O Field também define valores padrão. No exemplo seguinte, o idioma assume por padrão "fr" se o modelo não encontrar a informação, a contagem de palavras permanece None se não puder ser determinada e as etiquetas começam como uma lista vazia graças ao default_factory.

from pydantic import BaseModel, Field
from typing import Optional

class ArticleMetadata(BaseModel):
    title: str
    author: str
    language: str = Field(default="fr", description="Código de idioma ISO 639-1")
    word_count: Optional[int] = None
    tags: list[str] = Field(default_factory=list)

Os campos com valores padrão serão preenchidos pelo modelo se este encontrar a informação ou manterão o valor padrão caso contrário.

A Validação é Gratuita

Por último, mas não menos importante: a validação é automática. Se um valor não corresponder ao tipo declarado, o Pydantic levanta imediatamente um ValidationError indicando exatamente qual o campo em causa, sem que tenha de escrever uma única linha de código de verificação.

from pydantic import ValidationError

try:
    analysis = SentimentAnalysis(
        sentiment="positive",
        score="not a number",  # Erro de tipo
        keywords=["test"],
        summary="Summary"
    )
except ValidationError as e:
    print(e)
    # 1 validation error for SentimentAnalysis
    # score
    #   Input should be a valid number [type=float_parsing, ...]

Todo o código de verificação manual escrito na lição anterior desaparece aqui, substituído pela declaração do modelo.

Pontos-chave

  • O BaseModel do Pydantic é a base de todos os esquemas personalizados em Python
  • Utilize tipos explícitos: str, int, float, bool, list[T], Optional[T]
  • Modelos aninhados permitem estruturas JSON complexas
  • Field(description=...) melhora a qualidade da saída ao orientar o modelo
  • A validação é automática — os erros de tipo são detetados imediatamente