LlamaIndex는 LLM 애플리케이션을 위한 데이터 프레임워크입니다. 특히 RAG(Retrieval-Augmented Generation) 파이프라인을 구축할 때, 데이터 수집부터 인덱싱, 검색, 생성까지의 전 과정을 추상화하고 최적화합니다.
PDF, 웹페이지, 데이터베이스, API 등 100+ 소스에서 문서를 로드하고 파싱합니다.
청크 분할, 임베딩, 벡터 저장소 연동을 통해 의미 검색을 수행합니다.
OpenAI, Anthropic, 로컬 모델 등 다양한 LLM과 결합하여 컨텍스트 기반 응답을 생성합니다.
기존 RAG 구현 대비 LlamaIndex의 차별점을 비교합니다.
| 기능 | 직접 구현 (LangChain 등) | LlamaIndex |
|---|---|---|
| 데이터 커넥터 | 수동 구현 필요 | 100+ 내장 리더 |
| 인덱스 전략 | 직접 설계 | 벡터, 트리, 키워드, 그래프 등 6+ 인덱스 |
| 검색 최적화 | 기본 top-k | 하이브리드 검색, reranking, 필터 |
| LLM 호출 | 직접 프롬프트 | 자동 컨텍스트 윈도우, 프롬프트 템플릿 |
| 운영/모니터링 | 부재 | 콜백, 로깅, Observability |
LlamaIndex의 주요 추상화를 이해하는 것이 실무의 첫걸음입니다.
설치부터 첫 RAG 예제까지 5분이면 완료합니다.
pip install llama-index-core llama-index-readers-file llama-index-embeddings-openai llama-index-llms-openai또는 전체 패키지:
pip install llama-index# .env 파일 또는 환경변수
export OPENAI_API_KEY="sk-..."from llama_index.core import VectorStoreIndex, SimpleDirectoryReader
from llama_index.core import Settings
# 임베딩 & LLM 설정 (OpenAI 기본)
Settings.embed_model = "local:BAAI/bge-small-en-v1.5" # 로컬 임베딩
Settings.llm = "openai:gpt-4o-mini"
# 문서 로드
documents = SimpleDirectoryReader("data").load_data()
# 인덱스 생성
index = VectorStoreIndex.from_documents(documents)
# 쿼리 엔진 생성
query_engine = index.as_query_engine()
# 질문
response = query_engine.query("LlamaIndex의 주요 기능은?")
print(response)SimpleDirectoryReader는 PDF, txt, markdown, docx 등을 자동으로 인식합니다. 첫 실행 시 임베딩 모델 다운로드가 진행됩니다.
자주 사용하는 설정 파라미터를 표로 정리했습니다.
| 파라미터 | 기본값 | 설명 |
|---|---|---|
chunk_size | 1024 | Node 분할 크기 (토큰 수) |
chunk_overlap | 200 | 청크 간 중복 토큰 수 |
similarity_top_k | 2 | 검색 시 반환할 상위 노드 수 |
embed_model | text-embedding-ada-002 | 임베딩 모델 (로컬/클라우드) |
llm | gpt-3.5-turbo | 응답 생성 LLM |
response_mode | compact | compact / tree_summarize / refine |
chunk_size를 너무 크게 설정하면 검색 정밀도가 떨어지고, 너무 작으면 컨텍스트가 부족해집니다. 도메인 문서의 평균 문단 길이를 기준으로 설정하세요.
프로덕션 환경에서 자주 마주치는 문제와 해결 방법입니다.
| 문제 | 원인 | 해결책 |
|---|---|---|
| 검색 결과가 부정확함 | 청크 크기/오버랩 부적합 | chunk_size 512~1024, overlap 150~250 조정 |
| LLM 응답이 너무 김 | 컨텍스트 윈도우 초과 | similarity_top_k 줄이기, response_mode='compact' |
| 임베딩 속도 느림 | 로컬 모델 사용 | 배치 처리 또는 API 기반 임베딩으로 전환 |
| 메모리 부족 | 대용량 문서 | 스트리밍 로딩, IngestionPipeline 사용 |
| 벡터 저장소 연결 오류 | 인증/스키마 불일치 | 차원(dimension) 일치 확인, API 키 갱신 |
Settings.callback_manager를 활용하면 각 단계의 latency와 token 사용량을 추적할 수 있습니다. LlamaDebugHandler를 추가해보세요.