Jak používat LlamaIndex: Praktický průvodce od nuly do produkce
Pokud jste se někdy pokusili vytvořit aplikaci pro generování rozšířené o načítání (RAG) a pomysleli jste si: „Proč je propojování vkládání, vektorových úložišť a výzev tak komplikované?“, nejste sami. existuje proto, aby tento proces urychlil, zjednodušil a připravil na produkční prostředí. V tomto praktickém průvodci zaměřeném na řešení si projdeme, jak používat end-to-end – příjem dat, indexování, dotazování, vyhodnocování a nasazení – abyste mohli dodat něco spolehlivého, aniž byste se ztratili v propojovacím kódu.
Použijeme strukturu založenou na otázkách s postupnými kroky, spustitelnými úryvky a tipy z reálného světa. Ať už prototypujete chatbota pro interní dokumenty nebo nasazujete znalostního asistenta pro zákazníky, efektivní naučení se používat vám ušetří dny práce.
: je framework, který vám pomáhá propojit vaše data s velkými jazykovými modely pomocí nástrojů pro indexování, načítání a orchestraci – ideální pro RAG, agenty a strukturované výstupy.
Co je a proč ho používat?
- LlamaIndex je datový framework pro aplikace LLM. Poskytuje stavební bloky pro:
- Příjem dat: Načítání souborů, webových stránek, databází a API.
- Rozdělování a indexování: Přeměna surového obsahu na dotazovatelné struktury (vektorové, klíčové, grafové indexy).
- Načítání: Načítání kontextu s flexibilními strategiemi (BM25, hybridní, přeřazování).
- Dotazovací enginy a agenti: Skládání načítání, nástrojů a výzev do uceleného QA zážitku.
- Vyhodnocování a monitorování: Posuzování kvality načítání a relevance odpovědí.
- Chcete robustní RAG stack bez nutnosti znovu vynalézat rozdělování, vkládání a načítání.
- Potřebujete zkombinovat více zdrojů dat (PDF + Notion + SQL).
- Chcete experimentovat s hybridním načítáním, přeřazováním nebo strukturovanými výstupy.
- LlamaIndex při učení se, jak používat LlamaIndex:
- Data → Nody → Index → Retriever → Dotazovací engine → Aplikace
Rychlý start: Minimální RAG smyčka
Toto je nejrychlejší cesta k funkčnímu prototypu. Načteme dokumenty, vytvoříme vektorový index a položíme otázky.
# 1) Instalace
# 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) Konfigurace modelu + vkládání
os.environ["OPENAI_API_KEY"] = "YOUR_KEY" # nebo použijte jakéhokoli podporovaného poskytovatele LLM/vkládání
llm = OpenAI(model="gpt-4o-mini")
embed_model = OpenAIEmbedding(model="text-embedding-3-small")
# 3) Načtení dokumentů (např. ./data/*.pdf, .md, .txt)
docs = SimpleDirectoryReader("./data").load_data
# 4) Vytvoření indexu
index = VectorStoreIndex.from_documents(docs, embed_model=embed_model)
# 5) Vytvoření dotazovacího enginu a položení otázky
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 je podstata. Od tohoto bodu reálné aplikace přidávají lepší rozdělování, přeřazování, strukturované výzvy a pozorovatelnost.
Příjem dat: Přineste si vlastní data (BYOD) správným způsobem
Když se rozhodujete, jak používat pro reálná data, vyberte loadery, které odpovídají vašim zdrojům a zachovávají strukturu.
- Soubory:
SimpleDirectoryReader, čtečky PDF/HTML/Markdown
- Web:
BeautifulSoupWebReader, čtečky sitemap
- SaaS: Notion, Confluence, Slack, Google Drive (prostřednictvím konektorů)
- Databáze: SQL a vektorové DB (Pinecone, Weaviate, Chroma, Elasticsearch)
- Tip: Normalizujte metadata (název, autor, URL, created_at). Dobrá metadata později výrazně vylepšují přeřazování a filtrování.
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
Rozdělování a Node Parsers: Co do toho dáš, to z toho vyleze
Správné rozdělení je jedním z nejdůležitějších kroků, když se efektivně učíte používat .
- Proč na rozdělování záleží?: Příliš velké → nafouknutí tokenů a irelevantní načítání. Příliš malé → fragmentace kontextu.
- Výchozí nastavení: Rozumné pro mnoho případů, ale dolaďte pro svůj typ obsahu.
- Technická dokumentace: 512–1024 tokenů s 10–20% překrytím.
- FAQ: Menší bloky (256–512) pro zachování párů otázek a odpovědí.
- Právní/zásady: Větší bloky (1024–1536) pro zachování definic + klauzulí.
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)]))
Indexovací strategie: Vektorová, klíčová slova nebo hybridní?
Výběr správného indexu je zásadní. Dobrá zpráva: vám umožňuje je kombinovat.
- Vektorový index: Skvělý pro sémantické vyhledávání. Nejlepší pro „vysvětli X“ nebo nejasné dotazy.
- Klíčová slova (BM25): Silný pro přesné termíny, ID, chybové kódy, protokoly.
- Hybridní: Kombinujte obojí; přeřaďte nejlepší kandidáty pomocí LLM nebo cross‑encoderu.
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 předem analyzovaných nodů
v_index = VectorStoreIndex(nodes)
# BM25 klíčový retriever
bm25_retriever = BM25Retriever.from_defaults(nodes=nodes, similarity_top_k=6)
# Hybridní: sloučení kandidátů, poté přeřazení
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)
Přeřazování a filtry: Zvyšte přesnost bez zbytečných nákladů
Přeřazování zlepšuje kvalitu odpovědí tím, že přeřazuje načtené bloky podle relevance.
- Kdy přeřazovat: Pokud uživatelé hlásí citace mimo téma nebo dlouhé, vycpávané kontexty.
- Cross‑encoders (bi‑encoder embedding search → cross-encoder rerank)
- Přeřazování založené na LLM (nákladnější, někdy chytřejší na jemný text)
- Filtry metadat (např.
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]
)
Výzvy a dotazovací enginy: Od vyhledávání k odpovědím
Dotazovací engine je místo, kde se načítání setkává s generováním. Chcete-li zvládnout, jak používat v produkci, pečlivě navrhujte výzvy a syntézu odpovědí.
- Syntéza odpovědí strategie:
- Jednoduché „stuff“ (zřetězení) pro malé kontexty
- Strom nebo map‑reduce pro delší kontexty
- Režim citací pro zobrazení zdrojů
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)
- Vlastní výzvy: Přizpůsobte tón, strukturované výstupy nebo zábrany.
from llama_index.core.prompts import PromptTemplate
qa_tmpl = PromptTemplate(
"""
Jste stručný asistent, který se řídí důkazy. Používejte pouze poskytnutý kontext.
Pokud si nejste jisti, řekněte, že nevíte. Vraťte JSON s klíči: answer, sources.
Question: {query_str}
Context: {context_str}
"""
)
query_engine = v_index.as_query_engine(text_qa_template=qa_tmpl)
Agenti a nástroje: Když načítání nestačí
Někdy odpovědi vyžadují akce: spouštění SQL, volání API nebo procházení webu. Agenti koordinují nástroje a uvažování s vaším kanálem načítání.
- Případy použití: KPI dashboardy (SQL nástroj), podpůrní boti (API pro vyhledávání tiketů), výzkumní 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("What was monthly churn in Q2 2025? If needed, query the DB.")
Vyhodnocování: Nenasazujte naslepo
Zodpovědné naučení se používat znamená ověřování načítání i odpovědí před zavedením.
- Offline eval: Posuďte recall/precision načítání na označené sadě.
- Online eval: Protokolujte uživatelské výzvy, měřte spokojenost, míru odklonění a halucinace.
- LlamaIndex: LlamaIndex poskytuje pomocníky pro vyhodnocování věrnosti a relevance odpovědí.
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))
- Praktická hranice: U interních asistentů cílejte na >80% hodnocení „užitečné“ u nejčastějších dotazů před širokým spuštěním.
Perzistence a vektorové úložiště: Zajistěte škálovatelnost
Indexy vytvořené v paměti nebudou stačit pro reálné pracovní zátěže. Uložte je do vektorové DB a povolte inkrementální aktualizace.
- Populární back-endy: Pinecone, Weaviate, Chroma, Elasticsearch/OpenSearch, Qdrant.
- Tip: Používejte jmenné prostory pro každého nájemníka nebo oddělení; udržujte metadata bohatá.
# Pří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)
Zabezpečení a správa: Část, na kterou všichni zapomínají
- Zpracování PII: Redigujte nebo hashujte citlivá pole během příjmu dat.
- Řízení přístupu: Filtrujte podle rolí uživatelů pomocí omezení metadat.
- Čerstvost obsahu: Naplánujte opětovné načítání; označte verze.
- Bezpečnost: Přidejte zásady odmítnutí a omezení pouze na zdroje ve výzvách.
# Příklad: filtrování založené na metadatech v době dotazu
retriever = index.as_retriever(similarity_top_k=8)
retriever.metadata_filters = {"department": ["legal", "security"], "published": [True]}
Od prototypu k produkci: Vzory nasazení
- Serverový vzor: Zpřístupněte endpoint
/query; udržujte index v paměti.
- Serverless úskalí: Studené starty + velké modely mohou zhoršit latenci; zvažte spravovanou inferenci.
- Caching: Ukládejte do mezipaměti vkládání a časté výsledky dotazů; povolte částečné aktualizace.
- Pozorovatelnost: Protokolujte načtené nody, využití tokenů, délku odpovědí a zpětnou vazbu od uživatelů.
# Minimální 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]}
Plány z reálného světa: Vyberte si svou cestu
- Interní asistent pro zásady
- Index: Hybridní (BM25 + Vektor) s přeřazováním
- Zábrany: Režim pouze ze zdrojů; fallback „Nevím“
- KPI: Míra vyřešení pro dotazy na zásady
- Kopilot zákaznické podpory
- Index: Dokumenty k produktu + poznámky k vydání + tikety
- Agenti: API nástroj pro kontrolu stavu objednávky/tiketu
- KPI: Vyřešení při prvním kontaktu, odklon, CSAT
- Index: Web + PDF + poznámky; silná deduplikace
- Přeřazení: Cross‑encoder; syntéza: map‑reduce
- KPI: Čas k získání přehledu; přesnost citací
- Nástroje: SQL engine + RAG na definicích metrik
- Správa: Zásady na úrovni řádků; audit dotazů
- KPI: Správnost vs. ground truth
Náklady a latence: Udržujte to rychlé (a levné)
- Vkládání: Dávkově, kde je to možné; používejte menší modely pro recall, přeřazujte selektivně.
- Velikost kontextu: Cílem je 1–2k tokenů z nejrelevantnějších bloků.
- Caching: Ukládejte do mezipaměti top‑K načítání pro horké dotazy; memoizujte volání LLM s hashovanými výzvami.
- Paralelismus: Fan‑out načítání → fan‑in přeřazení pro snížení latence ocasu.
Běžná úskalí při učení se, jak používat
- Přílišné rozdělování, které vede k mělkému, hlučnému načítání
- Žádné filtry metadat, které způsobují, že se vloudí irelevantní zdroje
- Spoléhání se na jediný typ indexu pro veškerý obsah
- Přeskočení vyhodnocování; nasazení bez hranice kvality
- Nechání indexů zastarat; žádné plánované obnovení
Mimochodem: Zrychlení pracovního postupu v editoru
Při iteraci výzev, rozdělovačů a nastavení načítání stojí za zmínku, že postranní panel pro kódování a výzkum s umělou inteligencí, jako je Sider.ai, může urychlit smyčku. Můžete mít po ruce úryvky, výzvy a poznámky k vyhodnocování, generovat rozdíly ve změnách výzev a rychle testovat variace, aniž byste opustili prohlížeč. To je zvláště užitečné, když ladíte, jak používat napříč různými strategiemi načítání. Podrobný kontrolní seznam: Od nuly do produkce
- Načtěte zdroje a normalizujte metadata
- Dolaďte velikosti bloků podle typu obsahu
- Vytvořte vektorové + BM25 indexy; povolte hybridní načítání
- Přidejte přeřazování a filtry metadat
- Přizpůsobte výzvy; povolte citace a zásady odmítnutí
- Vyhodnoťte věrnost a relevanci na testovací sadě
- Uložte do vektorového úložiště; povolte inkrementální aktualizace
- Přidejte pozorovatelnost, caching a RBAC filtry
- Zabalte do API a nastavte SLA; dokumentujte režimy selhání
Klíčové poznatky
- Pokud chcete robustní RAG aplikaci, naučení se používat vám ušetří týdny propojovacího inženýrství.
- Začněte jednoduše, poté vrstvěte hybridní načítání, přeřazování a strukturované výzvy.
- Vyhodnoťte před škálováním; uchovávejte indexy a sledujte kvalitu v produkci.
- Navrhujte správu od prvního dne – zabezpečení není dodatečná úprava.
Další kroky
- Vytvořte prototyp rychlého startu na malé sadě dokumentů.
- Experimentujte s hybridním načítáním a přeřazovačem.
- Přidejte vyhodnocování a citace; sledujte metriky kvality.
- Přejděte na trvalé vektorové úložiště a nasaďte API.
FAQ
Q1: K čemu se používá v aplikacích RAG?
vám pomáhá propojit vaše data s LLM pomocí komponent pro příjem, indexování a načítání. Zjednodušuje vytváření systémů RAG tím, že zpracovává rozdělování, vektorové/klíčové indexy a orchestraci dotazů.
Q2: Jak si vyberu správný typ indexu v ?
Použijte vektorový index pro sémantické dotazy, BM25 pro přesné shody, jako jsou ID nebo kódy, a hybridní přístup pro nejlepší celkový recall a precision. Mnoho týmů kombinuje obojí a přidává přeřazování pro top‑K výsledky.
Otázka 3: Jak mohu zlepšit přesnost při používání LlamaIndex?
Upravte velikost chunků, zahrňte bohatá metadata, povolte hybridní vyhledávání a přidejte reranker. Také implementujte hodnocení věrnosti a relevance a použijte citační režim k zobrazení zdrojů.
Otázka 4: Může LlamaIndex pracovat s mou stávající vektorovou databází?
Ano. LlamaIndex se integruje s populárními vektorovými úložišti, jako jsou Pinecone, Weaviate, Chroma, Qdrant a Elasticsearch. Ukládejte indexy pro škálovatelnost a inkrementální aktualizace.
Otázka 5: Jak nasadím aplikaci LlamaIndex do produkčního prostředí?
Zabalte svůj dotazovací engine do API (např. FastAPI), ukládejte data ve vektorovém úložišti, přidejte caching a pozorovatelnost a průběžně vyhodnocujte kvalitu. Zaveďte filtry metadat a řízení přístupu pro zabezpečení.