A API de Anotações
Nesta página
Atualizado em 2 de novembro de 2026 — OCR. O OCR 4.0 (
mistral-ocr-4-0) foi desativado em 30 de setembro de 2026. Utilize o OCR 4.1 (mistral-ocr-4-1), disponível para uso geral desde 31 de agosto pelo mesmo preço, ou o aliasmistral-ocr-latest, que aponta para esta versão desde 16 de julho. O OCR 4.1 adiciona pontuações de confiança ao nível do bloco. Adenda de 3 de novembro: O exemplo anterior liapage.document_annotationem cada página; no SDKmistralai3.7.0, este campo pertence à resposta do OCR (ocr_response.document_annotation), enquanto as páginas contêm apenas o seu conteúdo e imagens; as anotações de imagem são lidas a partir deimage.image_annotation.
Para Além da Extração de Texto
O OCR fornece-lhe texto bruto: fiel e completo, mas indiferenciado. Obtém Markdown, não dados. As anotações dão o passo seguinte: extraem dados estruturados dos seus documentos com base num esquema que define antecipadamente. Descreve o que procura, o modelo extrai-o automaticamente e a sua aplicação recebe campos tipados em vez de uma parede de texto para analisar com expressões regulares.
Dois Níveis de Análise
O Document AI distingue dois tipos de anotações com base na escala em que operam.
As anotações de caixa delimitadora (bbox_annotation) focam-se nas imagens e gráficos que o OCR isolou. O modelo de visão processa cada caixa delimitadora individualmente para descrever o seu conteúdo. Num relatório anual, este mecanismo permite-lhe descrever gráficos e diagramas, classificar imagens (fotografia, logótipo, esquema, gráfico) e extrair conteúdo textual de imagens incorporadas — três informações que a extração de texto padrão ignora sistematicamente.
As anotações de documento (document_annotation) tratam o ficheiro como um todo. O modelo analisa o Markdown extraído juntamente com as primeiras oito imagens e devolve o que pediu: campos estruturados como um nome, data ou montante; o tipo de documento; um resumo do conteúdo; ou uma resposta a uma pergunta específica. Esta é a ferramenta para processamento em lote, aquela que integrará nos seus fluxos de trabalho de faturas, formulários e contratos.
O Esquema Pydantic Atua como Contrato
As anotações dependem de modelos Pydantic para definir a estrutura de saída. Cada atributo torna-se num campo a extrair e a sua description serve de instrução ao modelo: tem tanto peso como o próprio nome do campo.
from pydantic import BaseModel, Field
from typing import Optional
class InvoiceExtraction(BaseModel):
vendor: str = Field(..., description="Vendor name")
invoice_number: str = Field(..., description="Invoice number")
issue_date: str = Field(..., description="Issue date (YYYY-MM-DD)")
amount_excl_tax: float = Field(..., description="Amount excluding tax")
amount_incl_tax: float = Field(..., description="Amount including tax")
currency: str = Field(default="EUR", description="Currency (ISO code)")
Anotar um Documento Inteiro
A chamada permanece a mesma que para o OCR: basta adicionar o parâmetro document_annotation_format, preenchido por response_format_from_pydantic_model(), que traduz o seu modelo num esquema que a API pode utilizar. No retorno, a anotação chega como uma cadeia JSON, que revalida com o Pydantic para obter um objeto Python seguro.
import os
from mistralai.client import Mistral
from mistralai.extra import response_format_from_pydantic_model
from pydantic import BaseModel, Field
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
class InvoiceExtraction(BaseModel):
vendor: str = Field(..., description="Vendor name")
invoice_number: str = Field(..., description="Invoice number")
issue_date: str = Field(..., description="Issue date (YYYY-MM-DD)")
amount_excl_tax: float = Field(..., description="Amount excluding tax")
amount_incl_tax: float = Field(..., description="Amount including tax")
ocr_response = client.ocr.process(
model="mistral-ocr-latest",
document={
"type": "document_url",
"document_url": "https://example.com/invoice.pdf"
},
document_annotation_format=response_format_from_pydantic_model(
InvoiceExtraction
)
)
# A anotação do documento é transportada pela resposta, não por cada página
if ocr_response.document_annotation:
invoice = InvoiceExtraction.model_validate_json(
ocr_response.document_annotation
)
print(f"Vendor: {invoice.vendor}")
print(f"Amount incl. tax: {invoice.amount_incl_tax}")
Descrever Visuais Um a Um
Para imagens, o princípio é idêntico, mas o parâmetro muda e os resultados são lidos a partir de page.images em vez da própria página. Note include_image_base64=True: sem isto, perde os visuais que o modelo acabou de descrever.
from pydantic import BaseModel, Field
from mistralai.extra import response_format_from_pydantic_model
class ImageDescription(BaseModel):
image_type: str = Field(
..., description="Type: graph, table, photo, logo, schematic"
)
description: str = Field(
..., description="Short description of the image in English"
)
relevant_content: str = Field(
..., description="Summary of the informative content of the image"
)
ocr_response = client.ocr.process(
model="mistral-ocr-latest",
document={
"type": "document_url",
"document_url": "https://example.com/report.pdf"
},
bbox_annotation_format=response_format_from_pydantic_model(
ImageDescription
),
include_image_base64=True
)
# Aceder às anotações de imagem
for page in ocr_response.pages:
for image in page.images:
if image.image_annotation:
desc = ImageDescription.model_validate_json(image.image_annotation)
print(f"Image {image.id}: {desc.image_type}")
print(f" Description: {desc.description}")
Nada o obriga a escolher entre os dois: num relatório ilustrado, geralmente quererá tanto os metadados do documento como a descrição dos seus gráficos, o que uma única chamada cobre ao passar ambos os formatos.
ocr_response = client.ocr.process(
model="mistral-ocr-latest",
document={
"type": "document_url",
"document_url": "https://example.com/report.pdf"
},
bbox_annotation_format=response_format_from_pydantic_model(
ImageDescription
),
document_annotation_format=response_format_from_pydantic_model(
InvoiceExtraction
),
include_image_base64=True
)
Orientar a Extração com um Prompt
Um esquema descreve a forma esperada, não o contexto do documento. Quando os seus campos são ambíguos — múltiplas datas, múltiplos montantes, duas secções semelhantes —, o document_annotation_prompt ajuda a resolver a dúvida, indicando ao modelo a natureza do documento e o que priorizar. Num contrato comercial francês, esta frase de enquadramento faz frequentemente a diferença entre uma extração utilizável e um preenchimento aproximado.
ocr_response = client.ocr.process(
model="mistral-ocr-latest",
document={
"type": "document_url",
"document_url": "https://example.com/contract.pdf"
},
document_annotation_format=response_format_from_pydantic_model(
ContractExtraction
),
document_annotation_prompt=(
"This document is a French commercial contract. "
"Extract information about the contracting parties, "
"the contract duration, and the main clauses."
)
)
Pontos-chave
- Dois tipos de anotações:
bbox_annotationpara imagens,document_annotationpara o documento inteiro - Esquemas Pydantic definem a estrutura dos dados a extrair
- Utilize
response_format_from_pydantic_model()para converter o esquema - O
document_annotation_promptorienta a extração com instruções contextuais - Ambos os tipos podem ser combinados numa única chamada