[TIL-0216] LlamaIndex란?

🌟 개요

AI Agent 스터디에서 AI Agent 기반의 인플루언서 매칭 플랫폼을 실습 프로젝트로 진행하고 있다. 광고주가 광고 컨셉, 아이템, 예산 등을 입력하면, LangGraph 기반 AI Agent가 DB에서 최적의 인플루언서를 검색하고 추천해주는 서비스이다.

스터디에서는 프로젝트 실습과 병행하여 UC Berkeley의 LLM Agent 강의를 한 강의씩 수강하고 있는데, 이 강의를 통해 LlamaIndex라는 라이브러리를 알게 되었다.

기존 프로젝트는 SQL 기반의 정확 매칭(카테고리명, 플랫폼, 팔로워 수 범위)으로 인플루언서를 검색하고 있었는데, LlamaIndex를 도입하면 자연어 기반 시맨틱 검색과 과거 성공 사례를 근거로 한 RAG 분석이 가능해진다는 점에서 우리 프로젝트에 도입하게 되었다.

프로젝트에 도입한 LlamaIndex 관련 코드들을 분석하기 전에, LlamaIndex가 정확히 무엇이고, 어떤 개념들로 구성되어 있는지 제대로 알아보자.

---

🌟 LlamaIndex란?

LlamaIndex(구 GPT Index)는 LLM 애플리케이션을 위한 데이터 프레임워크이다.
핵심 목적은 외부 데이터를 LLM에 연결하는 것이다.
LLM(GPT-4, Claude 등)은 학습 데이터까지만 알고 있고, 사용자의 개인 데이터(DB, 문서, API 등)는 모른다. LlamaIndex는 이 간극을 메워준다.

---

🌟 왜 필요한가?

문제	LlamaIndex의 해결
LLM은 내 데이터를 모름	외부 데이터를 인덱싱하여 LLM에 제공
문서가 너무 길어 컨텍스트에 안 들어감	청킹 + 임베딩으로 관련 부분만 검색
단순 검색은 의미를 못 잡음	시맨틱 검색(벡터 유사도) 제공
데이터 소스가 다양함	통합 커넥터(PDF, DB, API, 웹 등) 제공

---

🌟 핵심 개념 1: Document & Node

💡 원본 데이터 → Document → Node(청크)

✅ Document

Document는 LlamaIndex에서 원본 데이터 하나를 표현하는 객체이다.
PDF 파일 하나, DB 행 하나, 웹 페이지 하나 등이 각각 하나의 Document가 된다.

💡 Document = text(임베딩 대상, 검색의 기준) + metadata(부가 정보, 필터링용)

• text만 넣기 (가장 기본적인 생성)

  from llama_index.core import Document
  
  doc = Document(text="인플루언서 김철수는 뷰티 카테고리 유튜버입니다.")

  • text에 들어가는 문자열이 나중에 임베딩(벡터 변환)의 대상이 된다.
  • 이 텍스트를 기반으로 유사도를 계산하기 때문에, 검색에 활용하고 싶은 정보는 반드시 text에 포함시켜야 한다.

• metadata를 함께 넣기

  doc = Document(
  	text="인플루언서 김철수는 뷰티 카테고리 유튜버입니다.",
     metadata={
     	"influencer_id": "123",
         "total_followers": 150000,
         "categories": ["뷰티", "라이프스타일"],
     },
  )

  • metadata는 검색 결과와 함께 딸려오는 부가 정보이다.
  • 임베딩에는 사용되지 않지만, 검색 후 필터링이나 결과 표시에 활용된다.
  • 예를 들어 "팔로워 10만 이상만 필터링" 같은 후처리를 metadata로 할 수 있다.

✅ Node와 청킹(Chunking)

실제 데이터는 보통 Document 하나가 매우 길다.
예를 들어 PDF 한 장이 수천 글자일 수 있다. 이걸 통쨰로 임베딩하면 두 가지 문제가 생긴다.

1. 임베딩 모델의 토큰 제한: 대부분의 임베딩 모델은 입력 길이에 제한이 있음 (예: 8192 토큰)
2. 검색 정확도 저하: 문서가 길수록 벡터가 "평균적인" 의미를 갖게 되어, 특정 부분을 정확히 찾기 어려움

그래서 Document를 작은 조각(Node)으로 쪼개는 과정이 필요하다. 이것이 청킹(Chunking)이다.

from llama_index.core.node_parser import SentenceSplitter

parser = SentenceSplitter(chunk_size=512, chunk_overlap=50)
nodes = parser.get_nodes_from_documents([doc])

• chunk_size=512: 한 Node의 최대 토큰 수. 하나의 청크가 최대 512토큰까지 담길 수 있다.

• chunk_overlap=50: 인접한 Node 간에 50토큰을 겹치게 한다.

  • overlap 없이 자르는 경우 (chunk_overlap=0)

    Node 1: "김철수는 뷰티 유튜버이다. 주로 화장품 리뷰를 하며, 특히 스킨케어 제품에 대한 전문성이 높다. 최근에는 LG생활건강과"
    Node 2: "협업하여 큰 성과를 냈다. 해당 캠페인에서 조회수 50만, 좋아요 3만을 달성했다..."

    👉 "LG생활건강과 협업하여 큰 성과를 냈다"라는 문맥이 두 Node로 분리되어 의미가 끊긴다. "LG생활건강과" 검색 시 Node 1에서 걸리지만, 성과 정보는 Node 2에만 있다.

  • overlap 있는 경우 (chunk_overlap=50)

    Node 1: "김철수는 뷰티 유튜버이다. 주로 화장품 리뷰를 하며, 특히 스킨케어 제품에 대한 전문성이 높다. 최근에는 LG생활건강과 협업하여 큰 성과를 냈다."
    Node 2: "최근에는 LG생활건강과 협업하여 큰 성과를 냈다. 해당 캠페인에서 조회수 50만, 좋아요 3만을 달성했다..."

    👉 겹치는 구간 덕분에 문맥이 유지된다.

✅ SentenceSplitter의 동작 방식

SentenceSplitter는 문장 경계를 존중하면서 나누는 도구로, LlamaIndex가 내부적으로 자동 처리해준다.
실제로 VectorStoreIndex.from_documents(documents)를 호출하면, LlamaIndex가 내부적으로 다음 과정을 자동 수행한다.

1. Document를 Node로 분할 (기본값: SentenceSplitter, chunk_size=1024)
2. 각 Node를 임베딩
3. Vector Store에 저장

명시적으로 SentenceSplitter를 직접 쓰는 경우는 기본값(1024토큰)이 아닌 다른 설정을 쓰고 싶을 때이다.
내부적으로 ., !, ?, \n 같은 문장 구분자를 기준으로 분할한 뒤, chunk_size에 맞게 문장들을 묶는다.

• 단순 글자 수로 자르기: "김철수는 뷰티 유튜버이다. 주로 화장" 👈 단어 중간에서 잘림
• SentenceSplitter로 자르기: "김철수는 뷰티 유튜버이다." 👈 문장 단위로 잘림

✅ Node의 구조

생성된 Node는 원본 Document의 정보를 그대로 가지고 있다.

for node in nodes:
	print(node.text)           # 청크 텍스트
    print(node.metadata)       # Document에서 상속받은 메타데이터
    print(node.relationships)  # 이전/다음 Node와의 관계
    print(node.node_id)        # 고유 ID

특히 relationships가 중요하다. Node는 자신의 이전 Node, 다음 Node, 원본 Document에 대한 참조를 유지한다. 덕분에 검색 결과에서 "앞뒤 맥락"을 추적할 수 있다.

✅ 정리: Document에서 검색까지의 전체 흐름

---

🌟 핵심 개념 2: Embedding (임베딩)

✅ 의미

텍스트를 고차원 벡터(숫자 배열)로 변환하는 것이다.

"뷰티 유튜버" → [0.12, -0.34, 0.56, ..., 0.78]  (1536차원)
"화장품 리뷰어" → [0.11, -0.33, 0.55, ..., 0.77]  (비슷한 벡터)
"게임 스트리머" → [-0.45, 0.67, -0.12, ..., 0.23]  (다른 벡터)

의미가 비슷한 텍스트는 벡터 공간에서 가까이 위치한다. 이것이 시맨틱 검색의 원리이다.

✅ 클라우드 API 모델 (OpenAI)

from llama_index.embeddings.openai import OpenAiEmbedding
embed_model = OpenAIEmbedding(model="text-embedding-3-small")

• 텍스트를 OpenAI 서버로 전송하여 임베딩 벡터를 받아옴
• 인터넷 연결 필요
• API 호출마다 비용 발생 (토큰당 과금)
• 내 컴퓨터 성능과 무관하게 빠름
• OPENAI_API_KEY 필요

✅ 로컬 모델 (HuggingFace)

from llama_index.embeddings.huggingface import HuggingFaceEmbedding
embed_model = HuggingFaceEmbedding(model_name="BAAI/bge-small-en-v1.5")

• 모델을 내 컴퓨터에 다운로드받아서 직접 실행
• 인터넷 없이도 동작 (최초 다운로드만 필요)
• 무료
• 내 컴퓨터 CPU/GPU 성능에 의존
• API 키 불필요

---

🌟 핵심 개념 3: Index (인덱스)

Node들을 검색 가능한 구조로 조직하는 것이다. LlamaIndex의 이름이 여기서 왔다.

from llama_index.core import VectorStoreIndex

index = VectorStoreIndex.from_documents(documents)

✅ VectorStoreIndex 동작 원리

Documents → 청킹 → Nodes → 임베딩 → 벡터 저장
                                         ↓
질의 → 질의 임베딩 → 코사인 유사도 계산 → 상위 K개 노드 반환

VectorStoreIndex는 데이터를 저장하는 인덱싱 단계와, 저장된 데이터에서 찾는 검색 단계로 나뉜다.

1단계: 인덱싱 (데이터 저장)

Documents → 청킹 → Nodes → 임베딩 → 벡터 저장

1. Documents 생성

   doc = Document(
   	text="김철수: 뷰티 전문 유튜버. 카테고리: 뷰티, 라이프스타일. 팔로워: 150000명.",
     metadata={"influencer_id": "123", "total_followers": 150000},
   )

   인플루언서 50명이면 Document 50개가 만들어진다.

2. 청킹 → Nodes

   Document 1 ("김철수: 뷰티 전문 유튜버...") → Node 1
   Document 2 ("이영희: 스킨케어 전문...") → Node 2
   Document 3 ("박지민: 메이크업 전문...") → Node 3
   ...

   이 프로젝트에서는 인플루언서 한 명당 텍스트가 짧아서 Document 1개 = Node 1개이다.
   만약 텍스트가 길었다면 Document 1개가 여러 Node로 쪼개진다.

3. 임베딩 (핵심)
   각 Node의 텍스트를 숫자 배열(벡터)로 변환한다. 이게 VectorStoreIndex의 핵심이다.

   Node 1 "김철수: 뷰티 전문 유튜버..."
       ↓ 임베딩 모델 (OpenAI text-embedding-ada-002)
      [0.12, -0.34, 0.56, 0.01, ..., 0.78]   ← 1536차원 벡터
   
   Node 2 "이영희: 스킨케어 전문..."
       ↓ 임베딩 모델
       [0.11, -0.33, 0.55, 0.02, ..., 0.77]   ← 뷰티와 비슷 → 벡터도 비슷!
   
   Node 3 "정민수: 게임 스트리머..."
       ↓ 임베딩 모델
       [-0.45, 0.67, -0.12, 0.89, ..., 0.23]  ← 뷰티와 다름 → 벡터도 다름!

   벡터로 변환하는 이유는, 텍스트끼리는 "의미적 유사도"를 직접 계산할 수 없지만, 벡터끼리는 수학적으로 거리를 계산할 수 있기 때문이다.
   

4. 벡터 저장
   변환된 벡터들을 Vector Store에 저장한다.이 과정이 VectorStoreIndex.from_documents(documents) 한 줄로 전부 실행된다.

2단계: 검색 (질의)

질의 → 질의 임베딩 → 코사인 유사도 계산 → 상위 K개 노드 반환

1. 질의 임베딩
   사용자의 질의도 동일한 임베딩 모델로 벡터로 변환한다.

   "친환경 뷰티 인플루언서 추천해줘"
      ↓ 같은 임베딩 모델
      [0.13, -0.31, 0.54, 0.03, ..., 0.76]   ← 질의 벡터

   같은 모델을 써야 같은 벡터 공간에서 비교할 수 있다. 인덱싱 때 OpenAI 모델을 썼으면, 검색 때도 OpenAI 모델을 써야 한다.

2. 코사인 유사도 계산
   질의 벡터와 저장된 모든 벡터 사이의 코사인 유사도를 계산한다.
   코사인 유사도는 두 벡터가 가리키는 방향이 얼마나 비슷한지를 -1~1 사이 값으로 나타낸 것으로, 1에 가까우면 의미가 비슷하고, 0에 가까우면 관련이 없고, -1에 가까우면 의미가 반대이다.

   질의 벡터: [0.13, -0.31, 0.54, ...]  ("친환경 뷰티 인플루언서 추천해줘")
   
   vs Node 1 [0.12, -0.34, 0.56, ...]  ("김철수: 뷰티 전문 유튜버")
    → 코사인 유사도: 0.94  ✅ 매우 유사!
   
   vs Node 2 [0.11, -0.33, 0.55, ...]  ("이영희: 스킨케어 전문")
    → 코사인 유사도: 0.91  ✅ 유사!
   
   vs Node 3 [-0.45, 0.67, -0.12, ...]  ("정민수: 게임 스트리머")
    → 코사인 유사도: 0.23  ❌ 관련 없음

3. 상위 K개 노드 반환
   유사도 점수가 높은 순서로 정렬하여 상위 K개를 반환한다.

   similarity_top_k=3 이면:
   
   1위: Node 1 (김철수: 뷰티 전문)     유사도: 0.94
   2위: Node 2 (이영희: 스킨케어 전문)  유사도: 0.91
   3위: Node 7 (박지민: 메이크업 전문)  유사도: 0.88
   ─────────────────────────────────────────────
   4위: Node 5 (최수진: 패션 전문)     유사도: 0.72  ← 여기부터 잘림
   ...

✅ 주요 인덱스 유형

인덱스	설명	용도
VectorStoreIndex	벡터 유사도 기반 검색	가장 범용적, 시맨틱 검색
KnowledgeGraphIndex	지식 그래프 구조	엔티티 간 관계 파악
SummaryIndex	전체 문서 요약	문서 전체를 다 읽어야 할 때
TreeIndex	트리 구조 요약	계층적 요약
KeywordTableIndex	키워드 기반 검색	정확한 키워드 매칭

---

🌟 핵심 개념 4: Retriever & Query Engine

이 둘의 차이를 한 마디로 하면, Retriever는 검색만, Query Engine은 검색 + LLM 답변 생성이다.

✅ Retriever: 관련 문서를 찾아오기만 하는 것

retriever = index.as_retriever(similarity_top_k=5)
nodes = retriever.retrieve("뷰티 카테고리 인플루언서 찾아줘")

• 동작 과정
  

• 반환되는 nodes의 형태

  for node in nodes:
  	print(node.get_text())  # "김철수: 뷰티 전문 유튜버. 카테고리: 뷰티, 라이프스타일..."
     print(node.get_score()) # 0.9234 (유사도 점수)
     print(node.metadata)    # {"influender_id": "123", "total_followers": 150000}

• LLM을 전혀 사용하지 않는다. 임베딩 모델로 벡터 유사도만 계산해서 결과를 돌려준다. 그래서 빠르고 비용도 적다.

✅ Query Engine: 검색하고 LLM이 답변까지 생성

query_engine = index.as_query_engine(similarity_top_k=5)
response = query_engine.query("뷰티 카테고리 인플루언서 추천해줘")

• 동작 과정
  

• LLM을 사용하므로, 자연어로 정리된 답변이 나온다.

✅ 같은 질문, 다른 결과

---

🌟 핵심 개념 5: Storage (저장)

✅ 왜 저장이 필요한가?

VectorStoreIndex.from_documents()를 호출하면 내부적으로 모든 Documents에 대해 임베딩 API를 호출한다.

• 인플루언서 50명 인덱싱 시: 임베딩 API 호출 50번 ➡️ 비용 발생 + 시간 소요
• 다음에 앱을 다시 실행하면: 또 50번 호출? ➡️ 돈 낭비 + 시간 낭비

그래서 한 번 만든 인덱스를 디스크에 저장해두고, 다음에는 저장된 것을 로드만 하면 된다. 임베딩 API를 다시 호출할 필요가 없다.

✅ 방법 1: 로컬 파일 저장 (LlamaIndex 기본 제공)

index.storage_context.persist(persist_dir="./storage")

이렇게 하면 ./storage/ 폴더에 JSON 파일들이 생긴다.

./storage/
├── docstore.json          ← Document/Node 원본 텍스트 + 메타데이터
├── index_store.json       ← 인덱스 구조 정보
└── default__vector_store.json  ← 임베딩 벡터값들

따라서 다음 실행 시에는 로드만 하면 된다.

from llama_index.core import StorageContext, load_index_from_storage

storage_context = StorageContext.from_defaults(persist_dir="./storage")
index = load_index_from_storage(storage_context)

• 장점: 별도 DB 설치 없이 바로 사용이 가능하다.
• 단점: 로드 시 모든 벡터를 메모리에 올린다. 따라서 데이터가 수십만 건 이상이면 메모리가 부족하다.

✅ 방법 2: 벡터 DB 연동 (ChromaDB)

import chromadb
from llama_index.vector_stores.chroma import ChromaVectorStore

# chromaDB 클라이언트 생성 (디스크에 영구 저장)
chroma_client = chromadb.PersistentClient(path="./chroma_db")

# 컬렉션 = 벡터를 담는 그룹 (DB의 테이블과 비슷한 개념)
collection = chroma_client.get_or_create_collection("influencer_profiles")

## LlamaIndex가 이 컬렉션을 벡터 저장소로 사용하도록 연결
vector_store = ChromaVectorStore(chroma_collection=collection)

디스크에는 다음과 같은 구조로 저장된다.

./chroma_db/
├── chroma.sqlite3          ← 벡터 + 메타데이터가 SQLite로 저장됨
└── [내부 파일들...]

• 장점: 대용량 데이터 처리가 가능하고, 필요한 벡터만 읽어온다. 검색 최적화가 내장되어 있다.
• 단점: 별도 라이브러리를 설치해야 한다. (pip install chromadb)

✅ 두 방식의 차이

	로컬 파일에 저장	ChromaDB에 저장
저장	index→JSON 파일로 직렬화	index→ChromaDB가 자체 형식으로 저장
로드	JSON 파일 전체를 메모리에 올림	연결만 맺고, 실제 데이터는 검색 시에만 읽음
검색	메모리에서 벡터 비교	ChromaDB가 최적화된 알고리즘으로 벡터 비교

---

🌟 RAG (Retrieval-Augmented Generation)

LlamaIndex의 가장 대표적인 패턴이다.

• RAG가 없으면: LLM이 학습 데이터만으로 답변 (환각 위험)
• RAG가 있으면: 실제 데이터를 근거로 답변 (정확도 향상)

---

🌟 LlamaIndex의 아키텍처 계층

1. Connection Layer (연결 계층)

• 역할: 세상의 모든 데이터를 가져오는 '입구'이다.
• 핵심 요소: Data Loaders (LlamaHub)
• 상세: PDF, Notion, Slack, SQL 데이터베이스 등 흩어져 있는 원본 데이터를 읽어온다. LlamaHub는 수백 개의 데이터 소스를 연결해 주는 일종의 '어댑터 시장'과 같다.

2. Data Layer (데이터 계층)

• 역할: 가져온 데이터를 AI가 처리하게 좋게 '손질'하는 곳이다.
• 핵심 요소: Document, Node, Embedding
• 상세
  • Document: 파일 전체를 담고 있는 큰 단위이다.
  • Node: 문서를 SentenceSplitter 등으로 쪼갠 작은 조각(Chunk)이다. 검색의 최소 단위가 된다.
  • Embedding: 텍스트 조각을 숫자로 변환하여 의미를 부여한다.

3. Index Layer (인덱스 계층)

• 역할: 손질된 데이터를 찾기 쉽게 '정리'하여 저장하는 창고이다.
• 핵심 요소: VectorStore, KG(Knowledge Graph), Summary Index
• 상세
  • VectorStore: ChromaDB처럼 벡터를 저장하고 유사도 검색을 지원한다.
  • KG: 데이터 간의 관계(철수-아빠-영희)를 그래프 형태로 저장한다.
  • Summary Index: 문서 전체의 요약본을 관리한다.

4. Orchestration Layer (오케스트레이션 계층)

• 역할: 질문에 맞는 데이터를 찾고 답변을 만드는 '지휘자'이다.
• 핵심 요소: Retriever, Response Synthesizer
• 상세
  • Retriever: 질문과 가장 관련 있는 노드(Node)를 인덱스에서 찾아온다.
  • Response Synthesizer: 찾아온 노드들과 질문을 합쳐 LLM에게 전달하고, 최종 답변을 조립한다.

5. Application Layer (애플리케이션 계층)

• 역할: 사용자가 실제로 마주하는 '서비스 창구'이다.
• 핵심 요소: Query Engine, Chat Engine, Agent
• 상세
  • Query Engine: 단발성 질문에 답한다. (예: "이 문서 요약해줘")
  • Chat Engine: 대화 맥락을 기억하며 대화한다. (예: "방금 말한 거 더 자세히 알려줘")
  • Agent: 스스로 판단하여 어떤 도구를 쓸지 결정하는 똑똑한 비서이다.

---

🌟 데이터 커넥터 (LlamaHub)

LlamaIndex는 160개 이상의 데이터 소스 커넥터를 제공한다.

• 웹 페이지

  from llama_index.readers.web import SimpleWebPageReader

• PDF

  from llama_index.readers.file import PDFReader

• 데이터베이스

  from llama_index.readers.database import DatabaseReader

• CSV

  from llama_index.readers.file import CSVReader

이 밖에도 Notion, Slack, Google Docs 등 수십 가지이다.

---

🌟 LlamaIndex vs. LangChain

항목	LlamaIndex	LangChain
핵심 목적	데이터 인덱싱 & 검색 (RAG)	LLM 애플리케이션 오케스트레이션
강점	다양한 인덱스, 임베딩, 검색 최적화	Agent, Chain, 도구 연결
이 프로젝트에서	벡터 검색, KG 인덱스	Agent 오케스트레이션 (LangGraph)
비유	도서관 사서 (데이터를 정리하고 찾아줌)	프로젝트 매니저 (작업을 연결하고 조율)