Strumento document_library: QnA sui tuoi file
In questa pagina
Lezione aggiornata il 3 novembre 2026 basata sull’SDK
mistralai3.7.0: i documenti della libreria sono gestiti tramiteclient.beta.libraries.documents(upload,list,delete). I metodiadd_document,list_documentseremove_documentdella versione precedente non esistono più e i caricamenti avvengono ora direttamente nella libreria. Fonte: client-python.
RAG integrato di Mistral
Lo strumento document_library è un sistema di Generazione Aumentata dal Recupero (RAG) integrato direttamente nelle API degli Agenti. Il tuo agente accede ai documenti che hai caricato sul cloud Mistral, recupera i passaggi pertinenti e formula la sua risposta con le citazioni. La differenza rispetto a una soluzione RAG sviluppata internamente è significativa: non devi ospitare un database vettoriale, mantenere una pipeline di embedding o ottimizzare una strategia di frammentazione. Ti limiti a caricare i file, dichiari lo strumento durante la creazione dell’agente e lasci che il modello decida quando interrogare la libreria.
Creare una libreria di documenti
Una libreria è il contenitore che ospita i tuoi documenti. La crei con una singola chiamata API prima di caricare qualsiasi file.
from mistralai.client import Mistral
import os
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# Creare una libreria
library = client.beta.libraries.create(
name="Documentazione Tecnica",
description="Manuali di prodotto e specifiche tecniche."
)
print(f"ID Libreria: {library.id}")
Prendi nota dell’ID restituito: è ciò che passerai all’agente. Non esiste alcuna scorciatoia utilizzando il nome della libreria. Se il tuo team gestisce librerie separate per le risorse umane, gli aspetti legali e la tecnica, archivia questi ID nella tua configurazione proprio come faresti con le stringhe di connessione.
Caricare i documenti
Il caricamento avviene in due fasi: prima, il file viene depositato nello spazio Files con uno purpose esplicito, poi viene allegato alla libreria.
# Caricare un PDF direttamente nella libreria
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}")
I formati supportati includono PDF, testo semplice e altri tipi di documenti comuni.
Creare un agente con una libreria di documenti
agent = client.beta.agents.create(
model="mistral-medium-latest",
name="Agente Documentazione",
instructions="""Sei un assistente alla documentazione.
- Rispondi utilizzando solo i documenti della libreria
- Cita i passaggi pertinenti
- Se l'informazione non è nei documenti, dichiaralo chiaramente""",
tools=[{
"type": "document_library",
"library_ids": [library.id]
}]
)
Il parametro library_ids è una lista: puoi associare più librerie a un singolo agente. Ad esempio, un assistente per il supporto potrebbe utilizzare sia la documentazione di prodotto che le procedure interne. Qui, le istruzioni sono più che un semplice optional. Senza la direttiva di limitare le risposte ai documenti, il modello colma le lacune con le sue conoscenze generali e perdi la capacità di distinguere ciò che proviene dai tuoi file da ciò che proviene altrove. La terza riga—dichiarare esplicitamente quando un’informazione manca—è ciò che trasforma un agente loquace in uno affidabile.
Interrogare i documenti
response = client.beta.conversations.start(
agent_id=agent.id,
inputs="Come funziona l'encoder visivo 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}")
Come per la ricerca web, la risposta arriva in chunk di due tipi. I chunk text contengono la risposta scritta; i chunk tool_reference contengono la provenienza, con il campo title che riporta il nome del documento sorgente e il campo url che fornisce il riferimento interno all’interno di quel documento. Questa separazione ti permette di visualizzare la risposta e, subito sotto, l’elenco dei documenti che l’hanno generata.
Questa tracciabilità non è solo estetica. Un consulente che risponde a un cliente basandosi su una procedura interna deve essere in grado di specificare quale procedura sta citando; un avvocato che si basa su un contratto deve poter risalire a quel contratto. Senza citazioni, un sistema RAG produce affermazioni non verificabili.
Gestire le librerie
# Elencare le librerie
libraries = client.beta.libraries.list()
for lib in libraries.data:
print(f"{lib.name} ({lib.id})")
# Elencare i documenti in una libreria
documents = client.beta.libraries.documents.list(library_id=library.id)
for doc in documents.data:
print(f"{doc.name} — {doc.size} byte")
# Eliminare un documento dalla libreria
client.beta.libraries.documents.delete(
library_id=library.id,
document_id=document.id
)
# Eliminare la libreria
client.beta.libraries.delete(library_id=library.id)
La rimozione dei documenti è l’operazione più spesso trascurata e la più costosa se dimenticata. Una versione obsoleta di un listino prezzi o di una procedura rimane citabile dall’agente indefinitamente, portando con sé tutta l’apparenza di legittimità perché proviene da una fonte. Fai della rimozione di un documento un riflesso automatico ogni volta che pubblichi una nuova versione.
Dal supporto interno all’analisi contrattuale
Il supporto interno è il caso d’uso più immediato: i dipendenti pongono domande alle risorse umane in linguaggio naturale invece di scavare nell’intranet.
agent = client.beta.agents.create(
model="mistral-large-latest",
name="Supporto Interno",
instructions="Rispondi alle domande dei dipendenti utilizzando la base documentale delle Risorse Umane.",
tools=[{"type": "document_library", "library_ids": [rh_library.id]}]
)
L’analisi contrattuale sposta il paradigma: l’agente non si limita a recuperare, ma esamina. Qui, le istruzioni descrivono un compito, non solo un ambito.
agent = client.beta.agents.create(
model="mistral-large-latest",
name="Analista Contratti",
instructions="""Analizza i contratti caricati.
- Identifica le clausole importanti
- Segnala i potenziali rischi
- Confronta con gli standard del settore""",
tools=[{"type": "document_library", "library_ids": [contrats_library.id]}]
)
Infine, una base di conoscenza di prodotto illustra la combinazione di strumenti: la documentazione ufficiale ha la precedenza e la ricerca web colma le lacune quando i documenti non coprono una domanda.
agent = client.beta.agents.create(
model="mistral-large-latest",
name="Esperto di Prodotto",
instructions="Rispondi alle domande tecniche sui nostri prodotti basandoti sulla documentazione ufficiale.",
tools=[
{"type": "document_library", "library_ids": [docs_library.id]},
{"type": "web_search"} # Fallback se i documenti sono insufficienti
]
)
Preparare le fonti, isolare le librerie
La qualità del RAG è determinata prima ancora di chiamare l’API. Un PDF strutturato con titoli chiari, sottotitoli e paragrafi distinti viene frammentato e recuperato molto meglio di una scansione appiattita o di un documento in cui tutta la logica risiede nel layout. Successivamente, separa le tue librerie per dominio invece di creare un unico contenitore generico. Un agente connesso solo alla libreria legale non rischierà di citare una nota delle risorse umane per rispondere a una domanda su un contratto. Queste due decisioni—affinare la struttura delle fonti e isolare le librerie—hanno un impatto sul risultato finale maggiore di qualsiasi ottimizzazione del modello.
Punti chiave
document_libraryè un RAG integrato: non serve gestire la propria infrastruttura vettoriale- Crea librerie tematiche e carica i documenti tramite le API Files
- Le risposte citano i passaggi pertinenti utilizzando i chunk
tool_reference - Puoi associare più librerie a un singolo agente
- Combina con altri strumenti per una copertura completa