LlamaIndex 가이드 | AI DevOps Korea

목차 13개 섹션

가이드 사용법
구조 다이어그램
핵심 아키텍처
고급 인덱싱 전략
하이브리드 검색 & 리랭킹
ReAct Agent
워크플로우
Sub-question 분해
벡터 DB 통합
RAGAS 평가
LlamaIndex 설계
운영 기준
검증 전략

가이드 사용법

읽는 방향

LlamaIndex를 실무 흐름으로 이해하기

LlamaIndex로 고급 RAG 파이프라인, ReAct Agent, 서브쿼리 분해, 하이브리드 검색을 구축합니다. ChromaDB·Pinecone 연동, RAGAS 평가, 프로덕션 배포까지 데이터 중심 AI Agent의 전 과정을 다룹니다. 이 가이드는 개념을 나열하기보다, 실제 프로젝트에서 판단해야 하는 순서대로 내용을 따라갈 수 있게 구성했습니다.

핵심 관점

AI / LLM 시스템

모델과 프롬프트만 보지 않고, 데이터 흐름, 평가, 배포 이후의 운영 지표까지 한 번에 연결해서 봅니다.

고급 RAG 시스템ReAct Agent서브쿼리 분해멀티 벡터 DB

구조 다이어그램

글로 읽은 내용을 머릿속에 오래 남기려면 먼저 흐름을 그림으로 잡는 편이 좋습니다. 아래 두 그림은 LlamaIndex를 학습할 때 계속 되돌아볼 수 있는 기준 지도입니다.

학습 흐름

다이어그램 렌더링 중…

아키텍처 관점

다이어그램 렌더링 중…

핵심 아키텍처

LlamaIndex를 처음 펼칠 때는 세부 명령보다 큰 그림이 먼저입니다. 이 섹션에서는 앞으로 배울 개념들이 어떤 문제를 풀기 위해 등장했는지부터 잡아봅니다.

LlamaIndex는 데이터 수집 → 인덱싱 → 검색 → 생성의 전 과정을 추상화합니다. VectorStoreIndex는 임베딩 기반 의미 검색에, SummaryIndex는 전체 문서 요약에 최적화됩니다. Settings 싱글턴으로 LLM·임베딩 모델을 전역 설정하면 개별 모듈마다 파라미터를 반복할 필요가 없습니다.

PYTHON

from llama_index.core import Settings
from llama_index.llms.openai import OpenAI
from llama_index.embeddings.openai import OpenAIEmbedding

# 전역 설정 — 모든 모듈이 자동으로 참조
Settings.llm = OpenAI(model="gpt-4o", temperature=0.1)
Settings.embed_model = OpenAIEmbedding(model="text-embedding-3-small")
Settings.chunk_size = 512       # 노드 최대 토큰 수
Settings.chunk_overlap = 50     # 청크 간 겹침 (문맥 연속성 유지)

인덱스 유형	특징	적합한 용도
VectorStoreIndex	임베딩 유사도 기반 검색	의미 검색, FAQ, 지식베이스
SummaryIndex	전체 노드 순차 처리	문서 전체 요약, 긴 리포트
KeywordTableIndex	BM25 키워드 매칭	정확한 용어 검색, 법률/의학
KnowledgeGraphIndex	그래프 관계 탐색	엔티티 연결, 다중 홉 질문

고급 인덱싱 전략

여기서는 고급 인덱싱 전략을 실제 코드와 함께 확인합니다. 예제를 그대로 따라 하기보다, 입력과 출력, 그리고 바뀌기 쉬운 부분이 어디인지 보면서 읽어보세요.

단순 고정 크기 청킹은 문장을 끊어 검색 품질을 떨어뜨립니다. Sentence Window는 문장 단위로 인덱싱하되 주변 문장을 윈도우로 묶어 컨텍스트를 유지합니다. Hierarchical(Auto-Merging)은 리프 노드를 검색하고 부모 노드를 반환해 요약과 세부 정보를 동시에 제공합니다. 실무에서는 두 전략을 앙상블하면 가장 높은 RAGAS 점수를 얻습니다.

PYTHON

from llama_index.core.node_parser import (
    SentenceWindowNodeParser,
    HierarchicalNodeParser,
    get_leaf_nodes,
)
from llama_index.core import VectorStoreIndex, StorageContext
from llama_index.core.indices.postprocessor import (
    MetadataReplacementPostProcessor,
    SentenceTransformerRerank,
)

# --- Sentence Window 인덱싱 ---
window_parser = SentenceWindowNodeParser.from_defaults(
    window_size=3,                              # 앞뒤 3문장을 윈도우로
    window_metadata_key="window",
    original_text_metadata_key="original_text",
)
nodes = window_parser.get_nodes_from_documents(documents)
window_index = VectorStoreIndex(nodes)

# 검색 시 윈도우로 텍스트를 교체하는 후처리기
window_query_engine = window_index.as_query_engine(
    node_postprocessors=[
        MetadataReplacementPostProcessor(target_metadata_key="window"),
        SentenceTransformerRerank(top_n=3, model="BAAI/bge-reranker-base"),
    ]
)

하이브리드 검색 & 리랭킹

여기서는 하이브리드 검색 & 리랭킹을 실제 코드와 함께 확인합니다. 예제를 그대로 따라 하기보다, 입력과 출력, 그리고 바뀌기 쉬운 부분이 어디인지 보면서 읽어보세요.

의미 검색(벡터)은 유사 의미 문서를 잘 찾지만 정확한 키워드를 놓치고, BM25(키워드)는 그 반대입니다. QueryFusionRetriever로 두 결과를 RRF(Reciprocal Rank Fusion)로 통합하면 두 강점을 모두 취할 수 있습니다. 이후 CohereRerank로 cross-encoder 재랭킹을 적용하면 top-k 품질이 크게 향상됩니다.

PYTHON

from llama_index.retrievers.bm25 import BM25Retriever
from llama_index.core.retrievers import QueryFusionRetriever
from llama_index.postprocessor.cohere_rerank import CohereRerank

# 벡터 검색기와 BM25 검색기 생성
vector_retriever = index.as_retriever(similarity_top_k=10)
bm25_retriever   = BM25Retriever.from_defaults(nodes=nodes, similarity_top_k=10)

# RRF로 두 검색 결과 융합 + 4개의 쿼리 변형으로 재현율 향상
hybrid_retriever = QueryFusionRetriever(
    [vector_retriever, bm25_retriever],
    similarity_top_k=10,
    num_queries=4,          # 쿼리를 4가지로 변형해 검색
    mode="reciprocal_rerank",
)

# Cohere cross-encoder로 최종 top-3 선택
reranker = CohereRerank(api_key="co_...", top_n=3)

from llama_index.core.query_engine import RetrieverQueryEngine
query_engine = RetrieverQueryEngine(
    retriever=hybrid_retriever,
    node_postprocessors=[reranker],
)

ReAct Agent

여기서는 ReAct Agent을 실제 코드와 함께 확인합니다. 예제를 그대로 따라 하기보다, 입력과 출력, 그리고 바뀌기 쉬운 부분이 어디인지 보면서 읽어보세요.

ReAct(Reasoning + Acting) Agent는 생각 → 행동 → 관찰 루프를 반복해 복잡한 멀티스텝 질문을 해결합니다. QueryEngineTool로 여러 지식 소스를 도구로 등록하면 에이전트가 상황에 맞는 도구를 선택합니다. max_iterations는 무한 루프 방지를 위해 반드시 설정하세요.

PYTHON

from llama_index.core.agent import ReActAgent
from llama_index.core.tools import QueryEngineTool, ToolMetadata

# 지식 소스를 도구로 래핑
knowledge_tool = QueryEngineTool(
    query_engine=query_engine,
    metadata=ToolMetadata(
        name="knowledge_base",
        description="회사 내부 문서, 정책, 절차를 검색합니다. 구체적인 질문을 입력하세요.",
    ),
)

agent = ReActAgent.from_tools(
    [knowledge_tool],
    verbose=True,       # 추론 과정 출력 (디버깅에 필수)
    max_iterations=10,  # 무한 루프 방지
)

# 에이전트가 스스로 검색 → 분석 → 답변 생성
response = agent.chat("분기별 매출 트렌드를 분석하고 이상치를 찾아줘")
print(response)

이벤트 기반 워크플로우

여기서는 이벤트 기반 워크플로우을 실제 코드와 함께 확인합니다. 예제를 그대로 따라 하기보다, 입력과 출력, 그리고 바뀌기 쉬운 부분이 어디인지 보면서 읽어보세요.

Workflow는 비동기 이벤트 그래프로 복잡한 RAG 파이프라인을 명시적으로 모델링합니다. 각 step은 입력 이벤트 타입을 받아 출력 이벤트를 반환하며, 병렬 실행과 조건 분기를 자연스럽게 표현합니다. 기존 체인 방식보다 디버깅과 테스트가 쉽고, 스텝별 관찰이 가능합니다.

PYTHON

from llama_index.core.workflow import (
    Workflow, StartEvent, StopEvent, step, Event
)
from llama_index.core import VectorStoreIndex

class RetrievalEvent(Event):
    """검색 결과를 다음 스텝으로 전달하는 이벤트"""
    nodes: list
    query: str

class RAGWorkflow(Workflow):
    @step
    async def retrieve(self, ev: StartEvent) -> RetrievalEvent:
        """1단계: 쿼리로 관련 문서 검색"""
        retriever = index.as_retriever(similarity_top_k=5)
        nodes = await retriever.aretrieve(ev.query)
        return RetrievalEvent(nodes=nodes, query=ev.query)

    @step
    async def generate(self, ev: RetrievalEvent) -> StopEvent:
        """2단계: 검색된 문서를 바탕으로 LLM 답변 생성"""
        context = "\n".join([n.get_content() for n in ev.nodes])
        response = await Settings.llm.acomplete(
            f"컨텍스트:\n{context}\n\n질문: {ev.query}"
        )
        return StopEvent(result=str(response))

# 워크플로우 실행
wf = RAGWorkflow(timeout=60)
result = await wf.run(query="핵심 내용을 요약해줘")

Sub-question 분해

여기서는 Sub-question 분해을 실제 코드와 함께 확인합니다. 예제를 그대로 따라 하기보다, 입력과 출력, 그리고 바뀌기 쉬운 부분이 어디인지 보면서 읽어보세요.

복잡한 질문은 하나의 검색으로 답하기 어렵습니다. SubQuestionQueryEngine은 LLM이 질문을 여러 서브 질문으로 분해해 각각의 적합한 도구(데이터 소스)에 병렬 질의한 뒤 결과를 통합합니다. 여러 DB나 문서 그룹에 걸친 분석 질문에 매우 효과적입니다.

PYTHON

from llama_index.core.query_engine import SubQuestionQueryEngine
from llama_index.core.tools import QueryEngineTool, ToolMetadata

# 각 데이터 소스를 도구로 등록
tools = [
    QueryEngineTool(
        query_engine=sales_engine,
        metadata=ToolMetadata(
            name="sales_2024",
            description="2024년 월별·분기별 매출 데이터. 금액, 수량, 지역 포함.",
        ),
    ),
    QueryEngineTool(
        query_engine=hr_engine,
        metadata=ToolMetadata(
            name="hr_data",
            description="인사 데이터. 입사일, 부서, 직급, 성과 평가 포함.",
        ),
    ),
]

# LLM이 자동으로 서브 질문을 생성하고 병렬 질의
engine = SubQuestionQueryEngine.from_defaults(
    query_engine_tools=tools,
    verbose=True,  # 생성된 서브 질문 확인
)

# 복합 질문 → 서브 질문 분해 → 통합 답변
response = engine.query("2024년 신규 직원의 성과와 매출 기여도는?")
print(response)

벡터 DB 통합

여기서는 벡터 DB 통합을 실제 코드와 함께 확인합니다. 예제를 그대로 따라 하기보다, 입력과 출력, 그리고 바뀌기 쉬운 부분이 어디인지 보면서 읽어보세요.

메모리 기반 인덱스는 서버 재시작 시 사라집니다. 프로덕션에서는 ChromaDB(로컬/자체 호스팅)나 Pinecone(완전 관리형)을 영구 벡터 스토어로 사용합니다. StorageContext를 통해 LlamaIndex 인덱스와 외부 벡터 DB를 투명하게 연결하며, 기존 컬렉션을 재사용해 재인덱싱 비용을 줄일 수 있습니다.

PYTHON

import chromadb
from llama_index.vector_stores.chroma import ChromaVectorStore
from llama_index.core import StorageContext, VectorStoreIndex

# ChromaDB 영구 클라이언트 생성
chroma_client = chromadb.PersistentClient(path="./chroma_db")
collection = chroma_client.get_or_create_collection(
    name="company_docs",
    metadata={"hnsw:space": "cosine"},  # 코사인 유사도 사용
)

# LlamaIndex 벡터 스토어로 래핑
vector_store = ChromaVectorStore(chroma_collection=collection)
storage_context = StorageContext.from_defaults(vector_store=vector_store)

# 최초 인덱싱 (이후 재시작 시에는 from_vector_store로 로드)
index = VectorStoreIndex.from_documents(
    documents,
    storage_context=storage_context,
    show_progress=True,
)

# 기존 컬렉션 재사용 (재인덱싱 불필요)
index = VectorStoreIndex.from_vector_store(vector_store)

RAGAS 평가

여기서는 RAGAS 평가을 실제 코드와 함께 확인합니다. 예제를 그대로 따라 하기보다, 입력과 출력, 그리고 바뀌기 쉬운 부분이 어디인지 보면서 읽어보세요.

RAG 시스템의 품질은 느낌이 아닌 수치로 측정해야 합니다. RAGAS는 Faithfulness(환각 여부), Answer Relevancy(답변 관련성), Context Recall(중요 정보 검색률) 세 지표로 RAG 파이프라인의 약점을 정량적으로 파악합니다. CI/CD에 통합해 코드 변경 시 품질 회귀를 자동 감지하는 것이 좋습니다.

PYTHON

from ragas import evaluate
from ragas.metrics import faithfulness, answer_relevancy, context_recall
from datasets import Dataset

# 평가 데이터셋 구성 — 최소 50개 이상의 질문-정답 쌍 권장
eval_dataset = Dataset.from_dict({
    "question":     questions,      # 테스트 질문 목록
    "answer":       answers,        # RAG 시스템의 답변
    "contexts":     contexts,       # 검색된 컨텍스트 (리스트의 리스트)
    "ground_truth": ground_truths,  # 참조 정답
})

result = evaluate(
    eval_dataset,
    metrics=[
        faithfulness,       # 답변이 컨텍스트에 근거하는가 (환각 탐지)
        answer_relevancy,   # 답변이 질문과 관련 있는가
        context_recall,     # 정답에 필요한 정보가 컨텍스트에 있는가
    ],
)

df = result.to_pandas()
print(df[["question", "faithfulness", "answer_relevancy", "context_recall"]])
# faithfulness > 0.9, answer_relevancy > 0.85 를 목표로 하세요

LlamaIndex 실무 설계

LlamaIndex 실무 설계은 선택지가 갈리는 지점입니다. 표를 기준으로 각 방법의 쓰임새와 운영상의 차이를 비교해두면 이후 판단이 훨씬 쉬워집니다.

LlamaIndex는 문서 chunking, metadata, index type, retriever 전략이 품질의 대부분을 결정합니다. ingestion 파이프라인과 query pipeline을 분리해야 재색인과 튜닝이 쉽습니다.

결정 지점	확인 질문	실무 기준
경계	LlamaIndex 코드에서 바뀌기 쉬운 부분은 어디인가?	입출력, 설정, 외부 연동, 핵심 규칙을 분리합니다.
상태	상태가 어디서 생성되고 어디서 사라지는가?	상태 소유자와 수명 주기를 코드로 드러냅니다.
장애	실패했을 때 호출자는 무엇을 받는가?	timeout, fallback, error contract를 먼저 정합니다.

LlamaIndex 운영 기준

이 섹션은 LlamaIndex 운영 기준을 실무 관점에서 정리합니다. 개념을 외우기보다, 어떤 상황에서 이 기준을 꺼내 쓸지에 초점을 맞춰보세요.

운영에서는 embedding 비용, index refresh 주기, vector DB latency, top-k 튜닝, reranker 비용을 함께 봐야 합니다.

LlamaIndex 검증 전략

LlamaIndex 검증 전략은 선택지가 갈리는 지점입니다. 표를 기준으로 각 방법의 쓰임새와 운영상의 차이를 비교해두면 이후 판단이 훨씬 쉬워집니다.

검색 품질은 context recall/precision과 citation 정확도를 기준으로 평가해야 합니다.

품질 축	검증 방법	완료 기준
정확성	정상/실패 케이스를 자동화합니다.	핵심 시나리오가 재현 가능하게 통과합니다.
회귀 방지	버그 수정 시 동일 케이스를 테스트로 남깁니다.	같은 장애가 다시 배포되지 않습니다.
운영성	로그, 메트릭, 알림을 확인합니다.	문제가 생겼을 때 원인 추적 경로가 있습니다.

목차 13개 섹션

가이드 사용법
구조 다이어그램
핵심 아키텍처
고급 인덱싱 전략
하이브리드 검색 & 리랭킹
ReAct Agent
워크플로우
Sub-question 분해
벡터 DB 통합
RAGAS 평가
LlamaIndex 설계
운영 기준
검증 전략

가이드 사용법

읽는 방향

LlamaIndex를 실무 흐름으로 이해하기

핵심 관점

AI / LLM 시스템

모델과 프롬프트만 보지 않고, 데이터 흐름, 평가, 배포 이후의 운영 지표까지 한 번에 연결해서 봅니다.

고급 RAG 시스템ReAct Agent서브쿼리 분해멀티 벡터 DB

구조 다이어그램

학습 흐름

다이어그램 렌더링 중…

아키텍처 관점

다이어그램 렌더링 중…

핵심 아키텍처

PYTHON

from llama_index.core import Settings
from llama_index.llms.openai import OpenAI
from llama_index.embeddings.openai import OpenAIEmbedding

# 전역 설정 — 모든 모듈이 자동으로 참조
Settings.llm = OpenAI(model="gpt-4o", temperature=0.1)
Settings.embed_model = OpenAIEmbedding(model="text-embedding-3-small")
Settings.chunk_size = 512       # 노드 최대 토큰 수
Settings.chunk_overlap = 50     # 청크 간 겹침 (문맥 연속성 유지)

인덱스 유형	특징	적합한 용도
VectorStoreIndex	임베딩 유사도 기반 검색	의미 검색, FAQ, 지식베이스
SummaryIndex	전체 노드 순차 처리	문서 전체 요약, 긴 리포트
KeywordTableIndex	BM25 키워드 매칭	정확한 용어 검색, 법률/의학
KnowledgeGraphIndex	그래프 관계 탐색	엔티티 연결, 다중 홉 질문

고급 인덱싱 전략

PYTHON

from llama_index.core.node_parser import (
    SentenceWindowNodeParser,
    HierarchicalNodeParser,
    get_leaf_nodes,
)
from llama_index.core import VectorStoreIndex, StorageContext
from llama_index.core.indices.postprocessor import (
    MetadataReplacementPostProcessor,
    SentenceTransformerRerank,
)

# --- Sentence Window 인덱싱 ---
window_parser = SentenceWindowNodeParser.from_defaults(
    window_size=3,                              # 앞뒤 3문장을 윈도우로
    window_metadata_key="window",
    original_text_metadata_key="original_text",
)
nodes = window_parser.get_nodes_from_documents(documents)
window_index = VectorStoreIndex(nodes)

# 검색 시 윈도우로 텍스트를 교체하는 후처리기
window_query_engine = window_index.as_query_engine(
    node_postprocessors=[
        MetadataReplacementPostProcessor(target_metadata_key="window"),
        SentenceTransformerRerank(top_n=3, model="BAAI/bge-reranker-base"),
    ]
)

하이브리드 검색 & 리랭킹

PYTHON

from llama_index.retrievers.bm25 import BM25Retriever
from llama_index.core.retrievers import QueryFusionRetriever
from llama_index.postprocessor.cohere_rerank import CohereRerank

# 벡터 검색기와 BM25 검색기 생성
vector_retriever = index.as_retriever(similarity_top_k=10)
bm25_retriever   = BM25Retriever.from_defaults(nodes=nodes, similarity_top_k=10)

# RRF로 두 검색 결과 융합 + 4개의 쿼리 변형으로 재현율 향상
hybrid_retriever = QueryFusionRetriever(
    [vector_retriever, bm25_retriever],
    similarity_top_k=10,
    num_queries=4,          # 쿼리를 4가지로 변형해 검색
    mode="reciprocal_rerank",
)

# Cohere cross-encoder로 최종 top-3 선택
reranker = CohereRerank(api_key="co_...", top_n=3)

from llama_index.core.query_engine import RetrieverQueryEngine
query_engine = RetrieverQueryEngine(
    retriever=hybrid_retriever,
    node_postprocessors=[reranker],
)

ReAct Agent

PYTHON

from llama_index.core.agent import ReActAgent
from llama_index.core.tools import QueryEngineTool, ToolMetadata

# 지식 소스를 도구로 래핑
knowledge_tool = QueryEngineTool(
    query_engine=query_engine,
    metadata=ToolMetadata(
        name="knowledge_base",
        description="회사 내부 문서, 정책, 절차를 검색합니다. 구체적인 질문을 입력하세요.",
    ),
)

agent = ReActAgent.from_tools(
    [knowledge_tool],
    verbose=True,       # 추론 과정 출력 (디버깅에 필수)
    max_iterations=10,  # 무한 루프 방지
)

# 에이전트가 스스로 검색 → 분석 → 답변 생성
response = agent.chat("분기별 매출 트렌드를 분석하고 이상치를 찾아줘")
print(response)

이벤트 기반 워크플로우

PYTHON

from llama_index.core.workflow import (
    Workflow, StartEvent, StopEvent, step, Event
)
from llama_index.core import VectorStoreIndex

class RetrievalEvent(Event):
    """검색 결과를 다음 스텝으로 전달하는 이벤트"""
    nodes: list
    query: str

class RAGWorkflow(Workflow):
    @step
    async def retrieve(self, ev: StartEvent) -> RetrievalEvent:
        """1단계: 쿼리로 관련 문서 검색"""
        retriever = index.as_retriever(similarity_top_k=5)
        nodes = await retriever.aretrieve(ev.query)
        return RetrievalEvent(nodes=nodes, query=ev.query)

    @step
    async def generate(self, ev: RetrievalEvent) -> StopEvent:
        """2단계: 검색된 문서를 바탕으로 LLM 답변 생성"""
        context = "\n".join([n.get_content() for n in ev.nodes])
        response = await Settings.llm.acomplete(
            f"컨텍스트:\n{context}\n\n질문: {ev.query}"
        )
        return StopEvent(result=str(response))

# 워크플로우 실행
wf = RAGWorkflow(timeout=60)
result = await wf.run(query="핵심 내용을 요약해줘")

Sub-question 분해

PYTHON

from llama_index.core.query_engine import SubQuestionQueryEngine
from llama_index.core.tools import QueryEngineTool, ToolMetadata

# 각 데이터 소스를 도구로 등록
tools = [
    QueryEngineTool(
        query_engine=sales_engine,
        metadata=ToolMetadata(
            name="sales_2024",
            description="2024년 월별·분기별 매출 데이터. 금액, 수량, 지역 포함.",
        ),
    ),
    QueryEngineTool(
        query_engine=hr_engine,
        metadata=ToolMetadata(
            name="hr_data",
            description="인사 데이터. 입사일, 부서, 직급, 성과 평가 포함.",
        ),
    ),
]

# LLM이 자동으로 서브 질문을 생성하고 병렬 질의
engine = SubQuestionQueryEngine.from_defaults(
    query_engine_tools=tools,
    verbose=True,  # 생성된 서브 질문 확인
)

# 복합 질문 → 서브 질문 분해 → 통합 답변
response = engine.query("2024년 신규 직원의 성과와 매출 기여도는?")
print(response)

벡터 DB 통합

PYTHON

import chromadb
from llama_index.vector_stores.chroma import ChromaVectorStore
from llama_index.core import StorageContext, VectorStoreIndex

# ChromaDB 영구 클라이언트 생성
chroma_client = chromadb.PersistentClient(path="./chroma_db")
collection = chroma_client.get_or_create_collection(
    name="company_docs",
    metadata={"hnsw:space": "cosine"},  # 코사인 유사도 사용
)

# LlamaIndex 벡터 스토어로 래핑
vector_store = ChromaVectorStore(chroma_collection=collection)
storage_context = StorageContext.from_defaults(vector_store=vector_store)

# 최초 인덱싱 (이후 재시작 시에는 from_vector_store로 로드)
index = VectorStoreIndex.from_documents(
    documents,
    storage_context=storage_context,
    show_progress=True,
)

# 기존 컬렉션 재사용 (재인덱싱 불필요)
index = VectorStoreIndex.from_vector_store(vector_store)

RAGAS 평가

PYTHON

from ragas import evaluate
from ragas.metrics import faithfulness, answer_relevancy, context_recall
from datasets import Dataset

# 평가 데이터셋 구성 — 최소 50개 이상의 질문-정답 쌍 권장
eval_dataset = Dataset.from_dict({
    "question":     questions,      # 테스트 질문 목록
    "answer":       answers,        # RAG 시스템의 답변
    "contexts":     contexts,       # 검색된 컨텍스트 (리스트의 리스트)
    "ground_truth": ground_truths,  # 참조 정답
})

result = evaluate(
    eval_dataset,
    metrics=[
        faithfulness,       # 답변이 컨텍스트에 근거하는가 (환각 탐지)
        answer_relevancy,   # 답변이 질문과 관련 있는가
        context_recall,     # 정답에 필요한 정보가 컨텍스트에 있는가
    ],
)

df = result.to_pandas()
print(df[["question", "faithfulness", "answer_relevancy", "context_recall"]])
# faithfulness > 0.9, answer_relevancy > 0.85 를 목표로 하세요

LlamaIndex 실무 설계

LlamaIndex 실무 설계은 선택지가 갈리는 지점입니다. 표를 기준으로 각 방법의 쓰임새와 운영상의 차이를 비교해두면 이후 판단이 훨씬 쉬워집니다.

결정 지점	확인 질문	실무 기준
경계	LlamaIndex 코드에서 바뀌기 쉬운 부분은 어디인가?	입출력, 설정, 외부 연동, 핵심 규칙을 분리합니다.
상태	상태가 어디서 생성되고 어디서 사라지는가?	상태 소유자와 수명 주기를 코드로 드러냅니다.
장애	실패했을 때 호출자는 무엇을 받는가?	timeout, fallback, error contract를 먼저 정합니다.

LlamaIndex 운영 기준

이 섹션은 LlamaIndex 운영 기준을 실무 관점에서 정리합니다. 개념을 외우기보다, 어떤 상황에서 이 기준을 꺼내 쓸지에 초점을 맞춰보세요.

운영에서는 embedding 비용, index refresh 주기, vector DB latency, top-k 튜닝, reranker 비용을 함께 봐야 합니다.

LlamaIndex 검증 전략

LlamaIndex 검증 전략은 선택지가 갈리는 지점입니다. 표를 기준으로 각 방법의 쓰임새와 운영상의 차이를 비교해두면 이후 판단이 훨씬 쉬워집니다.

검색 품질은 context recall/precision과 citation 정확도를 기준으로 평가해야 합니다.

품질 축	검증 방법	완료 기준
정확성	정상/실패 케이스를 자동화합니다.	핵심 시나리오가 재현 가능하게 통과합니다.
회귀 방지	버그 수정 시 동일 케이스를 테스트로 남깁니다.	같은 장애가 다시 배포되지 않습니다.
운영성	로그, 메트릭, 알림을 확인합니다.	문제가 생겼을 때 원인 추적 경로가 있습니다.

LI LlamaIndex 완전 가이드

가이드 사용법

LlamaIndex를 실무 흐름으로 이해하기

AI / LLM 시스템

구조 다이어그램

학습 흐름

아키텍처 관점

핵심 아키텍처

고급 인덱싱 전략

하이브리드 검색 & 리랭킹

ReAct Agent

이벤트 기반 워크플로우

Sub-question 분해

벡터 DB 통합

RAGAS 평가

LlamaIndex 실무 설계

LlamaIndex 운영 기준

LlamaIndex 검증 전략

LI LlamaIndex 완전 가이드

가이드 사용법

LlamaIndex를 실무 흐름으로 이해하기

AI / LLM 시스템

구조 다이어그램

학습 흐름

아키텍처 관점

핵심 아키텍처

고급 인덱싱 전략

하이브리드 검색 & 리랭킹

ReAct Agent

이벤트 기반 워크플로우

Sub-question 분해

벡터 DB 통합

RAGAS 평가

LlamaIndex 실무 설계

LlamaIndex 운영 기준

LlamaIndex 검증 전략