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

A API de Anotações

Aula 9 de 16 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. Para Além da Extração de Texto
  2. Dois Níveis de Análise
  3. O Esquema Pydantic Atua como Contrato
  4. Anotar um Documento Inteiro
  5. Descrever Visuais Um a Um
  6. Orientar a Extração com um Prompt
  7. Pontos-chave

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 alias mistral-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 lia page.document_annotation em cada página; no SDK mistralai 3.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 de image.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_annotation para imagens, document_annotation para 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_prompt orienta a extração com instruções contextuais
  • Ambos os tipos podem ser combinados numa única chamada