Kuinka käyttää LlamaIndexiä: Käytännön opas aloittelijasta tuotantoon
Jos olet koskaan yrittänyt rakentaa retrieval-augmented generation (RAG) -sovellusta ja miettinyt, "Miksi upotusten, vektorivarastojen ja kehotteiden yhdistäminen on niin hankalaa?", et ole yksin. LlamaIndex on olemassa tehdäkseen tästä prosessista nopean, järkevän ja tuotantovalmiin. Tässä käytännönläheisessä, ratkaisukeskeisessä oppaassa käymme läpi, miten LlamaIndexiä käytetään alusta loppuun – datan tuonnista, indeksoinnista, kyselyistä, arvioinnista ja käyttöönotosta – jotta voit julkaista luotettavan ratkaisun ilman, että eksyt liimauskoodin viidakkoon.
Käytämme kysymyslähtöistä rakennetta, jossa on etenevät vaiheet, suoritettavat koodiesimerkit ja käytännön vinkit. Olitpa sitten prototyypaamassa chatbotia sisäisiin dokumentteihin tai ottamassa käyttöön asiakastukiapuria, LlamaIndexin tehokas käyttö säästää sinulta päiviä työtä.
LlamaIndex on kehys, joka auttaa yhdistämään datasi suuriin kielimalleihin indeksoinnin, haun ja orkestroinnin työkaluilla – ihanteellinen RAG-sovelluksiin, agentteihin ja rakenteellisiin tuloksiin.
Mikä on LlamaIndex ja miksi sitä kannattaa käyttää?
- LlamaIndex on datakehys LLM-sovelluksille. Se tarjoaa rakennuspalikoita:
- Datatuonti: Tuo tiedostoja, verkkosivuja, tietokantoja ja rajapintoja.
- Paloittelu ja indeksointi: Muuta raakasisältö kyseltäviksi rakenteiksi (vektori-, avainsana- tai graafi-indeksit).
- Haku: Hae kontekstia joustavilla strategioilla (BM25, hybridi, uudelleenjärjestely).
- Kyselymoottorit ja agentit: Yhdistä haku, työkalut ja kehotteet johdonmukaiseksi kysymys-vastaus-kokemukseksi.
- Arviointi ja seuranta: Arvioi haun laatua ja vastausten merkityksellisyyttä.
- Milloin käyttää LlamaIndexiä:
- Haluat vankan RAG-pinojärjestelmän ilman, että sinun tarvitsee keksiä paloittelua, upotuksia ja hakua uudelleen.
- Tarvitset useiden datalähteiden yhdistämistä (PDF:t + Notion + SQL).
- Haluat kokeilla hybridi-hakua, uudelleenjärjestelyä tai rakenteellisia tuloksia.
- Keskeinen ajatusmalli LlamaIndexin käytön oppimisessa:
- Data → Solmut → Indeksi → Haku → Kyselymoottori → Sovellus
Pika-aloitus: Minimivaatimukset RAG-silmukalle
Tämä on nopein tapa saada toimiva prototyyppi. Ladataan dokumentit, rakennetaan vektori-indeksi ja esitetään kysymyksiä.
# 1) Asenna
# 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) Määritä mallisi ja upotukset
os.environ["OPENAI_API_KEY"] = "YOUR_KEY" # tai käytä mitä tahansa tuettua LLM-/upotuspalvelua
llm = OpenAI(model="gpt-4o-mini")
embed_model = OpenAIEmbedding(model="text-embedding-3-small")
# 3) Lataa dokumentit (esim. ./data/*.pdf, .md, .txt)
docs = SimpleDirectoryReader("./data").load_data
# 4) Rakenna indeksi
index = VectorStoreIndex.from_documents(docs, embed_model=embed_model)
# 5) Luo kyselymoottori ja esitä kysymys
query_engine = index.as_query_engine(llm=llm)
response = query_engine.query("Mitkä ovat keskeiset tietoturvakäytännöt dokumenteissa?")
print(response)
Siinä on olennaisin. Tästä eteenpäin todelliset sovellukset lisäävät parempaa paloittelua, uudelleenjärjestelyä, rakenteellisia kehotteita ja havainnointia.
Datatuonti: Tuo oma data oikein
Kun päätät, miten käyttää LlamaIndexiä oikean datan kanssa, valitse lataajat, jotka sopivat lähteisiisi ja säilyttävät rakenteen.
- Tiedostot:
SimpleDirectoryReader, PDF/HTML/Markdown-lukijat
- Web:
BeautifulSoupWebReader, sivukarttalukijat
- SaaS: Notion, Confluence, Slack, Google Drive (liitännäisten kautta)
- Tietokannat: SQL ja vektoritietokannat (Pinecone, Weaviate, Chroma, Elasticsearch)
- Vinkki: Normalisoi metatiedot (otsikko, tekijä, URL, luontiaika). Hyvät metatiedot tehostavat myöhempää uudelleenjärjestelyä ja suodatusta.
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
Paloittelu ja solmujen jäsentäjät: Roskaa sisään, roskaa ulos
Oikea paloittelu on yksi tärkeimmistä vaiheista LlamaIndexin tehokkaassa käytössä.
- Miksi paloittelu on tärkeää: Liian iso → tokenien paisuminen ja epäolennaiset haut. Liian pieni → kontekstin pirstoutuminen.
- Oletukset: Kohtuulliset moniin tapauksiin, mutta säädä sisältötyypin mukaan.
- Tekniset dokumentit: 512–1024 tokenin palat 10–20 % päällekkäisyydellä.
- UKK:t: Pienemmät palat (256–512) kysymys-vastaus-parien säilyttämiseksi.
- Oikeudelliset/politiikka: Suuremmat palat (1024–1536) määritelmien ja lausekkeiden säilyttämiseksi.
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)]))
Indeksistrategiat: Vektori, avainsana vai hybridi?
Oikean indeksin valinta on ratkaisevan tärkeää. Hyvä uutinen: LlamaIndex sallii niiden yhdistämisen.
- Vektori-indeksi: Erinomainen semanttiseen hakuun. Paras "selitä X"- tai epätarkkoihin kyselyihin.
- Avainsana (BM25): Vahva tarkkoihin termeihin, tunnisteisiin, virhekoodeihin ja lokitietoihin.
- Hybridi: Yhdistä molemmat; uudelleenjärjestä parhaat ehdokkaat LLM:llä tai ristinkooderilla.
from llama_index.core import VectorStoreIndex, SummaryIndex
from llama_index.core.retrievers import BM25Retriever
from llama_index.core.query_engine import RetrieverQueryEngine
# Vektori-indeksi esijäsennellyistä solmuista
v_index = VectorStoreIndex(nodes)
# BM25-avainsanahaku
bm25_retriever = BM25Retriever.from_defaults(nodes=nodes, similarity_top_k=6)
# Hybridi: yhdistä ehdokkaat, sitten uudelleenjärjestä
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)
Uudelleenjärjestely ja suodattimet: Paranna tarkkuutta ilman ylimääräisiä kustannuksia
Uudelleenjärjestely parantaa vastausten laatua järjestämällä haetut palat uudelleen merkityksellisyyden mukaan.
- Milloin uudelleenjärjestellä: Jos käyttäjät raportoivat epäaiheellisia lähteitä tai pitkiä, täyteyhteyksiä.
- Ristinkooderit (bi-kooderi-haku → ristinkooderi-uudelleenjärjestely)
- LLM-pohjainen uudelleenjärjestely (kalliimpi, joskus älykkäämpi hienovaraisessa tekstissä)
- Metatietosuodattimet (esim.
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]
)
Kehotteet ja kyselymoottorit: Hausta vastauksiin
Kyselymoottori on kohta, jossa haku kohtaa generoinnin. Hallitaksesi LlamaIndexin tuotantokäyttöä, suunnittele kehotteet ja vastausten yhdistäminen huolellisesti.
- Vastausten yhdistämisstrategiat:
- Yksinkertainen “stuff” (ketjuta) pienille konteksteille
- Puu- tai map-reduce-menetelmät pidemmille konteksteille
- Lähdeviitemoodi lähteiden näyttämiseen
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("Tiivistä perehdytysvaiheet ja mainitse lähteet.")
print(ans)
- Räätälöidyt kehotteet: Mukauta sävyä, rakenteellisia tuloksia tai turvarajoja.
from llama_index.core.prompts import PromptTemplate
qa_tmpl = PromptTemplate(
"""
Olet ytimekäs, todisteisiin perustuva avustaja. Käytä vain annettua kontekstia.
Jos et ole varma, sano ettet tiedä. Palauta JSON, jossa avaimet: answer, sources.
Kysymys: {query_str}
Konteksti: {context_str}
"""
)
query_engine = v_index.as_query_engine(text_qa_template=qa_tmpl)
Agentit ja työkalut: Kun haku ei riitä
Joskus vastaukset vaativat toimintoja: SQL-kyselyitä, API-kutsuja tai selaamista. LlamaIndex-agentit koordinoivat työkaluja ja päättelyä hakuputkessasi.
- Käyttötapaukset: KPI-kojelautat (SQL-työkalu), tukibotit (lipun tarkistus-API), tutkimusagentit (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("Mikä oli kuukausittainen churn Q2 2025? Tarvittaessa tee kysely tietokantaan.")
Arviointi: Älä julkaise sokkona
LlamaIndexin vastuullinen käyttö tarkoittaa sekä haun että vastausten validointia ennen käyttöönottoa.
- Offline-arviointi: Arvioi haun kattavuutta ja tarkkuutta merkityllä aineistolla.
- Online-arviointi: Kirjaa käyttäjän kehotteet, mittaa tyytyväisyyttä, ohjausprosentteja ja harhaluuloja.
- Sisäänrakennetut työkalut: LlamaIndex tarjoaa arviointiapuvälineitä uskollisuuden ja vastausten merkityksellisyyden tarkistamiseen.
from llama_index.core.evaluation import FaithfulnessEvaluator, RelevancyEvaluator
faith = FaithfulnessEvaluator(llm=llm)
rel = RelevancyEvaluator(llm=llm)
pred = query_engine.query("Listaa SOC 2 -kontrolliperheet politiikassamme.")
print("uskollinen?", faith.evaluate_response(pred))
print("merkityksellinen?", rel.evaluate_response(pred))
- Käytännön tavoite: Sisäisissä apureissa tähtää yli 80 % “hyödyllinen” -arvioon tärkeimmissä kyselyissä ennen laajaa julkaisua.
Pysyvyys ja vektorivarastot: Tee skaalautuvaksi
Muistissa rakennetut indeksit eivät riitä todellisiin kuormituksiin. Tallenna vektoritietokantaan ja ota käyttöön inkrementaaliset päivitykset.
- Suositut taustajärjestelmät: Pinecone, Weaviate, Chroma, Elasticsearch/OpenSearch, Qdrant.
- Vinkki: Käytä nimialueita vuokralaisittain tai osastoittain; pidä metatiedot rikkaana.
# Esimerkki: 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)
Turvallisuus ja hallinnointi: Se osa, jonka kaikki unohtavat
- Henkilötietojen käsittely: Poista tai hajauta arkaluontoiset kentät datan tuonnin yhteydessä.
- Käyttöoikeudet: Suodata käyttäjäroolien perusteella metatietorajoitteilla.
- Sisällön ajantasaisuus: Ajoita uudelleentuonti; merkitse versiot.
- Turvallisuus: Lisää kieltäytymiskäytännöt ja lähde-rajoitteet kehotteisiin.
# Esimerkki: metatietopohjainen suodatus kyselyhetkellä
retriever = index.as_retriever(similarity_top_k=8)
retriever.metadata_filters = {"department": ["legal", "security"], "published": [True]}
Prototyypistä tuotantoon: Käyttöönoton mallit
- Palvelinmalli: Tarjoa
/query-päätepiste; pidä indeksi lämpimänä muistissa.
- Serverless-haaste: Kylmät käynnistykset ja suuret mallit voivat hidastaa; harkitse hallittua inferenssiä.
- Välimuisti: Välimuistita upotukset ja usein kysytyt tulokset; ota käyttöön osittaiset päivitykset.
- Havainnointi: Kirjaa haetut solmut, tokenien käyttö, vastausten pituus ja käyttäjäpalaute.
# Minimivaatimusten FastAPI-kääre
# 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]}
Todelliset suunnitelmat: Valitse polkusi
- Sisäinen politiikka-avustaja
- Indeksi: Hybridi (BM25 + Vektori) uudelleenjärjestelyllä
- Turvarajat: Lähde-rajoitteinen tila; "En tiedä" -varmistus
- KPI: Ratkaisuprosentti politiikkakysymyksissä
- Indeksi: Tuotedokumentit + julkaisumuistiinpanot + tiketit
- Agentit: API-työkalu tilauksen/tiketin tilan tarkistukseen
- KPI: Ensikontaktin ratkaisu, ohjaus, asiakastyytyväisyys (CSAT)
- Indeksi: Web + PDF:t + muistiinpanot; vahva duplikaattien poisto
- Uudelleenjärjestely: Ristinkooderi; yhdistäminen: map-reduce
- KPI: Aikaan insighttiin; viittauspaikkansapitävyys
- Datan laadunvarmistus BI:lle
- Työkalut: SQL-moottori + RAG mittarimäärittelyissä
- Hallinnointi: Rivitasoiset politiikat; kyselyauditointi
- KPI: Oikeellisuus verrattuna totuuteen
Kustannukset ja viive: Pidä nopeana (ja halpana)
- Upotukset: Tee eräajoja mahdollisuuksien mukaan; käytä pienempiä malleja kattavuuteen, uudelleenjärjestely valikoiden.
- Kontekstin koko: Tavoittele 1–2 tkt tärkeimpiä paloja.
- Välimuisti: Välimuistita top-K-haku kuumille kyselyille; muista LLM-kutsut hajautetuilla kehotteilla.
- Rinnakkaisuus: Haarauta haku → yhdistä uudelleenjärjestely vähentää huippuviivettä.
Yleisiä sudenkuoppia LlamaIndexin käytön oppimisessa
- Liian pienet palat, johtaa pinnalliseen ja meluiseen hakuun
- Ei metatietosuodattimia, jolloin epäolennaiset lähteet pääsevät mukaan
- Yhden indeksityypin varaan luottaminen kaikelle sisällölle
- Arvioinnin ohittaminen; julkaisu ilman laatutavoitetta
- Indeksien vanhentuminen; ei aikataulutettua päivitystä
Muuten: Työskentelynopeuden parantaminen editorissa
Kun säädät kehotteita, paloittelijoita ja hakuasetuksia, AI-koodaus- ja tutkimussivupalkki kuten Sider.ai voi nopeuttaa sykliä. Voit pitää koodipaloja, kehotteita ja arviointimuistiinpanoja helposti saatavilla, luoda eroja kehotemuutoksista ja testata variaatioita nopeasti selaimesta poistumatta. Tämä on erityisen kätevää, kun säädät LlamaIndexin käyttöä eri hakustrategioiden välillä. Vaiheittainen tarkistuslista: Aloittelijasta tuotantoon
- Tuo lähteet ja normalisoi metatiedot
- Säädä palakoot sisältötyypin mukaan
- Rakenna vektori- ja BM25-indeksit; ota hybridi-haku käyttöön
- Lisää uudelleenjärjestely ja metatietosuodattimet
- Mukauta kehotteet; ota käyttöön viittaukset ja kieltäytymiskäytännöt
- Arvioi uskollisuus ja merkityksellisyys testiaineistolla
- Tallenna vektoritietokantaan; ota käyttöön inkrementaaliset päivitykset
- Lisää havainnointi, välimuisti ja RBAC-suodattimet
- Kääri API:ksi ja määritä SLA:t; dokumentoi virhetilanteet
Keskeiset opit
- Jos haluat vankan RAG-sovelluksen, LlamaIndexin oppiminen säästää viikkoja liimauskoodauksessa.
- Aloita yksinkertaisesti, lisää sitten hybridi-haku, uudelleenjärjestely ja rakenteelliset kehoteet.
- Arvioi ennen skaalausta; tallenna indeksit ja seuraa laatua tuotannossa.
- Suunnittele hallinnointi alusta alkaen – turvallisuus ei ole lisäosa.
Seuraavat askeleet
- Prototyypitä pika-aloitus pienellä dokumenttimäärällä.
- Kokeile hybridi-hakua ja uudelleenjärjestelyä.
- Lisää arviointi ja viittaukset; seuraa laatumittareita.
- Siirry pysyvään vektoritietokantaan ja ota käyttöön API.
UKK
K1: Mihin LlamaIndexiä käytetään RAG-sovelluksissa?
LlamaIndex auttaa yhdistämään datasi LLM:iin tuonnin, indeksoinnin ja haun kautta. Se virtaviivaistaa RAG-järjestelmien rakentamista käsittelemällä paloittelun, vektori-/avainsana-indeksit ja kyselyjen orkestroinnin.
K2: Kuinka valitsen oikean indeksityypin LlamaIndexissä?
Käytä vektori-indeksiä semanttisiin kyselyihin, BM25:tä tarkkoihin hakuun kuten tunnisteisiin tai koodeihin, ja hybridiä parhaan kattavuuden ja tarkkuuden saavuttamiseksi. Monet tiimit yhdistävät molemmat ja lisäävät uudelleenjärjestelyn top-K-tuloksille.
K3: Kuinka voin parantaa tarkkuutta käyttäessäni LlamaIndexiä?
Säädä palakokoja, sisällytä monipuolista metadataa, ota käyttöön hybridihaku ja lisää uudelleenjärjestäjä. Ota myös käyttöön arviointi luotettavuuden ja relevanssin varmistamiseksi, ja käytä viittaustilaa lähteiden näyttämiseen.
K4: Voiko LlamaIndex toimia nykyisen vektoritietokantani kanssa?
Kyllä. LlamaIndex integroituu suosittuihin vektoritietokantoihin, kuten Pinecone, Weaviate, Chroma, Qdrant ja Elasticsearch. Säilytä indeksit skaalautuvuuden ja inkrementaalisten päivitysten mahdollistamiseksi.
K5: Kuinka otan LlamaIndex-sovelluksen käyttöön tuotannossa?
Kääri kyselymoottorisi API:in (esim. FastAPI), säilytä tiedot vektoritietokannassa, lisää välimuisti ja observabiliteetti, ja arvioi laatua jatkuvasti. Ota käyttöön metatietosuodattimet ja pääsynvalvonta tietoturvan varmistamiseksi.