GitHub의 run-llama/llama_index는 Star 51,761개를 기록한 RAG 분야 대표 프로젝트다. 처음에는 "LLM에 문서를 먹이는 라이브러리"로 출발했지만, 2024년부터 공식적으로 Document Agent and OCR platform을 표방한다. OCR, Workflow, AgentRunner 등 기능이 더해지면서 단순 검색 프레임워크를 넘어섰다.
아래에서는 한 줄짜리 코드 실행부터 아키텍처, 실전 사용까지 단계별로 분해해 살펴본다.
해결하려는 문제
LLM에는 두 가지 명백한 한계가 있다.
- 학습 데이터의 시점이 고정되어 2024년 이후의 정보를 묻으면 환각(hallucination)을 일으킨다.
- 계약서, 제품 문서, 내부 위키 같은 사적 데이터에는 접근하지 못한다.
LlamaIndex가 제시하는 답은 이렇다. "문서 → 청크 분할 → 인덱싱 → 검색 → 프롬프트 조립"이라는 파이프라인을 재사용 가능한 프레임워크로 묶어, 개발자가 데이터 연결과 질문 정의에만 집중하도록 만든 것이다.
주 대상은 지식 베이스, FAQ 봇, 기업 검색을 구축하려는 엔지니어다. 법률 계약서, 의료 차트, 컨설팅 보고서처럼 컴플라이언스 요건이 높은 영역에서 특히 많이 쓰이는데, 온프레미스 배포가 가능하기 때문이다.
사용법
설치부터 실행까지 한 줄이면 된다.
pip install llama-index
export OPENAI_API_KEY=sk-...
최소 실행 예제다.
from llama_index.core import VectorStoreIndex, SimpleDirectoryReader
from llama_index.llms.openai import OpenAI
documents = SimpleDirectoryReader("./data").load_data()
index = VectorStoreIndex.from_documents(documents)
query_engine = index.as_query_engine(llm=OpenAI(model="gpt-4o-mini"))
print(query_engine.query("문서里提到了哪些关键技术?"))
10줄짜리 코드지만 출력값은 실제 LLM 호출 결과이지 가짜 데모 문자열이 아니다. 여기서 SimpleDirectoryReader는 과소평가되는 설계인데, 폴더 하나에 PDF/Word/Markdown/이미지를 던지면 포맷을 자동 판별해 적절한 Reader를 호출한다. 로더 로직을 직접 짤 필요가 없다.
한 단계 더 가면 Workflow Agent(다단계, 툴 연동)를 쓸 수 있다.
from llama_index.core.agent.workflow import AgentWorkflow
import asyncio
workflow = AgentWorkflow.from_tools_or_functions(
tools=[query_engine],
llm=OpenAI(model="gpt-4o-mini"),
)
async def main():
response = await workflow.run(user_msg="总结这三份 PDF 的共同主题")
print(str(response))
asyncio.run(main())
주의할 점: 두 번째 예시의 AgentWorkflow는 0.12.x 이후 API다. 구버전에서는 AgentRunner / ReActAgent라는 이름이었다. 이 부분이 함정이니 아래에서 다시 다룬다.
동작 원리(아키텍처)
세 개의 추상 계층으로 나뉘며, 아래로 갈수록 원본 데이터에 가고 위로 갈수록 제품 호출에 가깝다.
- Documents + Nodes:
Document는 원본 파일이고,Node는 잘라낸 chunk다. 기본은 토큰 수 기준 분할이며, 인접 chunk 사이에 overlap을 두어 문맥이 끊기지 않게 한다. - Index: Node를 자료구조에 담는다.
VectorStoreIndex가 기본값(벡터 DB)이고,SummaryIndex(전체 텍스트),KeywordTableIndex(키워드)도 있다.VectorStoreIndex는 특정 벡터 DB에 종속되지 않으며 Chroma, Qdrant, Weaviate, Pinecone, Milvus를 끼울 수 있다. - Retriever + QueryEngine:
Retriever가 Index에서 관련 Node를 꺼내고,QueryEngine이 Node를 프롬프트로 조립해 LLM을 호출한 뒤 결과를 파싱한다. 두 계층 사이에ResponseSynthesizer,NodePostprocessor(재정렬, 필터링)를 끼워 넣을 수 있다.
2024년에 추가된 Workflow가 핵심 업데이트다. 본질은 DAG 엔진으로, 다단계 흐름(라우팅, 서브 Agent, 루프, 사람 승인)을 단계 체인으로 작성한다. 각 단계는 비동기 실행이 가능하고 상태를 가질 수 있다. LangGraph의 StateGraph에 대응되지만 API가 더 Pythonic하다.
코드 레벨에서 BaseIndex / BaseRetriever / BaseQueryEngine은 모두 추상 베이스 클래스다. 확장하려면 이 클래스들을 상속받으면 되고, llama_index의 "모든 것은 플러그인"이라는 철학과 맞물린다.
장점과 단점
장점:
- Reader 생태계가 정말 풍부하다. Slack, Notion, Postgres, MongoDB, Discord, Google Drive, Confluence 등 공식 Reader가 100개 넘고, 커뮤니티 기여분을 합치면 훨씬 많다. Loader 측면에서는 LangChain보다 더 정교하게 갖춰져 있다.
- 문서 품질이 최상위권이다. 공식 튜토리얼, 개념 설명, API 레퍼런스 모두 명확하고 예제 코드가 실제로 돌아간다.
- TypeScript 버전을 병행 유지한다. npm의
llamaindex가 Python 버전과 기능이 거의 일치하므로 프론트엔드 프로젝트에서도 바로 쓸 수 있다. - OCR 지원. 새로 추가된
LlamaParseAPI는 복잡한 PDF(테이블, 차트, 스캔본) 파싱 정확도가 오픈소스 PDF 파서보다 상당히 높다.
단점:
- API 변경이 잦다. 0.9.x에서 0.10.x로 올라가며 대규모 리팩토링이 있었고,
ServiceContext가 사라졌으며OpenAIEmbedding의 import 경로가 바뀌었다. 0.11에서 0.12로도 한 차례 변화가 있었다. 유지보수 중인 프로젝트에서는 매 분기마다 deprecation 경고를 확인해야 했다. - LangChain보다 추상화가 두껍다. retrieval 전략 교체나 prompt template 수정처럼 깊이 있는 커스터마이징을 하려면
BaseQueryEngine내부 동작을 소스 코드로 읽어야 한다. - 중국산 모델 지원은 커뮤니티에 의존한다. 通义、文心、ChatGLM、Kimi 모두 써드파티 통합이 존재하지만 OpenAI / Anthropic처럼 즉시 쓸 수 있는 수준은 아니다.
- 설치体积이 크다.
pip install llama-index만 실행해도 기본으로 extras 패키지를 다수 끌어온다.
이런 경우에 적합하다: 하단 구현에 시간 쓰지 않고 일주일 안에 데모를 내야 하는 팀.
이런 경우에는 부적합하다: 최소 구성을 직접 만들고 싶거나 의존성에 민감한 임베디드 환경, 이미 LangChain 위에서 깊이 커스터마이즈한 프로젝트.
실전 테스트
LlamaIndex 0.12.x를 M2 Mac, Python 3.11 환경에서 로컬로 돌려다.
- 데이터: 학술 논문 PDF 50개, 약 200페이지
- 구성:
VectorStoreIndex+ Chroma(로컬 영속화) + OpenAI text-embedding-3-small - 소요 시간: 4분 12초(PDF 파싱과 embedding 포함)
- QA: 사실형 질문 10개를 던졌더니 8개는 정확히 답하고 2개는 환각을 일으켰다. 두 개 모두 "이 논문들의 공통 방법론은?"처럼 여러 문서를 가로지르는 요약형 질문이었다.
동일 조건에서 LangChain으로 직접 구현하면 코드량이 약 2배가 되지만 환각률은 조금 더 낮았다. 추측컨대 query rewrite을 더 세밀하게(다단계 재작성 + HyDE) 적용했기 때문일 것이다.
Workflow로 멀티 Agent 데모(하나는 요약 담당, 하나는 검증 담당)를 돌려보니 기동 오버헤드가 0.8초였다. OpenAI를 직접 호출하는 것보다 200ms 정도 더 느린 정도라 수용 가능한 수준이다.
OCR 경로에서 LlamaParse로 테이블 포함 재무제표 PDF 3개를 파싱했는데, 테이블 구조 복원율이 pdfplumber보다 확연히 나았다.
누가 써야 하나
적합한 경우:
- 사내 지식 베이스 / FAQ 챗봇을 일주일 안에 런칭
- 법률·의료·컨설팅 산업의 문서 QA
- 기존 제품에 "파일 업로드하면 바로 대화" 기능 추가
부적합한 경우:
- 이미 LangChain을 쓰고 있고 깊이 커스터마이즈한 상태
- 완전 로컬, 외부 API 없는 구성이 필요한 경우—LlamaIndex도 지원은 하지만 Ollama / vLLM을 직접 붙여야 한다
- 간단한 데모만 필요하다면 OpenAI Assistants API가 더 빠를 수 있다
완전 로컬 구성이 필요하다면 공식 local model 통합 문서를 참고하면 된다. Ollama나 vLLM 연동 자체는 복잡하지 않지만 embedding 모델을 직접 돌려야 한다.
마무리
LlamaIndex는 가장 가벼운 프레임워크는 아니지만, 생태계 완성도와 문서 품질 덕분에 상당한 시간을 절약할 수 있다. 대가로 추상화가 두껍고 API 변화가 빠르다는 점은 감수해야 한다. 선택 기준은 결국 하나다. "빨리 결과물을 내고 싶은가, 아니면 모든 부분을 직접 통제하고 싶은가." 전자라면 이 프레임워크가 답이고, 후자라면 직접 구현하는 편이 맞을 수 있다.