Index 시작 가이드: 디렉토리부터 검색까지
Index 시작 가이드: 디렉토리부터 검색까지
문서를 업로드하고, 인덱스를 만들고, 질문하면 답이 나오게 하려면 어떻게 해야 할까요? LlamaCloud의 Index는 이 과정을 세 단계로 단순화한 API예요. 폴더에 문서를 정리하고(디렉토리), 그 위에 인덱스를 만들면 파싱·청킹·임베딩·벡터 저장소 색인이 자동으로 돌아가요. 이후 하이브리드 검색이나 내장 채팅 에이전트로 질의만 하면 되죠.
출처: 공식문서
MCP 호환 에이전트를 쓰고 있다면 SDK 코드 없이도 LlamaParse MCP가 인덱스 검색·파일 작업을 에이전트 도구로 노출해 줘요. 코드를 직접 쓸 필요가 없으니 Claude Code나 Codex에 한 번에 설치하는 방법은 Skills and Plugins 페이지에서 볼 수 있어요.
준비사항
- Starter·Pro·Enterprise 플랜 중 하나가 있는 LlamaCloud 계정
- API 키 — 만드는 법은 문서 참고
SDK 설치
Python, TypeScript, Go, Java, CLI 중 골라서 설치하면 돼요. 이 가이드에서는 Python을 기준으로 보여드릴게요.
pip install llama-cloud>=2.8
from llama_cloud import AsyncLlamaCloud
client = AsyncLlamaCloud(api_key="<your-api-key>")
1단계 — 디렉토리 만들기
디렉토리는 인덱스에 넣을 원본 파일을 담는 컨테이너예요. 문서를 보관하는 폴더라고 생각하면 편해요.
directory = await client.beta.directories.create(
name="my-docs",
description="Product documentation",
)
print(directory.id) # e.g. "dir-abc123"
2단계 — 디렉토리에 파일 업로드
파일을 LlamaCloud에 올린 뒤 디렉토리에 추가해요.
# Upload a file
with open("report.pdf", "rb") as f:
file_obj = await client.files.create(file=f, purpose="user_data")
# Add the file to the directory
await client.beta.directories.files.add(
directory.id,
file_id=file_obj.id,
)
3단계 — 인덱스 만들기
인덱스를 만들면 소스 디렉토리의 모든 파일을 파싱→청킹→임베딩→색인하는 파이프라인이 자동 실행돼요.
index = await client.beta.indexes.create(
source_directory_id=directory.id,
)
print(f"Index ID: {index.id}")
print(f"Status: {index.metadata['status']}")
4단계 — 인덱스 준비 완료까지 대기
인덱스는 비동기로 만들어져요. 상태가 ready가 될 때까지 폴링하세요.
import asyncio
while True:
idx = await client.beta.indexes.get(index.id)
status = idx.metadata["status"] if idx.metadata else "unknown"
if status == "ready":
print("Index is ready!")
break
elif status == "failed":
print("Index build failed:", idx.metadata["error_message"])
break
print(f"Status: {status} -- waiting...")
await asyncio.sleep(2)
5단계 — 검색하기
인덱스가 준비되면 하이브리드 검색 쿼리를 날릴 수 있어요.
results = await client.beta.retrieval.retrieve(
index_id=index.id,
query="What are the key findings?",
top_k=5,
)
for result in results.results:
print(f"Score: {result.score}")
print(result.content[:200])
print("---")
다음 단계
검색 파라미터·필터링·리랭킹은 Retrieval 가이드, 인덱스 안 파일 검색·조회는 File operations, 파일 추가·갱신 후 재동기화는 Syncing 가이드를 따라가면 돼요.