Instrumentul document_library: Întrebări și răspunsuri pe baza fișierelor dumneavoastră
Pe această pagină
Lecție actualizată la 3 noiembrie 2026 pe baza SDK
mistralai3.7.0: documentele din bibliotecă sunt gestionate princlient.beta.libraries.documents(upload,list,delete). Metodeleadd_document,list_documentsșiremove_documentdin versiunea anterioară nu mai există, iar încărcările se fac direct în bibliotecă. Sursă: client-python.
RAG integrat în Mistral
Instrumentul document_library este un sistem de Generare Augmentată prin Recuperare (RAG) integrat direct în API-ul Agents. Agentul dumneavoastră accesează documentele încărcate în cloud-ul Mistral, recuperează pasajele relevante și formulează răspunsul cu citări. Diferența față de o soluție RAG dezvoltată intern este semnificativă: nu trebuie să găzduiți o bază de date vectoriale, să mențineți un pipeline de embedding sau să ajustați o strategie de fragmentare. Pur și simplu încărcați fișierele, declarați instrumentul la crearea agentului și lăsați modelul să decidă când să interogheze biblioteca.
Crearea unei biblioteci de documente
O bibliotecă este containerul care stochează documentele dumneavoastră. O creați printr-un singur apel API înainte de a încărca orice fișier.
from mistralai.client import Mistral
import os
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# Crearea unei biblioteci
library = client.beta.libraries.create(
name="Documentație Tehnică",
description="Manuale de produs și specificații tehnice."
)
print(f"ID Bibliotecă: {library.id}")
Notați ID-ul returnat: acesta este ceea ce transmiteți agentului. Nu există o scurtătură folosind numele bibliotecii. Dacă echipa dumneavoastră gestionează biblioteci separate pentru HR, juridic și tehnic, stocați aceste ID-uri în configurație, exact ca și șirurile de conexiune.
Încărcarea documentelor
Încărcarea se desfășoară în doi pași: mai întâi, fișierul este depus în spațiul Files cu un purpose explicit, apoi este atașat la bibliotecă.
# Încărcarea unui PDF direct în bibliotecă
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"Document {document.id}: {document.processing_status}")
Formatele suportate includ PDF, text simplu și alte tipuri comune de documente.
Crearea unui agent cu o bibliotecă de documente
agent = client.beta.agents.create(
model="mistral-medium-latest",
name="Agent Documentație",
instructions="""Ești un asistent pentru documentație.
- Răspunde doar folosind documentele din bibliotecă
- Citează pasajele relevante
- Dacă informația nu se află în documente, menționează acest lucru clar""",
tools=[{
"type": "document_library",
"library_ids": [library.id]
}]
)
Parametrul library_ids este o listă: puteți asocia mai multe biblioteci unui singur agent. De exemplu, un asistent de suport ar putea folosi atât documentația de produs, cât și procedurile interne. Aici, instrucțiunile sunt mai mult decât utile. Fără directiva de a limita răspunsurile la documente, modelul completează golurile cu cunoștințele sale generale, iar dumneavoastră pierdeți capacitatea de a distinge ceea ce provine din fișierele dumneavoastră de ceea ce vine din altă parte. A treia linie—care stipulează explicit când lipsesc informațiile—este cea care transformă un agent vorbăreț într-unul de încredere.
Interogarea documentelor
response = client.beta.conversations.start(
agent_id=agent.id,
inputs="Cum funcționează encoderul vizual 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" [Sursă] {chunk.title}")
La fel ca în cazul căutării pe web, răspunsul sosește în fragmente de două tipuri. Fragmentele text conțin răspunsul scris; fragmentele tool_reference conțin proveniența, câmpul title deținând numele documentului sursă, iar câmpul url oferind referința internă din acel document. Această separare vă permite să afișați răspunsul și, chiar sub el, lista documentelor care l-au generat.
Această trasabilitate nu este doar decorativă. Un consultant care răspunde unui client pe baza unei proceduri interne trebuie să poată specifica exact procedura citată; un avocat care se bazează pe un contract trebuie să poată face legătura cu acel contract. Fără citări, un sistem RAG produce afirmații neverificabile.
Gestionarea bibliotecilor
# Listarea bibliotecilor
libraries = client.beta.libraries.list()
for lib in libraries.data:
print(f"{lib.name} ({lib.id})")
# Listarea documentelor dintr-o bibliotecă
documents = client.beta.libraries.documents.list(library_id=library.id)
for doc in documents.data:
print(f"{doc.name} — {doc.size} bytes")
# Ștergerea unui document din bibliotecă
client.beta.libraries.documents.delete(
library_id=library.id,
document_id=document.id
)
# Ștergerea bibliotecii
client.beta.libraries.delete(library_id=library.id)
Eliminarea documentelor este operațiunea cel mai adesea neglijată și cea mai costisitoare atunci când este uitată. O versiune învechită a unei liste de prețuri sau a unei proceduri rămâne citabilă de agent la infinit, purtând toate aparențele legitimității deoarece este sourstată. Faceți din eliminarea unui document un reflex ori de câte ori publicați o nouă versiune.
De la suport intern la analiza contractelor
Suportul intern este cazul de utilizare cel mai imediat: angajații pun întrebări HR în limbaj natural în loc să caute prin intranet.
agent = client.beta.agents.create(
model="mistral-large-latest",
name="Suport Intern",
instructions="Răspunde la întrebările angajaților folosind baza de documentație HR.",
tools=[{"type": "document_library", "library_ids": [rh_library.id]}]
)
Analiza contractelor schimbă paradigma: agentul nu doar recuperează, ci examinează. Aici, instrucțiunile descriu o sarcină, nu doar un domeniu de aplicare.
agent = client.beta.agents.create(
model="mistral-large-latest",
name="Analist Contracte",
instructions="""Analizează contractele încărcate.
- Identifică clauzele importante
- Semnalează riscurile potențiale
- Compară cu standardele din industrie""",
tools=[{"type": "document_library", "library_ids": [contrats_library.id]}]
)
În final, o bază de cunoștințe despre produs ilustrează combinarea instrumentelor: documentația oficială are prioritate, iar căutarea pe web completează golurile atunci când documentele nu acoperă o întrebare.
agent = client.beta.agents.create(
model="mistral-large-latest",
name="Expert Produs",
instructions="Răspunde la întrebările tehnice despre produsele noastre pe baza documentației oficiale.",
tools=[
{"type": "document_library", "library_ids": [docs_library.id]},
{"type": "web_search"} # Soluție de rezervă dacă documentația este insuficientă
]
)
Pregătirea surselor și izolarea bibliotecilor
Calitatea RAG este determinată înainte chiar de a apela API-ul. Un PDF structurat, cu titluri clare, subtitluri și paragrafe distincte, se fragmentează și se recuperează mult mai bine decât o scanare aplatizată sau un document în care toată logica rezidă în aspectul vizual. În continuare, separați bibliotecile pe domenii în loc să creați o singură găleată universală. Un agent conectat doar la biblioteca juridică nu riscă să citeze o notă de serviciu HR pentru a răspunde la o întrebare despre contracte. Aceste două decizii—perfecționarea structurii sursei și izolarea bibliotecilor—au un impact asupra rezultatului final mai mare decât orice ajustare a modelului.
Puncte cheie
document_libraryeste un RAG integrat—nu este nevoie să vă gestionați propria infrastructură vectorială- Creați biblioteci tematice și încărcați documente prin API-ul Files
- Răspunsurile citează pasajele relevante folosind fragmente
tool_reference - Puteți asocia mai multe biblioteci unui singur agent
- Combinați cu alte instrumente pentru o acoperire completă