Narzędzie document_library: Odpowiedzi na pytania dotyczące Twoich plików
Na tej stronie
Lekcja zaktualizowana 3 listopada 2026 w oparciu o SDK
mistralaiw wersji 3.7.0: dokumenty w bibliotekach są zarządzane poprzezclient.beta.libraries.documents(upload,list,delete). Metodyadd_document,list_documentsiremove_documentz poprzedniej wersji już nie istnieją, a przesyłanie plików odbywa się teraz bezpośrednio do biblioteki. Źródło: client-python.
Wbudowany system RAG firmy Mistral
Narzędzie document_library to system Retrieval-Augmented Generation (RAG) wbudowany bezpośrednio w Agents API. Twój agent uzyskuje dostęp do dokumentów, które przesłałeś do chmury Mistral, pobiera odpowiednie fragmenty i formułuje odpowiedź wraz z cytowaniami. Różnica w porównaniu do autorskiego rozwiązania RAG jest znacząca: nie musisz hostować bazy danych wektorowych, utrzymywać potoku tworzenia osadzeń (embedding pipeline) ani dostrajać strategii dzielenia na fragmenty. Po prostu przesyłasz pliki, deklarujesz narzędzie podczas tworzenia agenta i pozwalasz modelowi decydować, kiedy odpytać bibliotekę.
Tworzenie biblioteki dokumentów
Biblioteka to kontener przechowujący Twoje dokumenty. Tworzysz ją jednym wywołaniem API przed przesłaniem jakichkolwiek plików.
from mistralai.client import Mistral
import os
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# Utwórz bibliotekę
library = client.beta.libraries.create(
name="Dokumentacja techniczna",
description="Instrukcje obsługi produktów i specyfikacje techniczne."
)
print(f"ID biblioteki: {library.id}")
Zanotuj zwrócone ID: to właśnie je przekażesz agentowi. Nie ma skrótu polegającego na użyciu nazwy biblioteki. Jeśli Twój zespół zarządza oddzielnymi bibliotekami dla działu HR, prawnego i technicznego, przechowuj te identyfikatory w konfiguracji tak samo jak ciągi połączeniowe.
Przesyłanie dokumentów
Przesyłanie odbywa się w dwóch krokach: najpierw plik jest umieszczany w przestrzeni Files z jawnie określonym purpose, a następnie dołączany do biblioteki.
# Prześlij plik PDF bezpośrednio do biblioteki
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"Dokument {document.id}: {document.processing_status}")
Obsługiwane formaty obejmują PDF, zwykły tekst i inne popularne typy dokumentów.
Tworzenie agenta z biblioteką dokumentów
agent = client.beta.agents.create(
model="mistral-medium-latest",
name="Agent ds. dokumentacji",
instructions="""Jesteś asystentem ds. dokumentacji.
- Odpowiadaj wyłącznie na podstawie dokumentów z biblioteki
- Cytuj odpowiednie fragmenty
- Jeśli informacje nie znajdują się w dokumentach, wyraźnie to zaznacz""",
tools=[{
"type": "document_library",
"library_ids": [library.id]
}]
)
Parametr library_ids to lista: możesz powiązać wiele bibliotek z jednym agentem. Na przykład asystent wsparcia może korzystać zarówno z dokumentacji produktu, jak i procedur wewnętrznych. W tym przypadku instrukcje są czymś więcej niż miłym dodatkiem. Bez dyrektywy ograniczającej odpowiedzi do dokumentów, model uzupełni luki swoją ogólną wiedzą, a Ty stracisz możliwość rozróżnienia tego, co pochodzi z Twoich plików, od tego, co pochodzi z innych źródeł. Trzeci wiersz – wyraźne stwierdzenie, kiedy brakuje informacji – to właśnie to, co zamienia gadatliwego agenta w niezawodnego.
Odpytywanie dokumentów
response = client.beta.conversations.start(
agent_id=agent.id,
inputs="Jak działa enkoder wizyjny 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" [Źródło] {chunk.title}")
Podobnie jak w przypadku wyszukiwania w sieci, odpowiedź przychodzi w fragmentach dwóch typów. Fragmenty text zawierają odpowiedź tekstową; fragmenty tool_reference zawierają informacje o pochodzeniu, gdzie pole title przechowuje nazwę dokumentu źródłowego, a pole url zapewnia wewnętrzne odniesienie w ramach tego dokumentu. To rozdzielenie pozwala wyświetlić odpowiedź, a tuż pod nią listę dokumentów, które ją wygenerowały.
Ta możliwość śledzenia pochodzenia nie jest tylko ozdobnikiem. Doradca odpowiadający klientowi na podstawie procedury wewnętrznej musi być w stanie wskazać, którą procedurę cytuje; prawnik polegający na umowie musi być w stanie dotrzeć do tej umowy. Bez cytowań system RAG generuje roszczenia, których nie można zweryfikować.
Zarządzanie bibliotekami
# Wylistuj biblioteki
libraries = client.beta.libraries.list()
for lib in libraries.data:
print(f"{lib.name} ({lib.id})")
# Wylistuj dokumenty w bibliotece
documents = client.beta.libraries.documents.list(library_id=library.id)
for doc in documents.data:
print(f"{doc.name} — {doc.size} bajtów")
# Usuń dokument z biblioteki
client.beta.libraries.documents.delete(
library_id=library.id,
document_id=document.id
)
# Usuń bibliotekę
client.beta.libraries.delete(library_id=library.id)
Usuwanie dokumentów to operacja najczęściej pomijana i najbardziej kosztowna, gdy zostanie zapomniana. Nieaktualna wersja cennika lub procedury pozostaje dostępna do cytowania przez agenta w nieskończoność, zachowując wszelkie pozory legitymności, ponieważ pochodzi ze źródła. Spraw, aby usuwanie dokumentu stało się odruchem za każdym razem, gdy publikujesz nową wersję.
Od wsparcia wewnętrznego po analizę umów
Wsparcie wewnętrzne to najbardziej oczywiste zastosowanie: pracownicy zadają pytania do działu HR w języku naturalnym, zamiast przeszukiwać intranet.
agent = client.beta.agents.create(
model="mistral-large-latest",
name="Wsparcie wewnętrzne",
instructions="Odpowiadaj na pytania pracowników, korzystając z bazy dokumentacji HR.",
tools=[{"type": "document_library", "library_ids": [rh_library.id]}]
)
Analiza umów zmienia paradygmat: agent nie tylko pobiera dane, ale je bada. Tutaj instrukcje opisują zadanie, a nie tylko zakres działania.
agent = client.beta.agents.create(
model="mistral-large-latest",
name="Analityk umów",
instructions="""Analizuj przesłane umowy.
- Identyfikuj ważne klauzule
- Sygnalizuj potencjalne ryzyka
- Porównuj ze standardami branżowymi""",
tools=[{"type": "document_library", "library_ids": [contrats_library.id]}]
)
Na koniec, baza wiedzy o produktach ilustruje łączenie narzędzi: oficjalna dokumentacja ma pierwszeństwo, a wyszukiwanie w sieci wypełnia luki, gdy dokumenty nie obejmują danego pytania.
agent = client.beta.agents.create(
model="mistral-large-latest",
name="Ekspert ds. produktów",
instructions="Odpowiadaj na pytania techniczne dotyczące naszych produktów na podstawie oficjalnej dokumentacji.",
tools=[
{"type": "document_library", "library_ids": [docs_library.id]},
{"type": "web_search"} # Zabezpieczenie na wypadek niewystarczającej dokumentacji
]
)
Przygotuj źródła, izoluj biblioteki
Jakość systemu RAG jest determinowana zanim jeszcze wywołasz API. Ustrukturyzowany plik PDF z wyraźnymi nagłówkami, podnagłówkami i odrębnymi akapitami dzieli się na fragmenty i pobiera znacznie lepiej niż spłaszczony skan lub dokument, w którym cała logika tkwi w układzie graficznym. Następnie rozdziel swoje biblioteki według domen, zamiast tworzyć jeden pojemnik na wszystko. Agent połączony tylko z biblioteką prawną nie zaryzykuje zacytowania notatki z działu HR, odpowiadając na pytanie dotyczące umowy. Te dwie decyzje – dopracowanie struktury źródła i izolacja bibliotek – wpływają na końcowy wynik bardziej niż jakiekolwiek dostrajanie modelu.
Kluczowe wnioski
document_libraryto wbudowany system RAG – nie musisz zarządzać własną infrastrukturą wektorową- Twórz tematyczne biblioteki i przesyłaj dokumenty poprzez API Files
- Odpowiedzi cytują odpowiednie fragmenty przy użyciu fragmentów
tool_reference - Możesz powiązać wiele bibliotek z jednym agentem
- Łącz z innymi narzędziami, aby uzyskać kompleksowy zasięg