Ferramenta document_library: Perguntas e Respostas sobre os Seus Ficheiros
Nesta página
Lição atualizada em 3 de novembro de 2026 com base no SDK
mistralai3.7.0: os documentos da biblioteca são geridos através declient.beta.libraries.documents(upload,list,delete). Os métodosadd_document,list_documentseremove_documentda versão anterior deixaram de existir, e os carregamentos são feitos diretamente na biblioteca. Fonte: client-python.
RAG Integrado da Mistral
A ferramenta document_library é um sistema de Geração Aumentada por Recuperação (RAG) integrado diretamente na API de Agentes. O seu agente acede aos documentos que carregou na nuvem da Mistral, recupera passagens relevantes e formula a sua resposta com citações. A diferença em relação a uma solução RAG desenvolvida internamente é significativa: não precisa de alojar uma base de dados vetorial, manter um pipeline de incorporação (embedding) ou afinar uma estratégia de fragmentação. Basta carregar ficheiros, declarar a ferramenta ao criar o agente e deixar o modelo decidir quando consultar a biblioteca.
Criar uma Biblioteca de Documentos
Uma biblioteca é o contentor que guarda os seus documentos. Cria-a com uma única chamada à API antes de carregar qualquer ficheiro.
from mistralai.client import Mistral
import os
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# Criar uma biblioteca
library = client.beta.libraries.create(
name="Documentação Técnica",
description="Manuais de produto e especificações técnicas."
)
print(f"ID da Biblioteca: {library.id}")
Tome nota do ID devolvido: é isto que passa ao agente. Não existe nenhum atalho que utilize o nome da biblioteca. Se a sua equipa gerir bibliotecas separadas para RH, jurídico e técnico, guarde estes IDs na sua configuração tal como faria com cadeias de ligação.
Carregar Documentos
O carregamento ocorre em duas etapas: primeiro, o ficheiro é depositado no espaço de Ficheiros com um purpose explícito; depois, é anexado à biblioteca.
# Carregar um PDF diretamente para a biblioteca
with open("product-manual.pdf", "rb") as f:
document = client.beta.libraries.documents.upload(
library_id=library.id,
file={"file_name": "product-manual.pdf", "content": f},
)
print(f"Documento {document.id}: {document.processing_status}")
Os formatos suportados incluem PDF, texto simples e outros tipos de documentos comuns.
Criar um Agente com uma Biblioteca de Documentos
agent = client.beta.agents.create(
model="mistral-medium-latest",
name="Agente de Documentação",
instructions="""Você é um assistente de documentação.
- Responda apenas utilizando documentos da biblioteca
- Cite as passagens relevantes
- Se a informação não estiver nos documentos, indique-o claramente""",
tools=[{
"type": "document_library",
"library_ids": [library.id]
}]
)
O parâmetro library_ids é uma lista: pode associar múltiplas bibliotecas a um único agente. Por exemplo, um assistente de suporte pode utilizar tanto a documentação do produto como os procedimentos internos. Aqui, as instruções são mais do que um extra agradável. Sem a diretiva para limitar as respostas aos documentos, o modelo preenche as lacunas com o seu conhecimento geral e perde a capacidade de distinguir o que provém dos seus ficheiros do que vem de outra fonte. A terceira linha — indicar explicitamente quando falta informação — é o que transforma um agente tagarela num agente fiável.
Consultar os Documentos
response = client.beta.conversations.start(
agent_id=agent.id,
inputs="Como funciona o codificador de visão Pixtral 12B?"
)
for entry in response.outputs:
if entry.type == "message.output":
for chunk in entry.content:
if chunk.type == "text":
print(chunk.text)
elif chunk.type == "tool_reference":
print(f" [Fonte] {chunk.title}")
Tal como na pesquisa na Web, a resposta chega em fragmentos de dois tipos. Os fragmentos text contêm a resposta escrita; os fragmentos tool_reference contêm a proveniência, com o campo title a guardar o nome do documento de origem e o campo url a fornecer a referência interna nesse documento. Esta separação permite-lhe apresentar a resposta e, logo abaixo, a lista de documentos que a produziram.
Esta rastreabilidade não é apenas decorativa. Um consultor que responda a um cliente com base num procedimento interno deve ser capaz de especificar qual o procedimento que está a citar; um advogado que se baseie num contrato deve poder rastrear esse contrato. Sem citações, um sistema RAG produz alegações inverificáveis.
Gerir Bibliotecas
# Listar bibliotecas
libraries = client.beta.libraries.list()
for lib in libraries.data:
print(f"{lib.name} ({lib.id})")
# Listar documentos numa biblioteca
documents = client.beta.libraries.documents.list(library_id=library.id)
for doc in documents.data:
print(f"{doc.name} — {doc.size} bytes")
# Eliminar um documento da biblioteca
client.beta.libraries.documents.delete(
library_id=library.id,
document_id=document.id
)
# Eliminar a biblioteca
client.beta.libraries.delete(library_id=library.id)
A remoção de documentos é a operação mais frequentemente negligenciada e a mais dispendiosa quando esquecida. Uma versão desatualizada de uma lista de preços ou de um procedimento permanece citável pelo agente indefinidamente, mantendo toda a aparência de legitimidade por ser uma fonte. Torne a remoção de um documento um reflexo sempre que publicar uma nova versão.
Do Suporte Interno à Análise de Contratos
O suporte interno é o caso de uso mais imediato: os colaboradores colocam perguntas de RH em linguagem natural em vez de vasculhar uma intranet.
agent = client.beta.agents.create(
model="mistral-large-latest",
name="Suporte Interno",
instructions="Responda às perguntas dos colaboradores utilizando a base de documentação de RH.",
tools=[{"type": "document_library", "library_ids": [rh_library.id]}]
)
A análise de contratos muda o paradigma: o agente não apenas recupera, ele examina. Aqui, as instruções descrevem uma tarefa, não apenas um âmbito.
agent = client.beta.agents.create(
model="mistral-large-latest",
name="Analista de Contratos",
instructions="""Analise os contratos carregados.
- Identifique cláusulas importantes
- Sinalize riscos potenciais
- Compare com os padrões da indústria""",
tools=[{"type": "document_library", "library_ids": [contrats_library.id]}]
)
Por fim, uma base de conhecimento de produtos ilustra a combinação de ferramentas: a documentação oficial tem precedência e a pesquisa na Web preenche as lacunas quando os documentos não cobrem uma questão.
agent = client.beta.agents.create(
model="mistral-large-latest",
name="Especialista de Produto",
instructions="Responda a perguntas técnicas sobre os nossos produtos com base na documentação oficial.",
tools=[
{"type": "document_library", "library_ids": [docs_library.id]},
{"type": "web_search"} # Fallback se a documentação for insuficiente
]
)
Preparar Fontes, Isolar Bibliotecas
A qualidade do RAG é determinada antes mesmo de chamar a API. Um PDF estruturado com títulos, subtítulos e parágrafos distintos fragmenta-se e recupera-se muito melhor do que uma digitalização achatada ou um documento onde toda a lógica reside no layout. Em seguida, separe as suas bibliotecas por domínio em vez de criar um único repositório genérico. Um agente ligado apenas à biblioteca jurídica não correrá o risco de citar um memorando de RH para responder a uma questão contratual. Estas duas decisões — polir a estrutura da fonte e isolar as bibliotecas — impactam o resultado final mais do que qualquer afinamento do modelo.
Pontos-chave
document_libraryé um RAG integrado — não precisa de gerir a sua própria infraestrutura vetorial- Crie bibliotecas temáticas e carregue documentos através da API de Ficheiros
- As respostas citam passagens relevantes utilizando fragmentos
tool_reference - Pode associar múltiplas bibliotecas a um único agente
- Combine com outras ferramentas para uma cobertura abrangente