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

Ferramenta document_library: Perguntas e Respostas sobre os Seus Ficheiros

Aula 11 de 18 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. RAG Integrado da Mistral
  2. Criar uma Biblioteca de Documentos
  3. Carregar Documentos
  4. Criar um Agente com uma Biblioteca de Documentos
  5. Consultar os Documentos
  6. Gerir Bibliotecas
  7. Do Suporte Interno à Análise de Contratos
  8. Preparar Fontes, Isolar Bibliotecas
  9. Pontos-chave

Lição atualizada em 3 de novembro de 2026 com base no SDK mistralai 3.7.0: os documentos da biblioteca são geridos através de client.beta.libraries.documents (upload, list, delete). Os métodos add_document, list_documents e remove_document da 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