Инструмент document_library: Въпроси и отговори върху вашите файлове
На тази страница
Урокът е актуализиран на 3 ноември 2026 г. въз основа на
mistralaiSDK 3.7.0: документите в библиотеката се управляват чрезclient.beta.libraries.documents(upload,list,delete). Методитеadd_document,list_documentsиremove_documentот предишната версия вече не съществуват, а качванията отиват директно в библиотеката. Източник: client-python.
Вградено RAG на Mistral
Инструментът document_library е система за генериране, подпомогнато от извличане (RAG), вградена директно в Agents API. Вашият агент получава достъп до документи, които сте качили в облака на Mistral, извлича съответните пасажи и формулира отговора си с цитати. Разликата спрямо собствено разработено RAG решение е значителна: не е необходимо да хоствате векторна база данни, да поддържате конвейер за вграждане (embedding pipeline) или да настройвате стратегия за разделяне на текст (chunking). Просто качвате файлове, декларирате инструмента при създаването на агента и оставяте модела да реши кога да прави заявки към библиотеката.
Създаване на библиотека с документи
Библиотеката е контейнерът, който съдържа вашите документи. Създавате я с едно единствено API обаждане, преди да качите каквито и да е файлове.
from mistralai.client import Mistral
import os
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# Create a library
library = client.beta.libraries.create(
name="Technical Documentation",
description="Product manuals and technical specifications."
)
print(f"Library ID: {library.id}")
Запишете върнатия идентификатор (ID): това е стойността, която предавате на агента. Няма пряк път чрез използване на името на библиотеката. Ако екипът ви управлява отделни библиотеки за човешки ресурси, правни въпроси и техническа документация, съхранявайте тези идентификатори във вашата конфигурация точно както бихте съхранявали низове за връзка.
Качване на документи
Качването се извършва на две стъпки: първо файлът се депозира в пространството Files с изрично указан purpose, след което се прикрепя към библиотеката.
# Upload a PDF directly to the library
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}")
Поддържаните формати включват PDF, обикновен текст и други често срещани типове документи.
Създаване на агент с библиотека с документи
agent = client.beta.agents.create(
model="mistral-medium-latest",
name="Documentation Agent",
instructions="""You are a documentation assistant.
- Answer only using documents from the library
- Cite relevant passages
- If the information is not in the documents, state this clearly""",
tools=[{
"type": "document_library",
"library_ids": [library.id]
}]
)
Параметърът library_ids е списък: можете да свържете няколко библиотеки с един единствен агент. Например, асистент за поддръжка може да използва едновременно продуктова документация и вътрешни процедури. Тук инструкциите са повече от просто желателни. Без директивата да ограничава отговорите само до документите, моделът ще попълва пропуските със своите общи знания и вие ще загубите способността да разграничавате какво идва от вашите файлове и какво идва от другаде. Третият ред – изричното посочване кога липсва информация – е това, което превръща бъбривия агент в надежден.
Заявки към документите
response = client.beta.conversations.start(
agent_id=agent.id,
inputs="How does the Pixtral 12B vision encoder work?"
)
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" [Source] {chunk.title}")
Подобно на уеб търсенето, отговорът пристига на части от два типа. Частите text съдържат написания отговор; частите tool_reference съдържат произхода, като полето title съдържа името на изходния документ, а полето url предоставя вътрешната препратка в рамките на този документ. Това разделяне ви позволява да покажете отговора и точно под него – списъка с документите, които са го генерирали.
Тази проследимост не е просто декоративна. Консултант, отговарящ на клиент въз основа на вътрешна процедура, трябва да може да посочи коя процедура цитира; адвокат, разчитащ на договор, трябва да може да проследи източника до самия договор. Без цитати една RAG система произвежда непроверими твърдения.
Управление на библиотеките
# List libraries
libraries = client.beta.libraries.list()
for lib in libraries.data:
print(f"{lib.name} ({lib.id})")
# List documents in a library
documents = client.beta.libraries.documents.list(library_id=library.id)
for doc in documents.data:
print(f"{doc.name} — {doc.size} bytes")
# Delete a document from the library
client.beta.libraries.documents.delete(
library_id=library.id,
document_id=document.id
)
# Delete the library
client.beta.libraries.delete(library_id=library.id)
Премахването на документи е най-често пренебрегваната операция и най-скъпата, когато бъде забравена. Остаряла версия на ценова листа или процедура остава достъпна за цитиране от агента за неопределено време, носейки цялата видимост на легитимност, тъй като идва от източник. Превърнете премахването на документ в рефлекс всеки път, когато публикувате нова версия.
От вътрешна поддръжка до анализ на договори
Вътрешната поддръжка е най-непосредственият случай на употреба: служителите задават въпроси към човешките ресурси на естествен език, вместо да ровят из интранет мрежата.
agent = client.beta.agents.create(
model="mistral-large-latest",
name="Internal Support",
instructions="Answer employee questions using the HR documentation base.",
tools=[{"type": "document_library", "library_ids": [rh_library.id]}]
)
Анализът на договори променя парадигмата: агентът не просто извлича, той изследва. Тук инструкциите описват задача, а не просто обхват.
agent = client.beta.agents.create(
model="mistral-large-latest",
name="Contract Analyst",
instructions="""Analyze uploaded contracts.
- Identify important clauses
- Flag potential risks
- Compare against industry standards""",
tools=[{"type": "document_library", "library_ids": [contrats_library.id]}]
)
Накрая, базата знания за продукти илюстрира комбинацията от инструменти: официалната документация има предимство, а уеб търсенето попълва пропуските, когато документите не покриват даден въпрос.
agent = client.beta.agents.create(
model="mistral-large-latest",
name="Product Expert",
instructions="Answer technical questions about our products based on official documentation.",
tools=[
{"type": "document_library", "library_ids": [docs_library.id]},
{"type": "web_search"} # Fallback if docs are insufficient
]
)
Подгответе източниците, изолирайте библиотеките
Качеството на RAG се определя, преди дори да извикате API. Структуриран PDF файл с ясни заглавия, подзаглавия и отделни абзаци се разделя и извлича много по-добре от сканирано изображение или документ, в който цялата логика се съдържа в оформлението. След това разделете библиотеките си по домейни, вместо да създавате един общ контейнер за всичко. Агент, свързан само с правната библиотека, няма да рискува да цитира меморандум от човешки ресурси, за да отговори на въпрос относно договор. Тези две решения – подобряване на структурата на източниците и изолиране на библиотеките – оказват влияние върху крайния резултат повече от всяка настройка на модела.
Ключови изводи
document_libraryе вградено RAG – няма нужда да управлявате собствена векторна инфраструктура- Създавайте тематични библиотеки и качвайте документи чрез Files API
- Отговорите цитират съответните пасажи, използвайки части
tool_reference - Можете да свържете няколко библиотеки с един единствен агент
- Комбинирайте с други инструменти за цялостно покритие