Jak używać LlamaIndex: Praktyczny przewodnik od zera do produkcji
Jeśli kiedykolwiek próbowałeś zbudować aplikację generowania rozszerzonego o wyszukiwanie (RAG) i pomyślałeś: „Dlaczego łączenie embeddingów, wektorowych baz danych i promptów jest takie skomplikowane?”, nie jesteś sam. LlamaIndex powstał, aby ten proces był szybki, logiczny i gotowy do produkcji. W tym praktycznym, zorientowanym na rozwiązania przewodniku, przejdziemy krok po kroku przez sposób użycia LlamaIndex – od pozyskiwania danych, indeksowania, zapytań, ewaluacji po wdrażanie – abyś mógł dostarczyć coś niezawodnego, nie gubiąc się w kodzie łączącym.
Użyjemy struktury opartej na pytaniach z progresywnymi krokami, uruchamialnymi fragmentami kodu i wskazówkami z życia wziętymi. Niezależnie od tego, czy prototypujesz chatbota dla dokumentacji wewnętrznej, czy wdrażasz asystenta wiedzy dla klientów, efektywne nauczenie się korzystania z LlamaIndex zaoszczędzi Ci wiele dni.
: LlamaIndex to framework, który pomaga łączyć dane z dużymi modelami językowymi za pomocą narzędzi do indeksowania, wyszukiwania i orkiestracji – idealny do RAG, agentów i ustrukturyzowanych wyników.
Czym jest LlamaIndex i dlaczego warto go używać?
- LlamaIndex to framework danych dla aplikacji LLM. Zapewnia elementy składowe dla:
- Pozyskiwania: Ładowanie plików, stron internetowych, baz danych i API.
- Chunking & Indeksowania: Przekształcanie surowej zawartości w struktury z możliwością wyszukiwania (indeksy wektorowe, słów kluczowych, grafów).
- Wyszukiwania: Wyszukiwanie kontekstu za pomocą elastycznych strategii (BM25, hybrydowe, reranking).
- Silników zapytań i agentów: Komponowanie wyszukiwania, narzędzi i promptów w spójne doświadczenie QA.
- Ewaluacji i monitorowania: Ocena jakości wyszukiwania i trafności odpowiedzi.
- Chcesz solidny stos RAG bez ponownego odkrywania chunkingu, embeddingów i wyszukiwania.
- Musisz połączyć wiele źródeł danych (PDF-y + Notion + SQL).
- Chcesz eksperymentować z wyszukiwaniem hybrydowym, rerankingiem lub ustrukturyzowanymi wynikami.
- Podstawowy model mentalny podczas uczenia się, jak używać LlamaIndex:
- Dane → Węzły → Indeks → Retriever → Silnik zapytań → Aplikacja
Szybki start: Minimalna pętla RAG
To najszybsza ścieżka do działającego prototypu. Załadujemy dokumenty, zbudujemy indeks wektorowy i zadamymy pytania.
# 1) Instalacja
# pip install llama-index llama-index-embeddings-openai llama-index-llms-openai
import os
from llama_index.core import VectorStoreIndex, SimpleDirectoryReader
from llama_index.embeddings.openai import OpenAIEmbedding
from llama_index.llms.openai import OpenAI
# 2) Konfiguracja modelu + embeddingów
os.environ["OPENAI_API_KEY"] = "YOUR_KEY" # lub użyj dowolnego obsługiwanego LLM/dostawcy embeddingów
llm = OpenAI(model="gpt-4o-mini")
embed_model = OpenAIEmbedding(model="text-embedding-3-small")
# 3) Załaduj dokumenty (np. ./data/*.pdf, .md, .txt)
docs = SimpleDirectoryReader("./data").load_data
# 4) Zbuduj indeks
index = VectorStoreIndex.from_documents(docs, embed_model=embed_model)
# 5) Utwórz silnik zapytań i zadaj pytanie
query_engine = index.as_query_engine(llm=llm)
response = query_engine.query("What are the key security practices mentioned in the docs?")
print(response)
To jest esencja. Od tego momentu prawdziwe aplikacje dodają lepszy chunking, reranking, ustrukturyzowane prompty i obserwowalność.
Pozyskiwanie: Przynieś własne dane (BYOD) we właściwy sposób
Decydując, jak używać LlamaIndex dla prawdziwych danych, wybierz loadery, które pasują do Twoich źródeł i zachowują strukturę.
- Pliki:
SimpleDirectoryReader, czytniki PDF/HTML/Markdown
- Web:
BeautifulSoupWebReader, czytniki map witryn
- SaaS: Notion, Confluence, Slack, Google Drive (przez konektory)
- Bazy danych: SQL i wektorowe bazy danych (Pinecone, Weaviate, Chroma, Elasticsearch)
- Wskazówka: Znormalizuj metadane (tytuł, autor, URL, created_at). Dobre metadane później doładują reranking i filtrowanie.
from llama_index.core import SimpleDirectoryReader
from llama_index.readers.web import SimpleWebPageReader
file_docs = SimpleDirectoryReader("./policies").load_data
web_docs = SimpleWebPageReader(html_to_text=True).load_data
all_docs = file_docs + web_docs
Chunking i parsery węzłów: Śmieci na wejściu, śmieci na wyjściu
Właściwe ustawienie chunkingu jest jednym z najważniejszych kroków podczas efektywnego uczenia się, jak używać LlamaIndex.
- Dlaczego chunking ma znaczenie: Zbyt duże → nadmiar tokenów i nieistotne wyszukiwanie. Zbyt małe → fragmentacja kontekstu.
- Domyślne ustawienia: Rozsądne w wielu przypadkach, ale dostosuj do rodzaju treści.
- Dokumentacja techniczna: chunki 512–1024 tokenów z 10–20% nakładaniem się.
- FAQ: Mniejsze chunki (256–512), aby zachować nienaruszone pary pytań i odpowiedzi.
- Prawo/Polityka: Większe chunki (1024–1536), aby zachować definicje + klauzule.
from llama_index.core.node_parser import SentenceSplitter
from llama_index.core import Document
parser = SentenceSplitter(chunk_size=800, chunk_overlap=100)
nodes = []
for d in all_docs:
nodes.extend(parser.get_nodes_from_documents([Document(text=d.text, metadata=d.metadata)]))
Strategie indeksowania: Wektorowe, słów kluczowych czy hybrydowe?
Wybór właściwego indeksu jest kluczowy. Dobra wiadomość: LlamaIndex pozwala je łączyć.
- Indeks wektorowy: Świetny do wyszukiwania semantycznego. Najlepszy do zapytań typu „wyjaśnij X” lub niejasnych zapytań.
- Słowa kluczowe (BM25): Mocny dla dokładnych terminów, identyfikatorów, kodów błędów, logów.
- Hybrydowy: Połącz oba; przetasuj najlepszych kandydatów za pomocą LLM lub cross-encodera.
from llama_index.core import VectorStoreIndex, SummaryIndex
from llama_index.core.retrievers import BM25Retriever
from llama_index.core.query_engine import RetrieverQueryEngine
# Indeks wektorowy z wstępnie przetworzonych węzłów
v_index = VectorStoreIndex(nodes)
# Retriever słów kluczowych BM25
bm25_retriever = BM25Retriever.from_defaults(nodes=nodes, similarity_top_k=6)
# Hybrydowy: połącz kandydatów, a następnie przetasuj
from llama_index.core.retrievers import RouterRetriever
from llama_index.retrievers.merge import MergerRetriever
v_retriever = v_index.as_retriever(similarity_top_k=6)
hybrid = MergerRetriever(retrievers=[v_retriever, bm25_retriever], top_k=8)
query_engine = RetrieverQueryEngine.from_args(retriever=hybrid)
Reranking i filtry: Zwiększ precyzję bez przepłacania
Reranking poprawia jakość odpowiedzi poprzez zmianę kolejności pobranych chunków zgodnie z trafnością.
- Kiedy rerankować: Jeśli użytkownicy zgłaszają cytaty nie na temat lub długie, rozwlekłe konteksty.
- Cross-encodery (wyszukiwanie embeddingów bi-encoder → reranking cross-encoder)
- Reranking oparte na LLM (bardziej kosztowne, czasami mądrzejsze w przypadku subtelnego tekstu)
- Filtry metadanych (np.
source == 'handbook', created_at > 2024-01-01)
from llama_index.postprocessor.flag_embedding_reranker import FlagEmbeddingReranker
from llama_index.core.query_engine import RetrieverQueryEngine
reranker = FlagEmbeddingReranker(top_n=5, model="BAAI/bge-reranker-base")
query_engine = v_index.as_query_engine(
similarity_top_k=12,
node_postprocessors=[reranker]
)
Prompty i silniki zapytań: Od wyszukiwania do odpowiedzi
Silnik zapytań to miejsce, gdzie wyszukiwanie spotyka się z generowaniem. Aby opanować sposób użycia LlamaIndex w produkcji, starannie projektuj prompty i syntezę odpowiedzi.
- Strategie syntezy odpowiedzi:
- Proste „stuff” (łączenie) dla małych kontekstów
- Tree lub map-reduce dla dłuższych kontekstów
- Tryb cytowania, aby pokazać źródła
from llama_index.core.response_synthesizers import get_response_synthesizer
from llama_index.core import ServiceContext
synth = get_response_synthesizer(response_mode="tree_summarize")
query_engine = v_index.as_query_engine(response_synthesizer=synth)
ans = query_engine.query("Summarize the onboarding steps and cite sources.")
print(ans)
- Niestandardowe prompty: Dostosuj ton, ustrukturyzowane wyniki lub bariery ochronne.
from llama_index.core.prompts import PromptTemplate
qa_tmpl = PromptTemplate(
"""
You are a terse, evidence-first assistant. Use only the provided context.
If unsure, say you don't know. Return JSON with keys: answer, sources.
Question: {query_str}
Context: {context_str}
"""
)
query_engine = v_index.as_query_engine(text_qa_template=qa_tmpl)
Agenci i narzędzia: Kiedy wyszukiwanie nie wystarcza
Czasami odpowiedzi wymagają działań: uruchamiania SQL, wywoływania API lub przeglądania. Agenci LlamaIndex koordynują narzędzia i rozumowanie z potokiem wyszukiwania.
- Przypadki użycia: Panele KPI (narzędzie SQL), boty wsparcia (API wyszukiwania zgłoszeń), agenci badawczy (web + RAG).
from llama_index.core.agent import ReActAgent
from llama_index.tools.sql import SQLQueryEngineTool
from sqlalchemy import create_engine
engine = create_engine("sqlite:///analytics.db")
sql_tool = SQLQueryEngineTool.from_engine(engine)
agent = ReActAgent.from_tools([sql_tool], llm=llm, verbose=True)
agent.chat("What was monthly churn in Q2 2025? If needed, query the DB.")
Ewaluacja: Nie wdrażaj na ślepo
Odpowiedzialne uczenie się, jak używać LlamaIndex, oznacza walidację zarówno wyszukiwania, jak i odpowiedzi przed wdrożeniem.
- Ewaluacja offline: Oceń recall/precision wyszukiwania na oznaczonym zbiorze.
- Ewaluacja online: Rejestruj prompty użytkowników, mierz satysfakcję, wskaźniki odrzucenia i halucynacje.
- Wbudowane funkcje: LlamaIndex udostępnia pomocników ewaluacyjnych dla wierności i trafności odpowiedzi.
from llama_index.core.evaluation import FaithfulnessEvaluator, RelevancyEvaluator
faith = FaithfulnessEvaluator(llm=llm)
rel = RelevancyEvaluator(llm=llm)
pred = query_engine.query("List SOC 2 control families in our policy.")
print("faithful?", faith.evaluate_response(pred))
print("relevant?", rel.evaluate_response(pred))
- Praktyczny próg: W przypadku wewnętrznych asystentów, dąż do oceny >80% „użyteczności” dla najważniejszych zapytań przed szerokim uruchomieniem.
Persystencja i wektorowe bazy danych: Uczyń to skalowalnym
Indeksy zbudowane w pamięci nie sprawdzą się w przypadku prawdziwych obciążeń. Utrwalaj w wektorowej bazie danych i włącz przyrostowe aktualizacje.
- Popularne back-endy: Pinecone, Weaviate, Chroma, Elasticsearch/OpenSearch, Qdrant.
- Wskazówka: Używaj przestrzeni nazw na najemcę lub dział; zachowaj bogate metadane.
# Przykład: Chroma
# pip install chromadb llama-index-vector-stores-chroma
from llama_index.vector_stores.chroma import ChromaVectorStore
from llama_index.core import StorageContext
import chromadb
chroma_client = chromadb.PersistentClient(path="./chroma_store")
collection = chroma_client.get_or_create_collection("company_knowledge")
vector_store = ChromaVectorStore(chroma_collection=collection)
storage_context = StorageContext.from_defaults(vector_store=vector_store)
index = VectorStoreIndex.from_documents(all_docs, storage_context=storage_context)
Bezpieczeństwo i zarządzanie: Część, o której wszyscy zapominają
- Obsługa PII: Redaguj lub haszuj wrażliwe pola podczas pozyskiwania.
- Kontrola dostępu: Filtruj według ról użytkowników za pomocą ograniczeń metadanych.
- Świeżość treści: Zaplanuj ponowne pozyskiwanie; oznaczaj wersje.
- Bezpieczeństwo: Dodaj zasady odmowy i ograniczenia tylko do źródeł w promptach.
# Przykład: filtrowanie oparte na metadanych w czasie zapytań
retriever = index.as_retriever(similarity_top_k=8)
retriever.metadata_filters = {"department": ["legal", "security"], "published": [True]}
Od prototypu do produkcji: Wzorce wdrażania
- Wzorzec serwera: Ujawnij endpoint
/query; utrzymuj indeks w pamięci operacyjnej.
- Pułapka serverless: Zimne starty + duże modele mogą zaszkodzić opóźnieniom; rozważ zarządzaną inferencję.
- Buforowanie: Buforuj embeddingi i częste wyniki zapytań; włącz częściowe aktualizacje.
- Obserwowalność: Rejestruj pobrane węzły, użycie tokenów, długość odpowiedzi i opinie użytkowników.
# Minimalna otoczka FastAPI
# pip install fastapi uvicorn
from fastapi import FastAPI
app = FastAPI
qe = index.as_query_engine(llm=llm)
@app.post("/query")
async def query(payload: dict):
q = payload.get("q", "")
resp = qe.query(q)
return {"answer": str(resp), "sources": [s.node.metadata for s in resp.source_nodes]}
Realne schematy: Wybierz swoją ścieżkę
- Wewnętrzny asystent ds. polityki
- Indeks: Hybrydowy (BM25 + wektorowy) z rerankingiem
- Bariery ochronne: Tryb tylko źródłowy; „Nie wiem” jako fallback
- KPI: Wskaźnik rozwiązania dla pytań dotyczących polityki
- Indeks: Dokumentacja produktu + informacje o wydaniu + zgłoszenia
- Agenci: Narzędzie API do sprawdzania statusu zamówienia/zgłoszenia
- KPI: Rozwiązanie przy pierwszym kontakcie, odrzucenie, CSAT
- Indeks: Web + PDF-y + notatki; silna deduplikacja
- Rerank: Cross-encoder; synteza: map-reduce
- KPI: Czas do uzyskania wglądu; dokładność cytowania
- Narzędzia: Silnik SQL + RAG na definicjach metryk
- Zarządzanie: Zasady na poziomie wiersza; audyt zapytań
- KPI: Poprawność vs. prawda podstawowa
Koszt i opóźnienie: Utrzymuj szybkość (i niski koszt)
- Embeddingi: Przetwarzaj wsadowo, gdzie to możliwe; używaj mniejszych modeli do recall, rerankuj selektywnie.
- Rozmiar kontekstu: Dąż do 1–2 tys. tokenów najbardziej odpowiednich chunków.
- Buforowanie: Buforuj wyszukiwanie top-K dla popularnych zapytań; memoizuj wywołania LLM z haszowanymi promptami.
- Równoległość: Rozdziel wyszukiwanie → zbierz reranking, aby zmniejszyć opóźnienie ogona.
Typowe pułapki podczas uczenia się, jak używać LlamaIndex
- Nadmierny chunking, prowadzący do płytkiego, zaszumionego wyszukiwania
- Brak filtrów metadanych, powodujący przedostawanie się nieistotnych źródeł
- Poleganie na jednym typie indeksu dla całej zawartości
- Pomijanie ewaluacji; wdrażanie bez progu jakości
- Pozwalanie indeksom na starzenie się; brak zaplanowanego odświeżania
Przy okazji: Przyspieszenie przepływu pracy w edytorze
Podczas iteracji nad promptami, chunkerami i ustawieniami wyszukiwania warto zauważyć, że pasek boczny do kodowania i badań AI, taki jak Sider.ai, może przyspieszyć pętlę. Możesz mieć pod ręką fragmenty kodu, prompty i notatki ewaluacyjne, generować różnice w zmianach promptów i szybko testować warianty bez opuszczania przeglądarki. Jest to szczególnie przydatne, gdy dostosowujesz sposób użycia LlamaIndex w różnych strategiach wyszukiwania. Lista kontrolna krok po kroku: Od zera do produkcji
- Pozyskaj źródła i znormalizuj metadane
- Dostosuj rozmiary chunków według rodzaju treści
- Zbuduj indeksy wektorowe + BM25; włącz wyszukiwanie hybrydowe
- Dodaj reranking i filtry metadanych
- Dostosuj prompty; włącz cytaty i zasady odmowy
- Oceń wierność i trafność na zbiorze testowym
- Utrwalaj w wektorowej bazie danych; włącz przyrostowe aktualizacje
- Dodaj obserwowalność, buforowanie i filtry RBAC
- Owiń w API i ustaw SLA; udokumentuj tryby awarii
Kluczowe wnioski
- Jeśli chcesz solidną aplikację RAG, nauczenie się, jak używać LlamaIndex, zaoszczędzi tygodnie inżynierii klejącej.
- Zacznij prosto, a następnie dodaj wyszukiwanie hybrydowe, reranking i ustrukturyzowane prompty.
- Oceń przed skalowaniem; utrwalaj indeksy i monitoruj jakość w produkcji.
- Projektuj z myślą o zarządzaniu od samego początku – bezpieczeństwo nie jest dodatkiem.
Następne kroki
- Wykonaj prototyp szybkiego startu na małym zestawie dokumentów.
- Poeksperymentuj z wyszukiwaniem hybrydowym i rerankerem.
- Dodaj ewaluację i cytaty; śledź metryki jakości.
- Przejdź do trwałej wektorowej bazy danych i wdróż API.
FAQ
Q1: Do czego służy LlamaIndex w aplikacjach RAG?
LlamaIndex pomaga łączyć dane z LLM za pomocą komponentów pozyskiwania, indeksowania i wyszukiwania. Usprawnia budowanie systemów RAG, obsługując chunking, indeksy wektorowe/słów kluczowych i orkiestrację zapytań.
Q2: Jak wybrać odpowiedni typ indeksu w LlamaIndex?
Użyj indeksu wektorowego dla zapytań semantycznych, BM25 dla dokładnych dopasowań, takich jak identyfikatory lub kody, oraz podejścia hybrydowego dla najlepszego ogólnego recall i precision. Wiele zespołów łączy oba i dodaje reranking dla wyników top-K.
Pytanie 3: Jak mogę poprawić dokładność podczas korzystania z LlamaIndex?
Dostosuj rozmiary fragmentów, dodaj bogate metadane, włącz hybrydowe wyszukiwanie i dodaj funkcję ponownego rankingu. Wprowadź również ocenę pod kątem wiarygodności i trafności oraz użyj trybu cytowania, aby pokazać źródła.
Pytanie 4: Czy LlamaIndex może współpracować z moją istniejącą bazą danych wektorowych?
Tak. LlamaIndex integruje się z popularnymi magazynami wektorowymi, takimi jak Pinecone, Weaviate, Chroma, Qdrant i Elasticsearch. Utrwal indeksy, aby zapewnić skalowalność i przyrostowe aktualizacje.
Pytanie 5: Jak wdrożyć aplikację LlamaIndex do środowiska produkcyjnego?
Umieść silnik zapytań w API (np. FastAPI), utrwal dane w magazynie wektorowym, dodaj buforowanie i możliwość obserwacji oraz stale oceniaj jakość. Wymuś filtry metadanych i kontrolę dostępu dla bezpieczeństwa.