Kurs Python · Moduł 11: RAG i systemy wieloagentowe

LlamaIndex - Framework RAG

6 min czytania ·
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. 1. Do czego służy LlamaIndex?

  2. 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:

  1. PytanieLlamaIndex
  2. PytanieDocument Loader
  3. Zadanie z kodemLlamaIndex Query Engine
  4. Ułóż w kolejnościLlamaIndex pipeline
  5. Ułóż w kolejnościChunking strategies

Przydatne artykuły