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

A Sua Primeira Chamada OCR em Python

Aula 5 de 16 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. Da Teoria ao Código
  2. O Script Mínimo
  3. Processamento de um Ficheiro do Seu Computador
  4. Guardar a Extração
  5. O Caso de uma Imagem Isolada
  6. Reconstruir um Documento Ilustrado
  7. Pontos-chave

Atualizado em 2 de novembro de 2026 — OCR. O OCR 4.0 (mistral-ocr-4-0) foi desativado a 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 de 2026: Um PDF local é transmitido em base64 como {"type": "document_url", "document_url": "data:application/pdf;base64,…"}; o tipo document_base64 de exemplos anteriores não existe nem na documentação nem no SDK mistralai, e esses exemplos teriam falhado. Fontes: OCR Processor · Document QnA.

Da Teoria ao Código

Já conhece o endpoint e os seus parâmetros. É altura de escrever um script completo que extraia texto de um PDF, desde a primeira linha de importação até ao ficheiro Markdown guardado no seu disco. Começaremos pelo caso mais simples — um documento público — e avançaremos depois para o que encontrará na prática: ficheiros locais, imagens isoladas e documentos ilustrados que necessitam de reconstrução.

Dois pré-requisitos, já abordados, mas que vale a pena verificar antes de perder dez minutos com um erro de autenticação:

pip install mistralai
export MISTRAL_API_KEY="your-api-key"

O Script Mínimo

Eis a extração completa de um PDF acessível online. Três linhas úteis: instanciar o cliente, chamar process e iterar sobre as páginas.

import os
from mistralai.client import Mistral

# Initialize the client
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

# OCR call on a public PDF
ocr_response = client.ocr.process(
    model="mistral-ocr-latest",
    document={
        "type": "document_url",
        "document_url": "https://arxiv.org/pdf/2201.04234"
    }
)

# Display the number of pages
print(f"Number of pages: {len(ocr_response.pages)}")

# Display the content of each page
for page in ocr_response.pages:
    print(f"\n--- Page {page.index + 1} ---")
    print(page.markdown)

Note o page.index + 1: o índice devolvido pela API começa em zero, enquanto os seus utilizadores contam a partir de um. É um desvio menor, desde que o tenha em mente, mas uma fonte de confusão duradoura quando o descobre num relatório entregue a um cliente.

Processamento de um Ficheiro do Seu Computador

Na vida real, os documentos raramente chegam através de um URL público. Tem-nos no seu disco, são confidenciais, pelo que os codifica em base64. O script seguinte processa uma fatura de fornecedor e concatena todas as páginas num único bloco de texto:

import os
import base64
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

# Read and encode the local file
file_path = "supplier_invoice.pdf"

with open(file_path, "rb") as f:
    document_base64 = base64.b64encode(f.read()).decode("utf-8")

# OCR call
ocr_response = client.ocr.process(
    model="mistral-ocr-latest",
    document={
        "type": "document_url",
        "document_url": f"data:application/pdf;base64,{document_base64}"
    }
)

# Concatenate all text
full_text = "\n\n".join(
    page.markdown for page in ocr_response.pages
)

print(full_text)

A concatenação via "\n\n".join(...) funciona bem para visualização ou pesquisa de texto integral. No entanto, apaga a fronteira entre páginas: se mais tarde precisar de citar uma fonte ou direcionar um utilizador para a página correta de um contrato, preserve a estrutura página a página em vez deste bloco único.

Guardar a Extração

Cada chamada OCR custa dinheiro e demora tempo. Voltar a executar a extração do mesmo relatório de duzentas páginas porque se esqueceu de guardar o resultado é um erro que só se comete uma vez. A função abaixo escreve o Markdown num ficheiro, marcando as quebras de página com um comentário e um separador:

import os
import base64
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

def extract_pdf(pdf_path: str, output_path: str) -> None:
    """Extracts text from a PDF and saves it as Markdown."""

    with open(pdf_path, "rb") as f:
        document_base64 = base64.b64encode(f.read()).decode("utf-8")

    ocr_response = client.ocr.process(
        model="mistral-ocr-latest",
        document={
            "type": "document_url",
            "document_url": f"data:application/pdf;base64,{document_base64}"
        }
    )

    with open(output_path, "w", encoding="utf-8") as f:
        for page in ocr_response.pages:
            f.write(f"<!-- Page {page.index + 1} -->\n\n")
            f.write(page.markdown)
            f.write("\n\n---\n\n")

    print(f"Extraction complete: {len(ocr_response.pages)} pages")
    print(f"Result saved to: {output_path}")


# Usage
extract_pdf("annual_report.pdf", "annual_report.md")

O comentário HTML <!-- Page N --> é invisível na vista renderizada, mas permanece presente no ficheiro: pode encontrá-lo via expressão regular para reconstruir a paginação durante a indexação.

O Caso de uma Imagem Isolada

O OCR 4 não se limita a PDFs. Uma fotografia de uma fatura tirada com um telemóvel, um recibo digitalizado, uma captura de ecrã — tudo é enviado da mesma forma, utilizando o tipo image_base64:

import os
import base64
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

# Encode an image
with open("scanned_invoice.png", "rb") as f:
    image_base64 = base64.b64encode(f.read()).decode("utf-8")

# OCR call on an image
ocr_response = client.ocr.process(
    model="mistral-ocr-latest",
    document={
        "type": "image_base64",
        "image_base64": image_base64
    }
)

# A single "page" for an image
print(ocr_response.pages[0].markdown)

A resposta mantém a mesma forma: uma lista de páginas, que neste caso contém apenas uma. O seu código de processamento permanece, portanto, idêntico independentemente do tipo de ficheiro de entrada, o que simplifica bastante os pipelines mistos.

Reconstruir um Documento Ilustrado

O Markdown devolvido referencia imagens como ![imageN.jpg](imageN.jpg), sem as incorporar. Se quiser um ficheiro autónomo — um relatório legível offline, uma pré-visualização para enviar por e-mail — solicite as imagens em base64 e substitua cada referência por um URI de dados:

import os
import base64
import re
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

ocr_response = client.ocr.process(
    model="mistral-ocr-latest",
    document={
        "type": "document_url",
        "document_url": "https://arxiv.org/pdf/2201.04234"
    },
    include_image_base64=True
)

for page in ocr_response.pages:
    markdown = page.markdown

    # Replace image references with base64
    for image in page.images:
        placeholder = f"![{image.id}]({image.id})"
        data_uri = f"![{image.id}](data:image/jpeg;base64,{image.image_base64})"
        markdown = markdown.replace(placeholder, data_uri)

    print(markdown[:500])

O ficheiro resultante cresce rapidamente, uma vez que o base64 pesa cerca de um terço a mais do que o binário original. Reserve esta reconstrução para documentos que necessite de tornar autónomos e mantenha as imagens como ficheiros separados nos seus pipelines de indexação.

Antes de avançar, pegue num documento que possua — uma fatura, um contrato, uma página digitalizada — e execute-o através do script de extração local. Compare o Markdown resultante com o original, linha por linha: as discrepâncias que encontrar, uma tabela mal reconstruída ou um cabeçalho absorvido pelo corpo do texto, são exatamente os problemas que as próximas três lições lhe ensinarão a tratar.

Pontos-chave

  • A chamada OCR leva 3 linhas: cliente, process, ler páginas
  • Utilize base64 para ficheiros locais, URL para documentos públicos
  • O resultado é Markdown estruturado, pronto a usar
  • As imagens extraídas podem ser recombinadas com o texto
  • Guarde sempre as suas extrações para evitar chamadas API repetidas