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

A API Document QnA

Aula 13 de 16 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. Consulte os seus documentos em linguagem natural
  2. Um endpoint diferente do OCR
  3. Três formas de enviar o documento
  4. Qual modelo de chat para qual pergunta
  5. Encadear perguntas
  6. O que o QnA não fará por si
  7. Pontos-chave

Lição atualizada em 3 de novembro de 2026. Adenda de 3 de novembro de 2026: Para enviar um PDF local, transmita-o em base64 no formato {"type": "document_url", "document_url": "data:application/pdf;base64,…"}. O tipo document_base64, encontrado em exemplos mais antigos, não existe na documentação nem no SDK mistralai, e esses exemplos teriam falhado. Fontes: OCR Processor · Document QnA.

Consulte os seus documentos em linguagem natural

O Document QnA combina OCR com um LLM da Mistral, permitindo-lhe fazer perguntas diretamente sobre o conteúdo do seu documento. Em vez de analisar cinquenta páginas para encontrar uma cláusula ou um valor específico, basta fazer a pergunta e ler a resposta. Internamente, o serviço executa duas etapas: o OCR extrai o texto, a estrutura e a formatação; em seguida, um modelo de chat da Mistral analisa o conteúdo extraído para gerar uma resposta. Esta combinação é transparente para si: uma única chamada à API trata de tudo.

Um endpoint diferente do OCR

É aqui que muitas pessoas tropeçam na primeira tentativa. O OCR puro utiliza client.ocr.process, enquanto o QnA usa o endpoint de Chat padrão client.chat.complete, com uma mensagem que contém tanto um bloco de texto como um bloco document_url. Por outras palavras, o documento torna-se um anexo à sua pergunta, tal como uma imagem numa troca multimodal.

import os
from mistralai.client import Mistral

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

# Pergunta sobre um documento público
response = client.chat.complete(
    model="mistral-small-latest",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "What is the total revenue mentioned?"
                },
                {
                    "type": "document_url",
                    "document_url": "https://example.com/annual-report.pdf"
                }
            ]
        }
    ]
)

print(response.choices[0].message.content)

Três formas de enviar o documento

Um URL público é a via mais direta, ideal para documentos já acessíveis online — como uma publicação científica, um relatório institucional ou um PDF alojado no seu sítio web.

messages = [
    {
        "role": "user",
        "content": [
            {"type": "text", "text": "Summarize the main points."},
            {
                "type": "document_url",
                "document_url": "https://arxiv.org/pdf/1805.04770"
            }
        ]
    }
]

response = client.chat.complete(
    model="mistral-small-latest",
    messages=messages
)

Os ficheiros locais, por outro lado, são enviados em base64. Este é o modo padrão sempre que um documento é confidencial ou está armazenado atrás da sua firewall; nada precisa de ser publicado na web para ser consultado.

import base64

with open("contract.pdf", "rb") as f:
    doc_base64 = base64.b64encode(f.read()).decode("utf-8")

messages = [
    {
        "role": "user",
        "content": [
            {
                "type": "text",
                "text": "What are the termination clauses?"
            },
            {
                "type": "document_url",
                "document_url": f"data:application/pdf;base64,{doc_base64}"
            }
        ]
    }
]

response = client.chat.complete(
    model="mistral-small-latest",
    messages=messages
)

Finalmente, existe uma terceira opção para ficheiros já carregados através da Files API: carrega uma vez com purpose="ocr" e, em seguida, referencia o ID resultante quantas vezes forem necessárias. Para um documento que planeia consultar várias vezes, isto evita voltar a carregar vários megabytes a cada pergunta.

uploaded = client.files.upload(
    file=open("report.pdf", "rb"),
    purpose="ocr"
)

messages = [
    {
        "role": "user",
        "content": [
            {"type": "text", "text": "What is the planned budget?"},
            {"type": "file_id", "file_id": uploaded.id}
        ]
    }
]

response = client.chat.complete(
    model="mistral-small-latest",
    messages=messages
)

Qual modelo de chat para qual pergunta

O parâmetro model fica ao seu critério e impacta tanto a qualidade da resposta como o custo.

ModeloPerfilQuando escolher
mistral-small-latestRápido e económicoSuficiente para a maioria das perguntas
mistral-medium-latestBom compromissoEquilíbrio entre velocidade e precisão
mistral-large-latestMais precisoAnálise e raciocínio complexos

A sua escolha depende da complexidade das suas perguntas e do seu orçamento: extrair um montante de uma fatura não exige o mesmo modelo que comparar regimes de responsabilidade entre dois contratos.

Encadear perguntas

Não precisa de fazer tudo de uma vez. Envia o documento na primeira mensagem, adiciona a resposta do modelo ao histórico e, em seguida, faz a sua pergunta de acompanhamento apenas como texto: o contexto do documento permanece na conversa. Esta é a forma natural de explorar um relatório — comece com um resumo e depois aprofunde o ponto que lhe interessa.

history = [
    {
        "role": "user",
        "content": [
            {"type": "text", "text": "Summarize this document in 3 points."},
            {
                "type": "document_url",
                "document_url": "https://example.com/report.pdf"
            }
        ]
    }
]

# Primeira chamada
response = client.chat.complete(
    model="mistral-small-latest",
    messages=history
)

# Adicionar resposta ao histórico
history.append({
    "role": "assistant",
    "content": response.choices[0].message.content
})

# Pergunta de acompanhamento
history.append({
    "role": "user",
    "content": "Detail the second point."
})

response = client.chat.complete(
    model="mistral-small-latest",
    messages=history
)

print(response.choices[0].message.content)

O que o QnA não fará por si

Quatro limitações vale a pena conhecer antes de construir um serviço sobre esta base. Primeiro, o tamanho: 50 MB por ficheiro e um máximo de 1.000 páginas, o que exclui grandes arquivos sem uma divisão prévia. Segundo, o custo, uma vez que documentos longos consomem muitos tokens de entrada a cada pergunta feita. Terceiro, a falta de memória persistente significa que deve reconstruir o histórico por si próprio; cada chamada é independente fora de uma conversa com várias intervenções. O ponto mais delicado é o último: o LLM interpreta tanto quanto extrai, o que pode introduzir erros em valores precisos. Para um montante que vá para a contabilidade, prefira anotação estruturada; reserve o QnA para compreensão e síntese.

Pontos-chave

  • O Document QnA utiliza o endpoint de Chat com conteúdo document_url: seja um URL público ou um PDF codificado em base64 como um data URL
  • O fluxo de trabalho interno é OCR seguido de LLM, mas apenas uma chamada é necessária
  • Três métodos de envio: URL, base64, ficheiro carregado
  • Conversas com várias intervenções permitem uma análise aprofundada
  • Escolha o seu modelo de chat com base na complexidade das suas perguntas