Kako koristiti LlamaIndex: Praktični vodič od nule do produkcije
Ako ste ikada pokušali izgraditi aplikaciju za generiranje obogaćenu dohvaćanjem (RAG) i pomislili: "Zašto je povezivanje ugradnji, vektorskih pohrana i upita tako komplicirano?", niste jedini. LlamaIndex postoji kako bi taj proces bio brz, razuman i spreman za produkciju. U ovom praktičnom, rješenjima usmjerenom vodiču, proći ćemo kroz korištenje LlamaIndexa od početka do kraja – unos podataka, indeksiranje, upite, evaluaciju i implementaciju – tako da možete isporučiti nešto pouzdano bez da se izgubite u povezujućem kodu.
Koristit ćemo strukturu vođenu pitanjima s progresivnim koracima, izvedivim isječcima i savjetima iz stvarnog svijeta. Bez obzira prototipirate li chatbot za interne dokumente ili implementirate pomoćnika za znanje za korisnike, učenje kako učinkovito koristiti LlamaIndex uštedjet će vam dane.
: LlamaIndex je okvir koji vam pomaže povezati vaše podatke s velikim jezičnim modelima pomoću alata za indeksiranje, dohvaćanje i orkestraciju – idealno za RAG, agente i strukturirane izlaze.
Što je LlamaIndex i zašto ga koristiti?
- LlamaIndex je podatkovni okvir za LLM aplikacije. Pruža gradivne blokove za:
- Unos (Ingestion): Učitavanje datoteka, web stranica, baza podataka i API-ja.
- Razbijanje na dijelove i indeksiranje (Chunking & Indexing): Pretvaranje sirovog sadržaja u strukture koje se mogu pretraživati (vektorski, ključni, grafički indeksi).
- Dohvaćanje (Retrieval): Dohvaćanje konteksta s fleksibilnim strategijama (BM25, hibridno, ponovno rangiranje).
- Mehanizmi za upite i agenti (Query Engines & Agents): Sastavljanje dohvaćanja, alata i upita u koherentno QA iskustvo.
- Evaluacija i nadzor (Evaluation & Monitoring): Procjena kvalitete dohvaćanja i relevantnosti odgovora.
- Kada koristiti LlamaIndex:
- Želite robustan RAG sustav bez ponovnog izmišljanja razbijanja na dijelove, ugradnji i dohvaćanja.
- Trebate kombinirati više izvora podataka (PDF-ovi + Notion + SQL).
- Želite eksperimentirati s hibridnim dohvaćanjem, ponovnim rangiranjem ili strukturiranim izlazima.
- Osnovni mentalni model pri učenju kako koristiti LlamaIndex:
- Podaci → Čvorovi (Nodes) → Indeks (Index) → Dohvaćivač (Retriever) → Mehanizam za upite (Query Engine) → Aplikacija (App)
Brzi početak: Minimalna RAG petlja
Ovo je najbrži put do radnog prototipa. Učitat ćemo dokumente, izgraditi vektorski indeks i postavljati pitanja.
# 1) Instalacija
# 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) Konfigurirajte svoj model + ugradnje
os.environ["OPENAI_API_KEY"] = "YOUR_KEY" # ili koristite bilo kojeg podržanog LLM/embedding providera
llm = OpenAI(model="gpt-4o-mini")
embed_model = OpenAIEmbedding(model="text-embedding-3-small")
# 3) Učitavanje dokumenata (npr., ./data/*.pdf, .md, .txt)
docs = SimpleDirectoryReader("./data").load_data
# 4) Izgradnja indeksa
index = VectorStoreIndex.from_documents(docs, embed_model=embed_model)
# 5) Stvaranje mehanizma za upite i postavljanje pitanja
query_engine = index.as_query_engine(llm=llm)
response = query_engine.query("Koje su ključne sigurnosne prakse spomenute u dokumentima?")
print(response)
To je bit. Odavde, stvarne aplikacije dodaju bolje razbijanje na dijelove, ponovno rangiranje, strukturirane upite i mogućnost promatranja.
Unos (Ingestion): Donesite vlastite podatke (BYOD) na pravi način
Kada odlučujete kako koristiti LlamaIndex za stvarne podatke, odaberite učitavače koji odgovaraju vašim izvorima i čuvaju strukturu.
- Datoteke:
SimpleDirectoryReader, čitači PDF/HTML/Markdown
- Web:
BeautifulSoupWebReader, čitači mapa web-mjesta
- SaaS: Notion, Confluence, Slack, Google Drive (putem konektora)
- Baze podataka: SQL i vektorske baze podataka (Pinecone, Weaviate, Chroma, Elasticsearch)
- Savjet: Normalizirajte metapodatke (naslov, autor, URL, created_at). Dobri metapodaci kasnije superpune ponovno rangiranje i filtriranje.
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
Razbijanje na dijelove i raščlanjivači čvorova: Smeće unutra, smeće van
Ispravno razbijanje na dijelove jedan je od najvažnijih koraka pri učenju kako učinkovito koristiti LlamaIndex.
- Zašto je razbijanje na dijelove važno: Preveliko → preopterećenje tokenima i irelevantno dohvaćanje. Premalo → fragmentacija konteksta.
- Zadane vrijednosti: Razumne za mnoge slučajeve, ali prilagodite za svoju vrstu sadržaja.
- Tehnička dokumentacija: dijelovi od 512–1024 tokena s 10–20% preklapanja.
- Česta pitanja: Manji dijelovi (256–512) kako bi se parovi pitanja/odgovora zadržali netaknutima.
- Pravno/Politika: Veći dijelovi (1024–1536) za očuvanje definicija + klauzula.
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)]))
Strategije indeksiranja: Vektorski, ključni ili hibridni?
Odabir pravog indeksa je ključan. Dobra vijest: LlamaIndex vam omogućuje da ih kombinirate.
- Vektorski indeks: Odličan za semantičko pretraživanje. Najbolji za "objasni X" ili nejasne upite.
- Ključni (BM25): Snažan za točne pojmove, ID-ove, kodove pogrešaka, zapise.
- Hibridni: Kombinirajte oboje; ponovno rangirajte najbolje kandidate s LLM-om ili unakrsnim enkoderom.
from llama_index.core import VectorStoreIndex, SummaryIndex
from llama_index.core.retrievers import BM25Retriever
from llama_index.core.query_engine import RetrieverQueryEngine
# Vektorski indeks iz prethodno raščlanjenih čvorova
v_index = VectorStoreIndex(nodes)
# BM25 dohvaćivač ključnih riječi
bm25_retriever = BM25Retriever.from_defaults(nodes=nodes, similarity_top_k=6)
# Hibridni: spajanje kandidata, zatim ponovno rangiranje
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)
Ponovno rangiranje i filtri: Povećajte preciznost bez preplaćivanja
Ponovno rangiranje poboljšava kvalitetu odgovora preuređivanjem dohvaćenih dijelova prema relevantnosti.
- Kada ponovno rangirati: Ako korisnici prijave citate izvan teme ili duge, podstavljene kontekste.
- Unakrsni enkoderi (pretraživanje ugradnje s dva enkodera → ponovno rangiranje s unakrsnim enkoderom)
- Ponovno rangiranje temeljeno na LLM-u (skuplje, ponekad pametnije na nijansiranom tekstu)
- Filtri metapodataka (npr.,
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]
)
Upiti i mehanizmi za upite: Od pretraživanja do odgovora
Mehanizam za upite je mjesto gdje se dohvaćanje susreće s generiranjem. Da biste savladali kako koristiti LlamaIndex u produkciji, pažljivo dizajnirajte upite i sintezu odgovora.
- Strategije sinteze odgovora:
- Jednostavno "stuff" (konkatenacija) za male kontekste
- Stablo ili map-reduce za dulje kontekste
- Način citiranja za prikaz izvora
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("Sažmite korake uvođenja i navedite izvore.")
print(ans)
- Prilagođeni upiti: Prilagodite ton, strukturirane izlaze ili zaštitne ograde.
from llama_index.core.prompts import PromptTemplate
qa_tmpl = PromptTemplate(
"""
Vi ste jezgrovit pomoćnik koji se temelji na dokazima. Koristite samo navedeni kontekst.
Ako niste sigurni, recite da ne znate. Vratite JSON s ključevima: odgovor, izvori.
Pitanje: {query_str}
Kontekst: {context_str}
"""
)
query_engine = v_index.as_query_engine(text_qa_template=qa_tmpl)
Agenti i alati: Kada dohvaćanje nije dovoljno
Ponekad odgovori zahtijevaju radnje: pokretanje SQL-a, pozivanje API-ja ili pregledavanje. LlamaIndex agenti koordiniraju alate i rasuđivanje s vašim cjevovodom za dohvaćanje.
- Slučajevi upotrebe: Nadzorne ploče KPI-ja (SQL alat), botovi za podršku (API za pretraživanje ulaznica), agenti za istraživanje (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("Koliki je bio mjesečni odljev u drugom tromjesečju 2025.? Ako je potrebno, pretražite bazu podataka.")
Evaluacija: Nemojte isporučivati na slijepo
Učenje kako odgovorno koristiti LlamaIndex znači validiranje i dohvaćanja i odgovora prije uvođenja.
- Izvanmrežna evaluacija: Procijenite opoziv/preciznost dohvaćanja na označenom skupu.
- Internetska evaluacija: Zabilježite korisničke upite, izmjerite zadovoljstvo, stope preusmjeravanja i halucinacije.
- Ugrađeno: LlamaIndex pruža pomoćnike za evaluaciju vjernosti i relevantnosti odgovora.
from llama_index.core.evaluation import FaithfulnessEvaluator, RelevancyEvaluator
faith = FaithfulnessEvaluator(llm=llm)
rel = RelevancyEvaluator(llm=llm)
pred = query_engine.query("Navedite obitelji SOC 2 kontrola u našoj politici.")
print("vjerno?", faith.evaluate_response(pred))
print("relevantno?", rel.evaluate_response(pred))
- Praktična granica: Za interne pomoćnike, ciljajte >80% ocjenu "korisno" na vrhunskim upitima prije širokog lansiranja.
Upornost i vektorske pohrane: Učinite ga skalabilnim
Indeksi izgrađeni u memoriji neće biti dovoljni za stvarna opterećenja. Spremite u vektorsku bazu podataka i omogućite inkrementalna ažuriranja.
- Popularni pozadinski sustavi: Pinecone, Weaviate, Chroma, Elasticsearch/OpenSearch, Qdrant.
- Savjet: Koristite prostore imena po stanaru ili odjelu; neka metapodaci budu bogati.
# Primjer: 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)
Sigurnost i upravljanje: Dio koji svi zaboravljaju
- Rukovanje PII: Redigirajte ili hashirajte osjetljiva polja tijekom unosa.
- Kontrole pristupa: Filtrirajte prema korisničkim ulogama s ograničenjima metapodataka.
- Svježina sadržaja: Zakažite ponovni unos; označite verzije.
- Sigurnost: Dodajte pravila odbijanja i ograničenja samo na izvor u upitima.
# Primjer: filtriranje temeljeno na metapodacima u vrijeme upita
retriever = index.as_retriever(similarity_top_k=8)
retriever.metadata_filters = {"department": ["legal", "security"], "published": [True]}
Od prototipa do produkcije: Uzorci implementacije
- Poslužiteljski uzorak: Izložite
/query krajnju točku; održavajte indeks toplim u memoriji.
- Poslužiteljska zamka: Hladni startovi + veliki modeli mogu naštetiti latenciji; razmislite o upravljanom zaključivanju.
- Predmemoriranje (Caching): Predmemorirajte ugradnje i česte rezultate upita; omogućite djelomična ažuriranja.
- Mogućnost promatranja (Observability): Zabilježite dohvaćene čvorove, upotrebu tokena, duljinu odgovora i povratne informacije korisnika.
# Minimalni FastAPI omotač
# 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]}
Nacrti iz stvarnog svijeta: Odaberite svoj put
- Interni pomoćnik za pravila
- Indeks: Hibridni (BM25 + vektorski) s ponovnim rangiranjem
- Zaštitne ograde: Način samo izvora; "Ne znam" povratna opcija
- KPI: Stopa rješavanja pitanja o pravilima
- Kopilot korisničke podrške
- Indeks: Dokumenti o proizvodu + bilješke o izdanju + ulaznice
- Agenti: API alat za provjeru statusa narudžbe/ulaznice
- KPI: Rješavanje prvog kontakta, preusmjeravanje, CSAT
- Indeks: Web + PDF-ovi + bilješke; snažna deduplikacija
- Ponovno rangiranje: Unakrsni enkoder; sinteza: map-reduce
- KPI: Vrijeme do uvida; točnost citata
- Alati: SQL mehanizam + RAG na definicijama metrike
- Upravljanje: Pravila na razini retka; revizija upita
- KPI: Ispravnost u odnosu na temeljnu istinu
Troškovi i latencija: Neka bude brzo (i jeftino)
- Ugradnje: Grupirajte gdje je moguće; koristite manje modele za opoziv, selektivno ponovno rangirajte.
- Veličina konteksta: Ciljajte na 1–2 tisuće tokena najrelevantnijih dijelova.
- Predmemoriranje: Predmemorirajte dohvaćanje top-K za vruće upite; zapamtite LLM pozive s hashiranim upitima.
- Paralelizam: Dohvaćanje s razgranavanjem → ponovno rangiranje s ujedinjavanjem za smanjenje latencije repa.
Uobičajene zamke pri učenju kako koristiti LlamaIndex
- Prekomjerno razbijanje na dijelove, što dovodi do plitkog, bučnog dohvaćanja
- Nema filtara metapodataka, što uzrokuje uvlačenje irelevantnih izvora
- Oslanjanje na jednu vrstu indeksa za sav sadržaj
- Preskakanje evaluacije; isporuka bez granice kvalitete
- Dopuštanje da indeksi zastare; nema zakazanog osvježavanja
Usput: Ubrzavanje vašeg tijeka rada u uređivaču
Dok ponavljate upite, razbijače na dijelove i postavke dohvaćanja, vrijedi napomenuti da bočna traka za AI kodiranje i istraživanje poput Sider.ai može ubrzati petlju. Možete držati isječke, upite i bilješke o evaluaciji pri ruci, generirati razlike u promjenama upita i brzo testirati varijacije bez napuštanja preglednika. Ovo je posebno korisno kada podešavate kako koristiti LlamaIndex u različitim strategijama dohvaćanja. Kontrolni popis korak po korak: Od nule do produkcije
- Unesite izvore i normalizirajte metapodatke
- Podesite veličine dijelova prema vrsti sadržaja
- Izgradite vektorske + BM25 indekse; omogućite hibridno dohvaćanje
- Dodajte ponovno rangiranje i filtre metapodataka
- Prilagodite upite; omogućite citate i pravila odbijanja
- Procijenite vjernost i relevantnost na testnom skupu
- Spremite u vektorsku pohranu; omogućite inkrementalna ažuriranja
- Dodajte mogućnost promatranja, predmemoriranje i RBAC filtre
- Umotajte u API i postavite SLA; dokumentirajte načine kvara
Ključni zaključci
- Ako želite robusnu RAG aplikaciju, učenje kako koristiti LlamaIndex uštedjet će tjedne inženjeringa povezivanja.
- Počnite jednostavno, zatim slojevito hibridno dohvaćanje, ponovno rangiranje i strukturirane upite.
- Procijenite prije nego što skalirate; ustrajte indekse i pratite kvalitetu u produkciji.
- Dizajnirajte za upravljanje od prvog dana – sigurnost nije dodatak.
Sljedeći koraci
- Prototipirajte brzi početak na malom skupu dokumenata.
- Eksperimentirajte s hibridnim dohvaćanjem i ponovnim rangiranjem.
- Dodajte evaluaciju i citate; pratite metrike kvalitete.
- Premjestite se u trajnu vektorsku pohranu i implementirajte API.
Često postavljana pitanja
P1: Za što se LlamaIndex koristi u RAG aplikacijama?
LlamaIndex vam pomaže povezati vaše podatke s LLM-ovima pomoću komponenti za unos, indeksiranje i dohvaćanje. Pojednostavljuje izgradnju RAG sustava rukovanjem razbijanjem na dijelove, vektorskim/ključnim indeksima i orkestracijom upita.
P2: Kako odabrati pravu vrstu indeksa u LlamaIndexu?
Koristite vektorski indeks za semantičke upite, BM25 za točna podudaranja kao što su ID-ovi ili kodovi i hibridni pristup za najbolji ukupni opoziv i preciznost. Mnogi timovi kombiniraju oboje i dodaju ponovno rangiranje za top-K rezultate.
P3: Kako mogu poboljšati točnost pri korištenju LlamaIndexa?
Podesite veličine dijelova teksta (chunk sizes), uključite bogate metapodatke, omogućite hibridno dohvaćanje (hybrid retrieval) i dodajte preuređivač (reranker). Također, implementirajte evaluaciju za vjernost (faithfulness) i relevantnost, te koristite način citiranja (citation mode) za prikaz izvora.
P4: Može li LlamaIndex raditi s mojom postojećom vektorskom bazom podataka?
Da. LlamaIndex se integrira s popularnim vektorskim pohranama kao što su Pinecone, Weaviate, Chroma, Qdrant i Elasticsearch. Spremite indekse za skalabilnost i inkrementalna ažuriranja.
P5: Kako mogu implementirati LlamaIndex aplikaciju u produkciju?
Omotajte svoj mehanizam za upite (query engine) u API (npr. FastAPI), pohranite podatke u vektorsku pohranu, dodajte predmemoriranje (caching) i mogućnost promatranja (observability) te kontinuirano procjenjujte kvalitetu. Primenite filtre metapodataka i kontrolu pristupa radi sigurnosti.