Casos de Utilização de Anotações
Nesta página
Atualização de 2 de novembro de 2026 — OCR. O OCR 4.0 (
mistral-ocr-4-0) foi descontinuado a 30 de setembro de 2026. Utilize o OCR 4.1 (mistral-ocr-4-1), geralmente disponível desde 31 de agosto pelo mesmo preço, ou o aliasmistral-ocr-latest, que aponta para ele desde 16 de julho. O OCR 4.1 adiciona pontuações de confiança ao nível do bloco. Adenda de 3 de novembro de 2026: Um PDF local é transmitido em base64 como{"type": "document_url", "document_url": "data:application/pdf;base64,…"}; o tipodocument_base64de exemplos anteriores não existe nem na documentação nem no SDKmistralai, e esses exemplos teriam falhado. Fontes: Processador OCR · QnA de Documentos. Corrigido a 3 de novembro de 2026: O código lia anteriormentepage.document_annotationpágina por página; no SDKmistralai3.7.0, a anotação do documento é um único campo na resposta (response.document_annotation), e a anotação de imagem é lida a partir deimage.image_annotation.
Anotações para Cada Função
As anotações de IA de documentos transformam documentos não estruturados em dados acionáveis. O mecanismo é sempre o mesmo — um esquema, um prompt, uma chamada — mas o que extrai muda radicalmente dependendo da função. Esta lição percorre quatro implementações concretas: classificação a montante num pipeline, análise de cláusulas contratuais, verificações de conformidade regulamentar e enriquecimento de um índice RAG.
Classificar Antes de Processar
Num fluxo de trabalho real, os documentos chegam misturados: uma fatura, uma ordem de compra, um cartão de identificação, uma carta. Antes de aplicar o esquema de extração adequado, precisa de saber com o que está a lidar. A anotação serve como a primeira etapa de triagem. O enumerado TypeDocument fixa as categorias admissíveis, a pontuação de confiança permite encaminhar tudo o que esteja abaixo de um limiar para revisão humana, e o resumo de uma frase dá aos operadores contexto suficiente para tomar uma decisão sem abrir o ficheiro.
import os
from enum import Enum
from pydantic import BaseModel, Field
from mistralai.client import Mistral
from mistralai.extra import response_format_from_pydantic_model
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
class TypeDocument(str, Enum):
INVOICE = "facture"
PURCHASE_ORDER = "bon_commande"
CONTRACT = "contrat"
REPORT = "rapport"
LETTER = "courrier"
FORM = "formulaire"
ID_DOCUMENT = "piece_identite"
OTHER = "autre"
class Classification(BaseModel):
document_type: TypeDocument = Field(
..., description="Identified document type"
)
confidence: float = Field(
..., description="Confidence score between 0 and 1"
)
language: str = Field(
..., description="Primary language (ISO 639-1 code)"
)
summary: str = Field(
..., description="One-sentence summary of the content"
)
def classify_document(document_base64: str) -> Classification:
"""Classifica automaticamente um documento."""
response = client.ocr.process(
model="mistral-ocr-latest",
document={
"type": "document_url",
"document_url": f"data:application/pdf;base64,{document_base64}"
},
document_annotation_format=response_format_from_pydantic_model(
Classification
),
document_annotation_prompt=(
"Identify the type of this document and provide "
"a summary of its content."
)
)
if response.document_annotation:
return Classification.model_validate_json(
response.document_annotation
)
raise ValueError("No annotation returned")
Ler um Contrato Como um Advogado
A análise contratual é um caso de utilização importante nas áreas jurídica e financeira, e é onde os esquemas aninhados realmente se destacam. Cada Clause carrega o seu título, um resumo do conteúdo, a sua categoria — confidencialidade, rescisão, não concorrência, responsabilidade, pagamento — e uma avaliação de risco em três níveis. O próprio contrato agrega estas cláusulas juntamente com as partes, data de assinatura, duração, montante e jurisdição aplicável. Num portefólio de duzentos contratos de fornecedores, obtém em poucas horas um mapeamento que ninguém teria tempo de produzir manualmente.
O campo risk merece um aviso: é uma avaliação produzida por um modelo, útil para priorizar a revisão de um advogado, nunca para a substituir.
from pydantic import BaseModel, Field
from typing import Optional
class Clause(BaseModel):
title: str = Field(..., description="Title or number of the clause")
content: str = Field(..., description="Summary of the clause content")
clause_type: str = Field(
..., description="Type: confidentiality, termination, "
"non-compete, liability, payment, other"
)
risk: str = Field(
..., description="Risk level: low, medium, high"
)
class ContractAnalysis(BaseModel):
parts: list[str] = Field(
..., description="Names of the contracting parts"
)
signature_date: Optional[str] = Field(
None, description="Signature date (YYYY-MM-DD)"
)
duration: Optional[str] = Field(
None, description="Contract duration"
)
key_clauses: list[Clause] = Field(
..., description="Identified main clauses"
)
amount: Optional[float] = Field(
None, description="Total amount if mentioned"
)
jurisdiction: Optional[str] = Field(
None, description="Applicable jurisdiction"
)
def analyze_contract(document_base64: str) -> ContractAnalysis:
"""Analisa um contrato e extrai as cláusulas principais."""
response = client.ocr.process(
model="mistral-ocr-latest",
document={
"type": "document_url",
"document_url": f"data:application/pdf;base64,{document_base64}"
},
document_annotation_format=response_format_from_pydantic_model(
ContractAnalysis
),
document_annotation_prompt=(
"Analyze this commercial contract. Identify the parts, "
"the main clauses, and evaluate the risk level "
"of each clause."
)
)
if response.document_annotation:
return ContractAnalysis.model_validate_json(
response.document_annotation
)
raise ValueError("No annotation returned")
Verificar a Conformidade Automaticamente
O controlo regulamentar é particularmente adequado para anotação porque os critérios estão escritos preto no branco na lei. Para uma fatura francesa, o prompt lista as obrigações a verificar — menções obrigatórias (SIRET, IVA intracomunitário, condições de pagamento, penalidades por atraso), formatação do montante, data de emissão — e o esquema impõe, para cada critério, um veredito booleano acompanhado da sua justificação. Recupera uma pontuação global e recomendações de melhoria, o que é suficiente para bloquear uma fatura não conforme antes de entrar no circuito de pagamentos.
from pydantic import BaseModel, Field
class CompliancePoint(BaseModel):
criterion: str = Field(..., description="Compliance criterion checked")
compliant: bool = Field(..., description="True if compliant, False otherwise")
justification: str = Field(
..., description="Explanation of compliance or non-compliance"
)
class ComplianceAudit(BaseModel):
document_type: str = Field(..., description="Type of document audited")
compliance_points: list[CompliancePoint] = Field(
..., description="Compliance points checked"
)
global_score: float = Field(
..., description="Global compliance score (0-100)"
)
recommendations: list[str] = Field(
..., description="Improvement recommendations"
)
def audit_invoice_compliance(document_base64: str) -> ComplianceAudit:
"""Verifica a conformidade da fatura segundo as regras francesas."""
response = client.ocr.process(
model="mistral-ocr-latest",
document={
"type": "document_url",
"document_url": f"data:application/pdf;base64,{document_base64}"
},
document_annotation_format=response_format_from_pydantic_model(
ComplianceAudit
),
document_annotation_prompt=(
"Verify the compliance of this invoice according to "
"French legal obligations: mandatory mentions "
"(SIRET, intra-community VAT, payment terms, "
"late payment penalties), amount formatting, issue date."
)
)
if response.document_annotation:
return ComplianceAudit.model_validate_json(
response.document_annotation
)
raise ValueError("No annotation returned")
Não Perder Nada Antes da Indexação
Um último caso de utilização, mais discreto mas decisivo: preparar conteúdo para um índice RAG. Um índice construído apenas em Markdown perde tudo o que era visual, e as suas pesquisas nunca encontrarão o gráfico que continha o dado chave. A função abaixo recompõe, página a página, o texto e a descrição de cada imagem, adicionando depois os metadados extraídos do documento, num único bloco pronto para ser dividido em fragmentos.
def enrich_for_rag(ocr_response) -> str:
"""Enriquece o conteúdo OCR com anotações para RAG."""
parts = []
for page in ocr_response.pages:
# Text content
parts.append(page.markdown)
# Image annotations (replace images with their description)
for image in page.images:
if image.image_annotation:
parts.append(
f"[Description of {image.id}]: {image.image_annotation}"
)
# Document annotation: a single one, carried by the response
if ocr_response.document_annotation:
parts.append(
f"[Extracted Metadata]: {ocr_response.document_annotation}"
)
return "\n\n".join(parts)
Ao adicionar descrições de imagens e metadados extraídos ao conteúdo indexado, não perde nenhuma informação do documento original. Notará que estes quatro cenários partilham a mesma espinha dorsal: o que os distingue é o esquema e o prompt, não o código de chamada.
Pontos-chave
- A classificação automática encaminha documentos para o pipeline de processamento correto
- A extração de cláusulas contratuais identifica riscos e pontos chave
- A verificação de conformidade automatiza auditorias regulamentares
- O enriquecimento por anotação melhora a qualidade da indexação RAG
- Cada caso de utilização resume-se a um esquema Pydantic bem desenhado e um prompt adaptado