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

Casos de Utilização Avançados

Aula 10 de 12 Atualizada a 29 de julho de 2026 Programador
Nesta página
  1. Para Além dos Exemplos Simples
  2. Extração de uma Fatura
  3. Análise de Avaliações por Aspeto
  4. Classificação de Texto em Múltiplas Categorias
  5. Fatorização da Chamada
  6. Pontos-chave

Para Além dos Exemplos Simples

Já dominou o Pydantic, o Zod e o client.chat.parse(). Os próximos três casos vão além de esquemas simples de quatro campos, abordando cenários que encontrará em ambientes empresariais: documentos contabilísticos, análise detalhada de avaliações de clientes e textos que pertencem simultaneamente a várias categorias. Cada um ilustra uma técnica de modelagem diferente.

Extração de uma Fatura

O processamento de documentos é o território natural dos esquemas aninhados. Uma fatura não é um objeto plano: contém um cabeçalho, um rodapé com totais e um número variável de linhas de itens com a sua própria estrutura. Por isso, modelamos LineItem separadamente e referenciamo-lo dentro de uma lista. A moeda utiliza um enum, o que impede que o modelo devolva "euros" ou "€" dependendo da redação do documento.

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

class Currency(str, Enum):
    eur = "EUR"
    usd = "USD"
    gbp = "GBP"

class LineItem(BaseModel):
    description: str = Field(description="Line item description")
    quantity: float = Field(description="Quantity")
    unit_price: float = Field(description="Unit price excluding tax")
    vat_rate: float = Field(description="VAT rate as a percentage (e.g., 20.0)")
    total_ht: float = Field(description="Line total excluding tax")

class InvoiceData(BaseModel):
    invoice_number: str = Field(description="Invoice number")
    date: str = Field(description="Invoice date in YYYY-MM-DD format")
    due_date: Optional[str] = Field(default=None, description="Due date")
    vendor_name: str = Field(description="Vendor name")
    vendor_address: Optional[str] = Field(default=None)
    client_name: str = Field(description="Client name")
    line_items: list[LineItem] = Field(description="Invoice line items")
    subtotal_ht: float = Field(description="Subtotal excluding tax")
    total_vat: float = Field(description="Total VAT amount")
    total_ttc: float = Field(description="Total including tax")
    currency: Currency = Field(description="Currency")
    payment_method: Optional[str] = Field(default=None)

# Extraction
response = client.chat.parse(
    model="mistral-large-latest",
    messages=[
        {
            "role": "system",
            "content": """You are an accounting expert. Extract data from the invoice.
Be precise with amounts. Calculate totals if necessary.
Dates must be in YYYY-MM-DD format."""
        },
        {"role": "user", "content": invoice_text}
    ],
    response_format=InvoiceData,
    temperature=0
)

invoice = response.choices[0].message.parsed
print(f"Invoice {invoice.invoice_number} — {invoice.vendor_name}")
print(f"Total incl. tax: {invoice.total_ttc} {invoice.currency.value}")
for item in invoice.line_items:
    print(f"  - {item.description}: {item.quantity} x {item.unit_price}€ = {item.total_ht}€ excl. tax")

O formato de data imposto no prompt do sistema não é um detalhe menor: sem ele, um documento francês pode produzir 12/03/2026 enquanto um americano gera 03/12/2026, criando duas cadeias de caracteres indistinguíveis para a sua base de dados. A versão TypeScript segue a mesma arquitetura, com o formato documentado através de .describe().

import { z } from "zod";

const LineItemSchema = z.object({
  description: z.string(),
  quantity: z.number(),
  unitPrice: z.number().describe("Unit price excluding tax"),
  vatRate: z.number().describe("VAT rate in %"),
  totalHt: z.number(),
});

const InvoiceSchema = z.object({
  invoiceNumber: z.string(),
  date: z.string().describe("Format YYYY-MM-DD"),
  dueDate: z.string().nullable(),
  vendorName: z.string(),
  clientName: z.string(),
  lineItems: z.array(LineItemSchema),
  subtotalHt: z.number(),
  totalVat: z.number(),
  totalTtc: z.number(),
  currency: z.enum(["EUR", "USD", "GBP"]),
});

const response = await client.chat.parse({
  model: "mistral-large-latest",
  messages: [
    { role: "system", content: "Extract invoice data precisely." },
    { role: "user", content: invoiceText },
  ],
  responseFormat: InvoiceSchema,
  temperature: 0,
});

const invoice = response.choices[0].message.parsed!;
console.log(`Invoice ${invoice.invoiceNumber} — Total: ${invoice.totalTtc} ${invoice.currency}`);

Análise de Avaliações por Aspeto

Uma avaliação real de um cliente raramente é uniformemente positiva ou negativa. A avaliação do hotel abaixo elogia o quarto e o pequeno-almoço, condena o estacionamento e o Wi-Fi, e oferece uma visão nuances sobre a equipa: uma única pontuação global perderia toda esta informação. A solução consiste em modelar um AspectSentiment reutilizável e solicitar uma lista dos mesmos. O campo evidence é a parte mais interessante do esquema — ao exigir uma citação do texto, força o modelo a fundamentar o seu julgamento e dá-lhe os meios para o verificar.

from pydantic import BaseModel, Field

class AspectSentiment(BaseModel):
    aspect: str = Field(description="The aspect analyzed (quality, price, service, delivery, etc.)")
    sentiment: str = Field(description="positive, negative, or neutral")
    score: float = Field(description="Score between -1.0 (very negative) and 1.0 (very positive)")
    evidence: str = Field(description="Quote or excerpt from the text justifying the sentiment")

class ReviewAnalysis(BaseModel):
    overall_sentiment: str = Field(description="Overall sentiment: positive, negative, mixed, or neutral")
    overall_score: float = Field(description="Overall score between -1.0 and 1.0")
    aspects: list[AspectSentiment] = Field(description="Aspect-by-aspect analysis")
    recommendation: bool = Field(description="Does the author recommend the product/service?")
    key_strengths: list[str] = Field(description="Identified strengths")
    key_weaknesses: list[str] = Field(description="Identified weaknesses")

review_text = """
The hotel is magnificent; the room was spacious and clean. The breakfast is excellent
with a wide selection. However, the parking is outrageously expensive (€35/night) and the Wi-Fi was
unstable throughout the stay. The reception staff was very welcoming,
but room service took over an hour to deliver our order.
"""

response = client.chat.parse(
    model="mistral-large-latest",
    messages=[
        {
            "role": "system",
            "content": "Analyze this customer review by detailing each mentioned aspect."
        },
        {"role": "user", "content": review_text}
    ],
    response_format=ReviewAnalysis,
    temperature=0
)

review = response.choices[0].message.parsed
print(f"Overall sentiment: {review.overall_sentiment} ({review.overall_score:+.1f})")
for aspect in review.aspects:
    print(f"  [{aspect.score:+.1f}] {aspect.aspect}: {aspect.sentiment}")

Classificação de Texto em Múltiplas Categorias

Ao contrário da classificação simples, onde é atribuído um único rótulo, a classificação multi-rótulo reconhece que um texto pode pertencer a várias categorias. O incidente descrito abaixo toca simultaneamente em segurança, finanças, fraude e proteção de dados: forçar um único rótulo empobreceria a lógica de encaminhamento.

Dois elementos do esquema merecem atenção. O campo reasoning exige uma justificação para cada rótulo, o que melhora a qualidade da pontuação. O campo requires_human_review transforma a incerteza do modelo num sinal operacional: em vez de descobrir事后 que uma classificação era duvidosa, escala automaticamente o processo para um humano quando a confiança desce abaixo de 0,7.

from pydantic import BaseModel, Field

class LabelScore(BaseModel):
    label: str = Field(description="Category name")
    confidence: float = Field(description="Confidence score between 0.0 and 1.0")
    reasoning: str = Field(description="One-sentence justification")

class MultiLabelClassification(BaseModel):
    primary_label: str = Field(description="Primary category")
    all_labels: list[LabelScore] = Field(
        description="All applicable categories with their confidence scores"
    )
    requires_human_review: bool = Field(
        description="True if classification is uncertain (confidence < 0.7)"
    )

text = """
Our mobile payment application has a security vulnerability allowing
access to banking data. Several customers have reported unauthorized
transactions. The technical team is currently investigating.
"""

response = client.chat.parse(
    model="mistral-large-latest",
    messages=[
        {
            "role": "system",
            "content": """Classify this text among the following categories (multiple possible):
security, finance, technical, legal, customer_support, compliance, fraud, data_privacy.
Assign a confidence score to each applicable category."""
        },
        {"role": "user", "content": text}
    ],
    response_format=MultiLabelClassification,
    temperature=0
)

result = response.choices[0].message.parsed
print(f"Primary category: {result.primary_label}")
print(f"Human review required: {'Yes' if result.requires_human_review else 'No'}")
for label in result.all_labels:
    print(f"  [{label.confidence:.0%}] {label.label} — {label.reasoning}")

Fatorização da Chamada

Estes três exemplos partilham a mesma mecânica: um prompt do sistema, um texto, um esquema e temperature=0. Em vez de copiar a chamada para cada novo caso, extraia-a para uma função genérica. O TypeVar limitado a BaseModel preserva a tipagem: o objeto devolvido tem o tipo do esquema passado como argumento, e o seu IDE reconhece-o.

from typing import TypeVar, Type
from pydantic import BaseModel

T = TypeVar("T", bound=BaseModel)

def extract(client, text: str, schema: Type[T], system_prompt: str = "") -> T:
    """Reusable structured extraction."""
    messages = []
    if system_prompt:
        messages.append({"role": "system", "content": system_prompt})
    messages.append({"role": "user", "content": text})

    response = client.chat.parse(
        model="mistral-large-latest",
        messages=messages,
        response_format=schema,
        temperature=0
    )
    return response.choices[0].message.parsed

# Usage
invoice = extract(client, invoice_text, InvoiceData, "Extract invoice data.")
review = extract(client, customer_review, ReviewAnalysis, "Analyze this customer review.")
classification = extract(client, ticket, MultiLabelClassification, "Classify this text.")

Três casos de utilização muito diferentes, cada um exigindo apenas uma única linha de código para ser chamado: este é o benefício concreto de uma boa modelagem de esquemas.

Pontos-chave

  • Esquemas aninhados (list[LineItem], list[AspectSentiment]) permitem análises complexas
  • Enums (Currency, categorias) restringem os valores possíveis
  • O campo evidence / reasoning força o modelo a justificar as suas escolhas
  • Um wrapper genérico reduz a duplicação de código
  • temperature=0 é obrigatório para estes casos de utilização em produção