A API Document QnA
Nesta página
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 tipodocument_base64, encontrado em exemplos mais antigos, não existe na documentação nem no SDKmistralai, 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.
| Modelo | Perfil | Quando escolher |
|---|---|---|
mistral-small-latest | Rápido e económico | Suficiente para a maioria das perguntas |
mistral-medium-latest | Bom compromisso | Equilíbrio entre velocidade e precisão |
mistral-large-latest | Mais preciso | Aná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