Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Strumento document_library: QnA sui tuoi file

Lezione 11 di 18 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. RAG integrato di Mistral
  2. Creare una libreria di documenti
  3. Caricare i documenti
  4. Creare un agente con una libreria di documenti
  5. Interrogare i documenti
  6. Gestire le librerie
  7. Dal supporto interno all’analisi contrattuale
  8. Preparare le fonti, isolare le librerie
  9. Punti chiave

Lezione aggiornata il 3 novembre 2026 basata sull’SDK mistralai 3.7.0: i documenti della libreria sono gestiti tramite client.beta.libraries.documents (upload, list, delete). I metodi add_document, list_documents e remove_document della 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