Kurs Python · Moduł 11: RAG i systemy wieloagentowe
LlamaIndex - Framework RAG
W tej lekcji8
W trzech poprzednich lekcjach sami pisaliśmy chunking, embeddingi, wyszukiwanie i sklejanie promptu. To dobra szkoła tropienia, ale w prawdziwej wyprawie nikt nie szyje sobie namiotu przed wyjazdem. Bierzesz sprawdzony ekwipunek i skupiasz się na trasie.
LlamaIndex to framework do budowania aplikacji RAG. Upraszcza cały proces - od ładowania dokumentów po generowanie odpowiedzi - i daje gotowe klocki na każdy krok, który dotąd pisaliśmy ręcznie.
Podstawy LlamaIndex
Cały pipeline z pierwszej lekcji mieści się w kilku linijkach. Obiekt Settings ustawia globalnie model językowy i model embeddingów, a SimpleDirectoryReader wczytuje wszystkie pliki z katalogu:
from llama_index.core import VectorStoreIndex, SimpleDirectoryReader, Settings
from llama_index.llms.openai import OpenAI
from llama_index.embeddings.openai import OpenAIEmbedding
# Konfiguracja globalna
Settings.llm = OpenAI(model="gpt-4o-mini", temperature=0)
Settings.embed_model = OpenAIEmbedding(model="text-embedding-3-small")
# Ładowanie dokumentów
documents = SimpleDirectoryReader("./docs").load_data()
print(f"Załadowano {len(documents)} dokumentów")
# Tworzenie indeksu
index = VectorStoreIndex.from_documents(documents)
# Query engine
query_engine = index.as_query_engine()
# Zapytanie
response = query_engine.query("Co to jest RAG?")
print(response)Łańcuch jest zawsze ten sam: SimpleDirectoryReader i .load_data() ładują dokumenty, VectorStoreIndex.from_documents dzieli je na fragmenty, liczy embeddingi i buduje indeks, a .as_query_engine() zamienia indeks w silnik pytań. Pod spodem dzieje się dokładnie to, co pisaliśmy sami: retrieve, augment, generate. Zmienił się tylko poziom, na którym pracujesz.
Document Loaders
Dokumenty rzadko leżą w jednym formacie. LlamaIndex ma loadery do tekstu, plików i stron internetowych:
from llama_index.core import Document
from llama_index.readers.web import SimpleWebPageReader
from llama_index.readers.file import PDFReader, DocxReader
# Z tekstu
doc = Document(text="To jest przykładowy tekst do zaindeksowania.")
# Z plików
pdf_reader = PDFReader()
pdf_docs = pdf_reader.load_data(file="document.pdf")
# Ze strony web
web_reader = SimpleWebPageReader()
web_docs = web_reader.load_data(urls=["https://example.com"])
# Z wielu źródeł
from llama_index.core import SimpleDirectoryReader
reader = SimpleDirectoryReader(
input_dir="./data",
recursive=True,
required_exts=[".pdf", ".docx", ".txt", ".md"]
)
documents = reader.load_data()Document to podstawowa jednostka danych: tekst plus metadane. PDFReader i SimpleWebPageReader pochodzą z osobnych pakietów (llama-index-readers-file, llama-index-readers-web), więc trzeba je doinstalować. SimpleDirectoryReader z recursive=True przejdzie też podkatalogi i weźmie tylko rozszerzenia z listy required_exts.
Node Parsing (Chunking)
W LlamaIndex fragment dokumentu nazywa się node. Strategie podziału możesz ułożyć od najprostszej do najbardziej zaawansowanej: cięcie po znakach, jak nasz simple_chunker z pierwszej lekcji, podział po zdaniach, podział semantyczny i parser hierarchiczny. Zaczynamy od zdań:
from llama_index.core.node_parser import (
SentenceSplitter,
SemanticSplitterNodeParser,
)
# Prosty podział po zdaniach
sentence_parser = SentenceSplitter(
chunk_size=512,
chunk_overlap=50
)
nodes = sentence_parser.get_nodes_from_documents(documents)SentenceSplitter tnie tekst na fragmenty do 512 tokenów, starając się nie rozrywać zdań, a chunk_overlap to znana już zakładka.
Podział semantyczny idzie dalej: porównuje embeddingi sąsiednich zdań i tnie tam, gdzie znaczenie wyraźnie się zmienia:
# Semantyczny podział
semantic_parser = SemanticSplitterNodeParser(
buffer_size=1,
breakpoint_percentile_threshold=95,
embed_model=Settings.embed_model
)
semantic_nodes = semantic_parser.get_nodes_from_documents(documents)breakpoint_percentile_threshold=95 oznacza, że cięcie następuje tylko przy 5% największych skoków znaczenia. To droższe, bo wymaga embeddingu każdego zdania.
Parser hierarchiczny tworzy kilka poziomów fragmentów naraz, od dużych do małych:
# Hierarchiczny podział
from llama_index.core.node_parser import HierarchicalNodeParser
hierarchical_parser = HierarchicalNodeParser.from_defaults(
chunk_sizes=[2048, 512, 128]
)
hierarchical_nodes = hierarchical_parser.get_nodes_from_documents(documents)Małe fragmenty (128 tokenów) dobrze trafiają w wyszukiwaniu, a duże (2048) dają modelowi szerszy kontekst. Dokumenty wejściowe się nie zmieniają, zmienia się tylko sposób ich pocięcia.
Retriever Modes
Retriever to zwiadowca, który przynosi pasujące fragmenty. Możesz go skonfigurować ręcznie i dodać postprocessing:
from llama_index.core.retrievers import VectorIndexRetriever
from llama_index.core.query_engine import RetrieverQueryEngine
from llama_index.core.postprocessor import SimilarityPostprocessor
# Podstawowy retriever
retriever = VectorIndexRetriever(
index=index,
similarity_top_k=5
)
# Z postprocessingiem
query_engine = RetrieverQueryEngine(
retriever=retriever,
node_postprocessors=[
SimilarityPostprocessor(similarity_cutoff=0.7)
]
)similarity_top_k=5 pobiera pięć fragmentów, a SimilarityPostprocessor odrzuca te z podobieństwem poniżej 0.7, żeby słabe trafienia nie zaśmiecały promptu.
Hybrid search z poprzedniej lekcji też jest tu gotowy. Uwaga: w aktualnych wersjach BM25Retriever mieszka w osobnym pakiecie llama-index-retrievers-bm25, a nie w llama_index.core:
# Hybrid retriever
from llama_index.retrievers.bm25 import BM25Retriever # pip install llama-index-retrievers-bm25
from llama_index.core.retrievers import QueryFusionRetriever
vector_retriever = index.as_retriever(similarity_top_k=5)
bm25_retriever = BM25Retriever.from_defaults(nodes=nodes, similarity_top_k=5)
hybrid_retriever = QueryFusionRetriever(
retrievers=[vector_retriever, bm25_retriever],
similarity_top_k=5,
num_queries=1,
)QueryFusionRetriever łączy wyniki obu zwiadowców w jedną listę. num_queries=1 oznacza, że używamy tylko oryginalnego pytania, bez dodatkowych wariantów generowanych przez LLM.
Query Transformations
Czasem problem leży w samym pytaniu. Pytanie złożone warto rozbić na mniejsze, a krótkie pytanie przerobić tak, żeby lepiej pasowało do dokumentów:
from llama_index.core.query_engine import SubQuestionQueryEngine
from llama_index.core.tools import QueryEngineTool
# Sub-question engine - rozbija pytania na mniejsze
tools = [
QueryEngineTool.from_defaults(
query_engine=index.as_query_engine(),
name="dokumentacja",
description="Zawiera dokumentację projektu"
)
]
sub_question_engine = SubQuestionQueryEngine.from_defaults(
query_engine_tools=tools
)
# HyDE - Hypothetical Document Embeddings
from llama_index.core.indices.query.query_transform import HyDEQueryTransform
from llama_index.core.query_engine import TransformQueryEngine
hyde = HyDEQueryTransform(include_original=True)
hyde_query_engine = TransformQueryEngine(
index.as_query_engine(),
query_transform=hyde
)SubQuestionQueryEngine rozbija pytanie na podpytania i każde kieruje do odpowiedniego narzędzia, tu jednego o nazwie "dokumentacja". HyDE najpierw każe modelowi napisać hipotetyczną odpowiedź i szuka dokumentów podobnych do niej, bo odpowiedź bywa bliższa dokumentom niż samo pytanie. include_original=True zachowuje też oryginalne pytanie.
Chat Engine
Query engine nie pamięta poprzednich pytań. Do rozmowy służy chat engine z pamięcią:
from llama_index.core.chat_engine import CondenseQuestionChatEngine
from llama_index.core.memory import ChatMemoryBuffer
# Pamięć czatu
memory = ChatMemoryBuffer.from_defaults(token_limit=3000)
# Chat engine z historią
chat_engine = index.as_chat_engine(
chat_mode="condense_question",
memory=memory,
verbose=True
)
# Konwersacja
response1 = chat_engine.chat("Co to jest Python?")
print(response1)
response2 = chat_engine.chat("Jakie ma zastosowania?")
print(response2)
# Reset pamięci
chat_engine.reset()Tryb condense_question przepisuje pytanie uzupełniające, takie jak "Jakie ma zastosowania?", na samodzielne pytanie z użyciem historii, a dopiero potem przeszukuje indeks. reset() czyści pamięć. W najnowszych wersjach ChatMemoryBuffer jest oznaczony jako deprecated na rzecz klasy Memory z tego samego modułu, ale działa dalej.
Integracja z Vector Databases
Domyślnie indeks żyje w pamięci. Żeby przetrwał restart, podłączamy bazę wektorową z poprzedniej lekcji. Tak wygląda Chroma:
# Chroma
from llama_index.vector_stores.chroma import ChromaVectorStore
import chromadb
chroma_client = chromadb.PersistentClient(path="./chroma_db")
chroma_collection = chroma_client.get_or_create_collection("llama_index")
vector_store = ChromaVectorStore(chroma_collection=chroma_collection)
index = VectorStoreIndex.from_vector_store(vector_store)from_vector_store otwiera indeks nad kolekcją, która już ma dane. Żeby zapisać do niej nowe dokumenty, przekaż vector_store przez StorageContext do from_documents.
Qdrant i Pinecone podłącza się identycznie, zmienia się tylko klasa magazynu:
# Qdrant
from llama_index.vector_stores.qdrant import QdrantVectorStore
from qdrant_client import QdrantClient
qdrant_client = QdrantClient(host="localhost", port=6333)
vector_store = QdrantVectorStore(
client=qdrant_client,
collection_name="llama_index"
)
# Pinecone
from llama_index.vector_stores.pinecone import PineconeVectorStore
from pinecone import Pinecone
pc = Pinecone(api_key="...")
pinecone_index = pc.Index("llama-index")
vector_store = PineconeVectorStore(pinecone_index=pinecone_index)Reszta kodu, czyli query engine, retrievery i chat engine, zostaje bez zmian, i to jest największa zaleta tej warstwy abstrakcji.
Ewaluacja
Na koniec sprawdzamy, czy odpowiedzi są wiarygodne. LlamaIndex ma evaluatory, które używają modelu językowego jako sędziego:
from llama_index.core.evaluation import (
FaithfulnessEvaluator,
RelevancyEvaluator,
CorrectnessEvaluator
)
# Evaluatory
faithfulness = FaithfulnessEvaluator()
relevancy = RelevancyEvaluator()
# Ewaluacja odpowiedzi
query = "Co to jest RAG?"
response = query_engine.query(query)
faithfulness_result = faithfulness.evaluate_response(response=response)
print(f"Faithfulness: {faithfulness_result.passing}")
relevancy_result = relevancy.evaluate_response(query=query, response=response)
print(f"Relevancy: {relevancy_result.passing}")FaithfulnessEvaluator sprawdza, czy odpowiedź wynika z pobranego kontekstu, czyli łapie halucynacje. RelevancyEvaluator sprawdza, czy odpowiedź i kontekst pasują do pytania. Pole passing przyjmuje wartość True albo False.
Polecam zaczynać od SentenceSplitter i prostego query engine, a po HyDE czy hybrid search sięgać dopiero wtedy, gdy ewaluacja pokaże konkretny problem.
LlamaIndex to kompletny framework do RAG. W następnej lekcji poznasz systemy multi-agentowe - gdy jeden agent to za mało!
Zapamiętaj: LlamaIndex to gotowy ekwipunek wyprawy, dzięki któremu skupiasz się na trasie, a nie na szyciu namiotu.
Hasła z dokumentacji w tej lekcji
Widzisz błąd w tej lekcji?
Sprawdź się
Odpowiedz na pytania z tej lekcji. Wybierz odpowiedź, a od razu zobaczysz, czy jest poprawna.
1. Do czego służy LlamaIndex?
2. Która klasa LlamaIndex służy do ładowania dokumentów z katalogu?
Zadania praktyczne w grze
- Edytor kodu
Zaimplementuj podstawowy system Q&A z LlamaIndex
- Układanie w poziomie
Ułóż podstawowy pipeline LlamaIndex:
- Układanie w pionie
Posortuj strategie chunkingu od najprostszej do najbardziej zaawansowanej: