Ako používať LlamaIndex: Praktický sprievodca od nuly po produkciu
Ak ste sa niekedy pokúšali vytvoriť aplikáciu na generovanie rozšírené o získavanie (RAG) a pomysleli ste si: „Prečo je prepojenie embeddingov, vektorových úložísk a promptov také zložité?“, nie ste sami. existuje na to, aby tento proces bol rýchly, rozumný a pripravený na produkciu. V tomto praktickom, na riešenia orientovanom sprievodcovi si prejdeme, ako používať end-to-end – príjem dát, indexovanie, dopytovanie, vyhodnocovanie a nasadenie – aby ste mohli dodať niečo spoľahlivé bez toho, aby ste sa stratili v zlepenom kóde.
Použijeme štruktúru riadenú otázkami s postupnými krokmi, spustiteľnými úryvkami a tipmi z reálneho sveta. Či už prototypujete chatbota pre internú dokumentáciu alebo nasadzujete asistenta znalostí pre zákazníkov, efektívne naučiť sa používať vám ušetrí dni.
: je framework, ktorý vám pomáha prepojiť vaše dáta s rozsiahlymi jazykovými modelmi pomocou nástrojov na indexovanie, získavanie a orchestráciu – ideálne pre RAG, agentov a štruktúrované výstupy.
Čo je a prečo ho používať?
- LlamaIndex je dátový framework pre LLM aplikácie. Poskytuje stavebné bloky pre:
- Príjem dát: Načítanie súborov, webových stránok, databáz a API.
- Chunking & Indexovanie: Premena surového obsahu na štruktúry, ktoré sa dajú dopytovať (vektorové, kľúčové slová, grafové indexy).
- Získavanie: Získavanie kontextu s flexibilnými stratégiami (BM25, hybridné, prehodnocovanie).
- Dopytovacie enginy & Agenti: Skladanie získavania, nástrojov a promptov do uceleného QA zážitku.
- Vyhodnocovanie & Monitorovanie: Posudzovanie kvality získavania a relevantnosti odpovedí.
- Kedy používať LlamaIndex:
- Chcete robustný RAG stack bez toho, aby ste znovu vynašli chunking, embeddingy a získavanie.
- Potrebujete kombinovať viacero zdrojov dát (PDF + Notion + SQL).
- Chcete experimentovať s hybridným získavaním, prehodnocovaním alebo štruktúrovanými výstupmi.
- LlamaIndex pri učení sa, ako používať LlamaIndex:
- Dáta → Nody → Index → Retriever → Dopytovací Engine → Aplikácia
Rýchly štart: Minimálna RAG slučka
Toto je najrýchlejšia cesta k funkčnému prototypu. Načítame dokumenty, vytvoríme vektorový index a položíme otázky.
# 1) Inštalácia
# 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) Konfigurácia modelu + embeddingov
os.environ["OPENAI_API_KEY"] = "YOUR_KEY" # alebo použite ľubovoľného podporovaného poskytovateľa LLM/embeddingov
llm = OpenAI(model="gpt-4o-mini")
embed_model = OpenAIEmbedding(model="text-embedding-3-small")
# 3) Načítanie dokumentov (napr. ./data/*.pdf, .md, .txt)
docs = SimpleDirectoryReader("./data").load_data
# 4) Vytvorenie indexu
index = VectorStoreIndex.from_documents(docs, embed_model=embed_model)
# 5) Vytvorenie dopytovacieho enginu a položenie otázky
query_engine = index.as_query_engine(llm=llm)
response = query_engine.query("Aké sú kľúčové bezpečnostné postupy uvedené v dokumentoch?")
print(response)
To je podstata. Od tohto bodu reálne aplikácie pridávajú lepší chunking, prehodnocovanie, štruktúrované prompty a pozorovateľnosť.
Príjem dát: Prineste si vlastné dáta (BYOD) správnym spôsobom
Keď sa rozhodujete, ako používať pre reálne dáta, vyberte si loadery, ktoré zodpovedajú vašim zdrojom a zachovávajú štruktúru.
- Súbory:
SimpleDirectoryReader, čítačky PDF/HTML/Markdown
- Web:
BeautifulSoupWebReader, čítačky máp stránok
- SaaS: Notion, Confluence, Slack, Google Drive (cez konektory)
- Databázy: SQL a vektorové DB (Pinecone, Weaviate, Chroma, Elasticsearch)
- Tip: Normalizujte metadáta (názov, autor, URL, created_at). Dobré metadáta neskôr výrazne vylepšia prehodnocovanie a filtrovanie.
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 a Node Parsers: Čo do toho dáš, to z toho dostaneš
Správne nastavenie chunkingu je jedným z najdôležitejších krokov pri efektívnom učení sa používať .
- Prečo záleží na chunkingu: Príliš veľké → nafúknutie tokenov a irelevantné získavanie. Príliš malé → fragmentácia kontextu.
- Predvolené hodnoty: Rozumné pre mnohé prípady, ale prispôsobte ich pre váš typ obsahu.
- Technická dokumentácia: 512–1024 tokenových chunkov s 10–20% prekrytím.
- FAQ: Menšie chunky (256–512) na zachovanie párov otázok a odpovedí.
- Právne/Politické: Väčšie chunky (1024–1536) na zachovanie definícií + klauzúl.
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)]))
Indexové stratégie: Vektorové, kľúčové slová alebo hybridné?
Výber správneho indexu je kľúčový. Dobrá správa: vám umožňuje ich kombinovať.
- Vektorový index: Skvelý pre sémantické vyhľadávanie. Najlepší pre „vysvetli X“ alebo nejasné dopyty.
- Kľúčové slová (BM25): Silný pre presné výrazy, ID, chybové kódy, logy.
- Hybridný: Kombinujte oboje; prehodnoťte najlepších kandidátov pomocou LLM alebo cross-encodera.
from llama_index.core import VectorStoreIndex, SummaryIndex
from llama_index.core.retrievers import BM25Retriever
from llama_index.core.query_engine import RetrieverQueryEngine
# Vektorový index z pre-parsovaných nodov
v_index = VectorStoreIndex(nodes)
# BM25 retriever kľúčových slov
bm25_retriever = BM25Retriever.from_defaults(nodes=nodes, similarity_top_k=6)
# Hybridný: zlúčenie kandidátov, potom prehodnotenie
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)
Prehodnocovanie a filtre: Zvýšte presnosť bez preplácania
Prehodnocovanie zlepšuje kvalitu odpovedí preusporiadaním získaných chunkov podľa relevantnosti.
- Kedy prehodnocovať: Ak používatelia hlásia citácie mimo témy alebo dlhé, vypchaté kontexty.
- Cross-encodery (bi-encoder embedding search → cross-encoder rerank)
- Prehodnocovanie založené na LLM (nákladnejšie, niekedy inteligentnejšie pri jemnom texte)
- Filtre metadát (napr.
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]
)
Promptovanie a dopytovacie enginy: Od vyhľadávania k odpovediam
Dopytovací engine je miesto, kde sa stretáva získavanie s generovaním. Ak chcete zvládnuť, ako používať v produkcii, starostlivo navrhnite prompty a syntézu odpovedí.
- Syntéza odpovedí stratégie:
- Jednoduché „stuff“ (zreťazenie) pre malé kontexty
- Strom alebo map-reduce pre dlhšie kontexty
- Režim citácií na zobrazenie zdrojov
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("Zhrňte kroky onboardingu a uveďte zdroje.")
print(ans)
- Vlastné prompty: Prispôsobte tón, štruktúrované výstupy alebo ochranné zábradlia.
from llama_index.core.prompts import PromptTemplate
qa_tmpl = PromptTemplate(
"""
Ste stručný asistent, ktorý sa riadi dôkazmi. Používajte iba poskytnutý kontext.
Ak si nie ste istí, povedzte, že neviete. Vráťte JSON s kľúčmi: odpoveď, zdroje.
Otázka: {query_str}
Kontext: {context_str}
"""
)
query_engine = v_index.as_query_engine(text_qa_template=qa_tmpl)
Agenti a nástroje: Keď získavanie nestačí
Niekedy odpovede vyžadujú akcie: spustenie SQL, volanie API alebo prehliadanie. agenti koordinujú nástroje a uvažovanie s vaším procesom získavania.
- Prípady použitia: KPI dashboardy (SQL nástroj), support boty (API na vyhľadávanie tiketov), výskumní agenti (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("Aký bol mesačný churn v Q2 2025? Ak je to potrebné, dopytujte sa v DB.")
Vyhodnocovanie: Nenasadzujte naslepo
Zodpovedné naučenie sa používať znamená overenie získavania aj odpovedí pred nasadením.
- Offline eval: Posúďte recall/precision získavania na označenom súbore.
- Online eval: Zaznamenávajte používateľské prompty, merajte spokojnosť, miery odklonu a halucinácie.
- LlamaIndex: LlamaIndex poskytuje pomocníkov na vyhodnocovanie vernosti a relevantnosti odpovedí.
from llama_index.core.evaluation import FaithfulnessEvaluator, RelevancyEvaluator
faith = FaithfulnessEvaluator(llm=llm)
rel = RelevancyEvaluator(llm=llm)
pred = query_engine.query("Zoznam SOC 2 kontrolných rodín v našej politike.")
print("verný?", faith.evaluate_response(pred))
print("relevantný?", rel.evaluate_response(pred))
- Praktická hranica: Pre interných asistentov zacielte na >80% „užitočné“ hodnotenie na najlepšie dopyty pred rozsiahlym spustením.
Perzistencia a vektorové úložiská: Urobte to škálovateľným
Indexy vytvorené v pamäti nebudú stačiť pre reálne pracovné zaťaženia. Uložte ich do vektorovej DB a povoľte inkrementálne aktualizácie.
- Populárne backendy: Pinecone, Weaviate, Chroma, Elasticsearch/OpenSearch, Qdrant.
- Tip: Používajte menné priestory pre každého nájomníka alebo oddelenie; udržujte bohaté metadáta.
# Príklad: 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)
Bezpečnosť a riadenie: Časť, na ktorú všetci zabúdajú
- Manipulácia s PII: Redigujte alebo hashujte citlivé polia počas príjmu.
- Riadenie prístupu: Filtrujte podľa rolí používateľov pomocou obmedzení metadát.
- Čerstvosť obsahu: Naplánujte opakovaný príjem; označte verzie.
- Bezpečnosť: Pridajte zásady odmietnutia a obmedzenia iba na zdroje v promptoch.
# Príklad: filtrovanie na základe metadát v čase dopytu
retriever = index.as_retriever(similarity_top_k=8)
retriever.metadata_filters = {"department": ["legal", "security"], "published": [True]}
Od prototypu po produkciu: Vzory nasadenia
- Serverový vzor: Vystavte endpoint
/query; udržujte index v pamäti.
- Serverless úskalie: Studené štarty + veľké modely môžu poškodiť latenciu; zvážte spravovanú inferenciu.
- Caching: Cacheujte embeddingy a časté výsledky dopytov; povoľte čiastočné aktualizácie.
- Pozorovateľnosť: Zaznamenávajte získané nody, použitie tokenov, dĺžku odpovede a spätnú väzbu od používateľov.
# Minimálny FastAPI wrapper
# 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]}
Blueprints z reálneho sveta: Vyberte si svoju cestu
- Interný asistent politiky
- Index: Hybridný (BM25 + Vektor) s prehodnocovaním
- Ochranné zábradlia: Režim iba pre zdroje; „Neviem“ fallback
- KPI: Miera riešenia pre politické otázky
- Copilot zákazníckej podpory
- Index: Dokumenty k produktu + poznámky k vydaniu + tikety
- Agenti: API nástroj na kontrolu stavu objednávky/tiketu
- KPI: Riešenie pri prvom kontakte, odklon, CSAT
- Index: Web + PDF + poznámky; silná deduplikácia
- Prehodnocovanie: Cross-encoder; syntéza: map-reduce
- KPI: Čas na získanie prehľadu; presnosť citácií
- Nástroje: SQL engine + RAG na definíciách metrík
- Riadenie: Zásady na úrovni riadkov; audit dopytov
- KPI: Správnosť vs. ground truth
Náklady a latencia: Udržujte to rýchle (a lacné)
- Embeddingy: Dávkujte, kde je to možné; používajte menšie modely na recall, selektívne prehodnocujte.
- Veľkosť kontextu: Zamerajte sa na 1–2k tokenov najrelevantnejších chunkov.
- Caching: Cacheujte top-K získavanie pre horúce dopyty; memoizujte LLM hovory s hashovanými promptami.
- Paralelizmus: Fan-out získavanie → fan-in prehodnocovanie na zníženie latencie chvosta.
Bežné úskalia pri učení sa, ako používať
- Nadmerný chunking, ktorý vedie k plytkému, hlučnému získavaniu
- Žiadne filtre metadát, čo spôsobuje, že sa vkrádajú irelevantné zdroje
- Spoliehanie sa na jeden typ indexu pre všetok obsah
- Preskakovanie vyhodnocovania; nasadzovanie bez kvalitatívnej hranice
- Nechávanie indexov zastarať; žiadne naplánované obnovenie
Mimochodom: Zrýchlenie vášho pracovného postupu v editore
Keď iterujete na promptoch, chunkeroch a nastaveniach získavania, stojí za zmienku, že bočný panel s AI kódovaním a výskumom, ako je Sider.ai, môže urýchliť slučku. Môžete mať po ruke úryvky, prompty a poznámky k vyhodnocovaniu, generovať rozdiely v zmenách promptov a rýchlo testovať variácie bez toho, aby ste opustili svoj prehliadač. To je obzvlášť užitočné, keď dolaďujete, ako používať v rôznych stratégiách získavania. Kontrolný zoznam krok za krokom: Od nuly po produkciu
- Príjem zdrojov a normalizácia metadát
- Dolaďte veľkosti chunkov podľa typu obsahu
- Vytvorte vektorové + BM25 indexy; povoľte hybridné získavanie
- Pridajte prehodnocovanie a filtre metadát
- Prispôsobte prompty; povoľte citácie a zásady odmietnutia
- Vyhodnoťte vernosť a relevantnosť na testovacej sade
- Uložte do vektorového úložiska; povoľte inkrementálne aktualizácie
- Pridajte pozorovateľnosť, ukladanie do vyrovnávacej pamäte a filtre RBAC
- Zabaliť do API a nastaviť SLA; zdokumentovať režimy zlyhania
Kľúčové poznatky
- Ak chcete robustnú aplikáciu RAG, naučiť sa používať vám ušetrí týždne zlepeného inžinierstva.
- Začnite jednoducho, potom pridajte hybridné získavanie, prehodnocovanie a štruktúrované prompty.
- Vyhodnoťte predtým, ako budete škálovať; uložte indexy a monitorujte kvalitu v produkcii.
- Navrhnite riadenie od prvého dňa – bezpečnosť nie je dodatočná súčasť.
Ďalšie kroky
- Vytvorte prototyp rýchleho spustenia na malej sade dokumentov.
- Experimentujte s hybridným získavaním a prehodnocovačom.
- Pridajte vyhodnocovanie a citácie; sledujte metriky kvality.
- Presuňte sa do trvalého vektorového úložiska a nasaďte API.
FAQ
Q1: Na čo sa používa LlamaIndex v aplikáciách RAG?
LlamaIndex vám pomáha pripojiť vaše dáta k LLM pomocou komponentov na príjem, indexovanie a vyhľadávanie. Zefektívňuje budovanie systémov RAG spracovaním chunkingu, vektorových/kľúčových indexov a orchestrácie dopytov.
Q2: Ako si vyberiem správny typ indexu v LlamaIndex?
Použite vektorový index pre sémantické dopyty, BM25 pre presné zhody, ako sú ID alebo kódy, a hybridný prístup pre najlepší celkový recall a presnosť. Mnohé tímy kombinujú oboje a pridávajú prehodnocovanie pre výsledky top-K.
Otázka 3: Ako môžem zlepšiť presnosť pri používaní LlamaIndex?
Upravte veľkosť blokov (chunks), zahrňte bohaté metadáta, povoľte hybridné vyhľadávanie a pridajte prehodnocovač (reranker). Implementujte tiež vyhodnocovanie pre vernosť a relevantnosť a použite citačný režim na zobrazenie zdrojov.
Otázka 4: Môže LlamaIndex pracovať s mojou existujúcou vektorovou databázou?
Áno. LlamaIndex sa integruje s populárnymi vektorovými úložiskami ako Pinecone, Weaviate, Chroma, Qdrant a Elasticsearch. Uložte indexy pre škálovateľnosť a inkrementálne aktualizácie.
Otázka 5: Ako nasadím aplikáciu LlamaIndex do produkcie?
Zabaľte svoj dopytovací engine do API (napr. FastAPI), uložte dáta do vektorového úložiska, pridajte ukladanie do vyrovnávacej pamäte a pozorovateľnosť a nepretržite vyhodnocujte kvalitu. Vynucujte filtre metadát a riadenie prístupu pre bezpečnosť.