TL;DR
- LlamaIndex 사용법의 뼈대는 셋이다. 문서를 읽고, 검색 가능한 형태로 만들고, 질문이 들어오면 관련 조각을 찾아 모델에 넘긴다.
- 파이썬과 타입스크립트 모두 지원하고 공식 문서는 다섯 줄이면 시작한다고 표기한다.
- 진짜 어려운 건 검색이 아니라 문서 읽기다. 표와 도표가 섞인 PDF에서 이 회사가 별도 제품을 파는 이유가 거기 있다.
LlamaIndex 사용법을 알아보는 상황은 대개 하나다.
회사 문서를 모델이 답할 수 있게 만들고 싶은 것.
매뉴얼이든 계약서든 사내 위키든, 모델은 그 내용을 모르니까 어떻게든 넣어줘야 한다.
이 작업의 이름이 컨텍스트 증강이고, LlamaIndex는 그걸 위한 프레임워크다.
깃허브 별이 5만 개를 넘겼고, 문서 파싱과 워크플로, 에이전트까지 여러 제품군으로 나뉘어 있다.
아래는 개념을 정리하고 첫 검색 에이전트를 만드는 순서, 그리고 실제로 막히는 지점을 공식 문서 기준으로 정리한 것이다.
무엇을 하는 프레임워크인가
공식 문서의 정의는 “데이터 위에서 LLM 기반 에이전트를 만드는 프레임워크”다.
여기서 핵심 개념 두 개를 먼저 잡으면 나머지가 쉬워진다.
컨텍스트 증강은 모델이 모르는 내용을 질문과 함께 넣어주는 방식이다.
모델을 다시 학습시키는 대신 필요한 정보를 그때그때 찾아 붙인다.
흔히 RAG라고 부르는 게 이 방식이다.
워크플로는 단순한 한 번의 검색을 넘어 여러 단계를 거치는 흐름이다.
질문을 다시 쓰고, 여러 곳에서 찾고, 결과를 비교한 뒤 답하는 식의 절차를 코드로 표현한다.
프레임워크 말고 제품군도 함께 있다.
문서를 읽어내는 파서, 가벼운 파서, 워크플로 도구, 에이전트 제품이 각각 있고 관리형 클라우드 서비스로도 제공된다.
LlamaIndex 사용법, 첫 에이전트까지
- 파이썬이나 타입스크립트 중 하나를 고릅니다. 양쪽 다 공식 지원됩니다.
- 패키지를 설치합니다. 문서의 설치 절차를 먼저 따릅니다.
- 모델 API 키를 환경변수로 설정합니다. 기본값이 정해져 있으니 다른 모델을 쓰려면 지정해야 합니다.
- 시작 예제를 그대로 실행해 기본 에이전트가 도는지 확인합니다.
- 문서를 넣습니다. 폴더에서 파일을 읽어오는 것부터 시작합니다.
- 인덱스를 만듭니다. 문서를 조각내고 임베딩해 검색 가능한 형태로 바꾸는 단계입니다.
- 질의를 던져 답이 근거와 함께 나오는지 확인합니다.
- 결과가 부실하면 조각내는 방식과 검색 개수를 조정합니다.
로컬 모델만으로 진행하는 별도 튜토리얼도 문서에 준비돼 있다.
데이터를 외부로 보낼 수 없는 상황이라면 그쪽 경로를 따르면 된다.
결과를 좌우하는 건 문서 읽기다
RAG를 만들어보면 대부분 같은 지점에서 막힌다.
검색이 안 되는 게 아니라 문서가 제대로 안 읽힌 것이다.
깔끔한 텍스트 파일이라면 문제가 없다.
문제는 실제 업무 문서가 그렇지 않다는 데 있다.
표가 여러 페이지에 걸쳐 있고, 도표에 숫자가 들어 있고, 머리말과 꼬리말이 본문과 섞이고, 두 단으로 나뉜 레이아웃이 순서를 흐트러뜨린다.
LlamaIndex가 문서 파싱을 별도 제품으로 파는 이유가 여기 있다.
공개된 기능 목록을 보면 어떤 문제를 다루는지 드러난다.
레이아웃 추출, 멀티모달 파싱, 단어·줄·셀 단위 위치 정보, 표를 표로 읽어내기, 도표를 분석 가능한 형태로 바꾸기, 구조화 출력.
실무 순서로 정리하면 이렇다.
먼저 문서 몇 개를 파싱해 결과 텍스트를 눈으로 본다.
표가 뭉개졌거나 순서가 섞였으면 검색을 아무리 손봐도 답이 좋아지지 않는다.
파싱 품질부터 확보하는 게 순서다.
인덱스를 만들 때 정하는 것
문서를 읽어낸 다음 결정할 항목이 있다.
조각 크기가 첫째다.
너무 잘게 나누면 맥락이 끊겨 답이 단편적이 되고, 크게 잡으면 관련 없는 내용이 함께 딸려와 모델을 헷갈리게 한다.
문서 성격에 따라 다르므로 몇 가지 값으로 시험해보는 편이 낫다.
나누는 기준이 둘째다.
글자 수로 자르는 것보다 제목이나 문단 같은 구조 단위로 자르는 쪽이 대체로 낫다.
매뉴얼처럼 목차가 뚜렷한 문서라면 특히 그렇다.
메타데이터가 셋째다.
각 조각에 출처 문서명과 페이지, 작성일을 붙여두면 답에 근거를 표시할 수 있고, 조건으로 걸러내는 것도 가능해진다.
검색 개수가 넷째다.
몇 조각을 모델에 넘길지다.
많이 넘기면 정확도가 오르는 것처럼 보이지만 비용과 지연이 늘고, 관련 없는 조각이 섞이면 오히려 답이 나빠진다.
워크플로와 에이전트로 넘어가는 지점
한 번 검색해 답하는 구조로 해결되지 않는 질문이 있다. “작년과 올해 매출을 비교해줘” 같은 요청은 두 문서를 각각 찾아 비교하는 절차가 필요하다.
이때 워크플로를 쓴다.
단계를 정의하고 조건에 따라 분기하는 흐름을 코드로 만든다.
에이전트는 그 절차를 모델이 스스로 정하게 하는 방향이다.
공개된 활용 사례를 보면 어떤 문제에 쓰이는지 짐작할 수 있다.
재무 실사, 송장 처리, 기술 문서 검색, 고객 응대 같은 것들이다.
공통점은 문서가 많고 답에 근거가 필요하다는 점이다.
연결 도구도 따로 모여 있다.
각종 데이터 소스에서 읽어오는 커넥터와 리더가 라이브러리로 정리돼 있어서, 노션이나 구글 드라이브 같은 곳에서 문서를 가져오는 코드를 직접 짜지 않아도 된다.
한계와 안 맞는 경우
- 문서가 적고 자주 안 바뀌는 경우. 프롬프트에 그냥 붙이는 게 더 간단하다.
- 정확한 수치를 계산해야 하는 작업. 검색으로 찾아온 텍스트를 모델이 계산하면 오류가 생긴다.
- 파싱이 어려운 문서만 있는 경우. 스캔한 이미지나 복잡한 표가 주력이면 파싱 단계에 비용이 집중된다.
- 추상화를 걷어내고 싶은 경우. 직접 짜는 것보다 층이 하나 늘어난다. 코드로 조립하는 쪽이 편하면 LangChain 사용법 쪽 접근도 함께 본다.
제품 만들 때 가져갈 설계
첫째는 병목을 제품으로 만든 점이다.
RAG에서 실제로 어려운 게 검색이 아니라 문서 읽기라는 걸 알고, 거기에 별도 제품을 세웠다.
프레임워크를 열어두고 가장 어려운 조각을 파는 구조다.
둘째는 문서를 AI 도구에서 바로 열 수 있게 한 방식이다.
각 문서 페이지에 마크다운으로 보기와 코딩 도구에서 열기 버튼이 붙어 있다.
문서를 읽는 주체가 사람만이 아니라는 걸 전제한 설계다.
셋째는 다섯 줄로 시작한다고 명시한 점이다.
프레임워크의 진입 장벽은 개념이 아니라 첫 실행까지의 거리인데, 그 거리를 숫자로 약속했다.
실행 체크리스트
- 다루려는 문서의 형식과 양을 먼저 정리합니다.
- 문서 몇 개를 파싱해 결과 텍스트를 눈으로 확인합니다.
- 표와 순서가 살아 있는지 봅니다. 여기가 무너지면 뒤가 소용없습니다.
- 파이썬이나 타입스크립트 중 하나를 골라 시작 예제를 실행합니다.
- 조각 크기와 나누는 기준을 두세 가지로 시험해 비교합니다.
- 각 조각에 출처와 페이지 메타데이터를 붙입니다.
- 검색 개수를 조정하며 답 품질과 비용을 함께 봅니다.
- 답에 근거를 표시해 사용자가 확인할 수 있게 합니다.
- 여러 단계가 필요한 질문이 많으면 워크플로로 옮깁니다.
자주 묻는 질문
LlamaIndex는 무료인가요
프레임워크는 오픈소스로 공개돼 있습니다.
문서 파싱 같은 관리형 서비스는 별도 요금제가 있고, 모델 API 사용료는 따로 발생합니다.
파이썬만 지원하나요
파이썬과 타입스크립트를 모두 지원합니다.
공식 문서에 두 언어의 시작 예제가 각각 준비돼 있습니다.
로컬 모델로도 만들 수 있나요
로컬 모델만 사용하는 별도 튜토리얼이 문서에 있습니다.
데이터를 외부로 보낼 수 없는 환경이라면 이 경로를 따르면 됩니다.
답이 부정확할 때 무엇부터 봐야 하나요
검색 설정보다 문서 파싱 결과를 먼저 확인하는 것이 순서입니다.
표가 뭉개졌거나 문단 순서가 섞였다면 검색을 손봐도 답이 좋아지지 않습니다.
