Definir Esquemas com Pydantic
Nesta página
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:
| Tipo | Significado |
|---|---|
str | string |
int | inteiro |
float | número decimal |
bool | booleano (verdadeiro/falso) |
list[T] | lista de elementos do tipo T |
Optional[T] | campo que pode ser null |
Enum | valor 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
BaseModeldo 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