대부분의 RAG(Retrieval-Augmented Generation) 튜토리얼은 다음과 같은 방식으로 시작됩니다: "먼저, 벡터 데이터베이스(Vector Database)를 설치하세요…" 그다음 임베딩 모델(Embedding Models), 청킹 전략(Chunking Strategies), 유사도 임계값(Similarity Thresholds)이 등장합니다. PDF에 대해 질문할 수 있게 될 때쯤이면, 여러분은 이미 세 개의 서비스를 배포하고 200줄의 보일러플레이트(Boilerplate) 코드를 작성한 상태가 됩니다. Garudust Agent는 다른 길을 택합니다. RAG가 내장되어 있으며, trigram 토크나이저(Tokenizer)를 사용하는 SQLite FTS5를 기반으로 작동합니다. 벡터 데이터베이스는 필요 없습니다. 임베딩 API 호출도 필요 없습니다. PDF(또는 TXT, CSV, Markdown, JSON)를 대화창에 넣기만 하면 몇 초 안에 질문을 시작할 수 있습니다.

작동 원리
문서를 입력(Ingest)할 때 Garudust는 다음과 같은 과정을 거칩니다:

1. 텍스트 추출 (외부 도구 없이 네이티브 PDF 파서 사용)
2. 청크(Chunk)로 분할 (800자 이하, 문단 인식 기준)
3. tokenize = 'trigram' 설정을 사용하여 FTS5 가상 테이블에 청크 인덱싱

질문을 하면, doc_search가 인덱스에 대해 전체 텍스트 쿼리(Full-text Query)를 실행하고, 가장 잘 일치하는 상위 청크들을 컨텍스트(Context)로서 LLM(Large Language Model)에 전달합니다. 이것이 전체 파이프라인이며, 모든 것은 ~/.garudust/state.db에 있는 하나의 SQLite 파일로 처리됩니다. trigram 토크나이저를 사용하기 때문에 별도의 토크나이저 설정 없이도 태국어, 중국어, 일본어를 포함한 모든 언어에서 작동합니다.

설정
RAG는 기본적으로 활성화되어 있습니다. 여러분이 설정해야 할 유일한 것은 에이전트가 읽을 수 있도록 허용된 디렉토리입니다:

~/.garudust/config.yaml

security :
allowed_read_paths :
- /home/you/documents
- /data/company-docs

그게 전부입니다. 만약 RAG를 완전히 끄고 싶다면:

disabled_toolsets : [ rag ]

첫 번째 문서 입력하기
CLI를 시작합니다:
garudust

그 다음 에이전트에게 파일을 입력하도록 명령합니다:

사용자: ingest /home/you/documents/employee-handbook.pdf
에이전트: Indexed employee-handbook.pdf — 47 chunks ready for search.

미리보기: "This handbook outlines the policies and procedures for all employees…"

이제 무엇이든 물어보세요:

사용자: What is the remote work policy?
에이전트: According to the employee handbook, remote work is permitted up to 3 days per week for roles that do not require on-site presence. Employees must notify their manager at least 24 hours in advance and maintain availability during core hours (10am–4pm).

4가지 RAG 도구

도구	기능
doc_ingest	파일(PDF, TXT, CSV, MD, JSON…)을 추출하고 인덱싱(Index)합니다.
doc_search	인덱싱된 모든 문서에 대해 전체 텍스트 검색(Full-text search)을 수행합니다.
doc_list	청크(Chunk) 수와 타임스탬프를 포함하여 인덱싱된 모든 문서를 나열합니다.
doc_forget	파일 하나를 삭제하거나 전체 인덱스를 비웁니다.

사용자가 이 도구들을 직접 호출하는 일은 없습니다. 에이전트(Agent)가 사용자의 질문을 바탕으로 언제 사용할지를 스스로 결정합니다. 하지만 이 도구들이 존재한다는 것을 아는 것은 내부적으로 어떤 일이 일어나고 있는지 이해하는 데 도움이 됩니다.

파일 재인덱싱 (Re-ingesting a file)
문서가 변경되었다면, 다시 인덱싱(Ingest)하기만 하면 됩니다. 해당 경로에 대한 기존 인덱스는 자동으로 교체됩니다.

문서 삭제하기 (Forgetting a document)
사용자: 인덱스에서 Q1 보고서를 삭제해줘.
에이전트: 인덱스에서 문서가 삭제되었습니다.

또는 전체를 삭제할 수도 있습니다:
사용자: 인덱싱된 모든 문서를 삭제해줘.
에이전트: 인덱스에서 5개의 문서를 삭제했습니다.

FTS5 쿼리 구문 (FTS5 Query Syntax)

doc_search는 전체 FTS5 구문을 지원하며, 에이전트는 사용자의 질문이 이를 활용할 때 유용하다고 판단되면 자동으로 사용합니다.

구문	예시
AND (기본값)	remote work policy
구문 (Phrase)	"annual leave"
OR	vacation OR leave
NOT	policy NOT contractor
접두사 (Prefix)	terminat*

사용자가 직접 FTS5 쿼리를 작성할 필요는 없습니다. 에이전트가 이를 알아서 처리합니다. 하지만 에이전트를 가이드하고 싶다면 다음과 같이 할 수 있습니다:
사용자: 계약 문서에서 "termination clause"를 검색해줘.

실제 활용 사례 (Real-World Use Cases)

1. 기업 지식 베이스 (Company Knowledge Base)
온보딩 문서, 표준 운영 절차(SOP), 내부 위키(Wiki)를 인덱싱하세요. 신입 팀원들이 Confluence를 뒤지는 대신 일상적인 언어로 질문할 수 있습니다.
사용자: ingest /docs/sop-release-process.md
사용자: 핫픽스(Hotfix)를 운영 환경에 배포하기 전에 어떤 승인이 필요한가요?

2. 계약 및 법률 검토 (Contract and Legal Review)
사용자: ingest /legal/vendor-agreement-2025.pdf
사용자: 이 계약서에 책임 제한(Limitation of liability) 조항이 포함되어 있나요? 한도는 얼마인가요?

3. 로그 분석 (Log Analysis)
로그 파일을 인덱싱하고 grep 패턴을 작성하지 않고도 질문할 수 있습니다:
사용자: ingest /var/log/app/error.log
사용자: 지난 한 시간 동안 어떤 서비스에서 가장 많은 에러가 발생했나요?
사용자: 데이터베이스 연결 타임아웃(Connection timeout)이 발생한 적이 있나요?

4. 코드베이스 문서화 (Codebase Documentation)
사용자: ingest /project/docs/api-reference.md
사용자: /auth/refresh 엔드포인트는 어떤 파라미터(Parameter)를 받나요?

Telegram 또는 LINE을 통해 전송된 파일 수집하기

메시징 플랫폼과 함께 garudust-server를 실행하는 경우, 사용자는 봇에게 직접 파일을 보낼 수 있습니다. 첨부 파일은 자동으로 임시 경로에 저장되며 요청 시 수집(Ingest)될 수 있습니다:

사용자: quarterly-report.pdf (첨부됨) 전송
에이전트(Agent): 파일을 받았습니다. 검색을 위해 인덱싱(Indexing)할까요?
사용자: 네
에이전트(Agent): quarterly-report.pdf 인덱싱 완료 — 83개의 청크(Chunks) 준비됨. 미리보기: "2025년 1분기 재무 요약 — 총 매출: $4.2M…"
사용자: 1분기 매출 총이익(Gross margin)은 얼마였나요?
에이전트(Agent): 보고서에 따르면, 2025년 1분기 매출 총이익은 61.3%로, 2024년 4분기의 58.9%에서 상승했습니다.

플랫폼 첨부 파일(Telegram, LINE, Discord 등에서 온 파일)은 플랫폼 어댑터(Platform adapter)가 /tmp/garudust_*에 파일을 작성하기 때문에, allowed_read_paths 설정과 관계없이 항상 허용됩니다.

여러 문서 동시 처리

여러 파일을 수집하고 동일한 세션 내에서 모든 파일에 걸쳐 검색할 수 있습니다:

사용자: ingest /docs/policy-2024.pdf
사용자: ingest /docs/policy-2025.pdf
사용자: 2024년과 2025년 사이의 출장비 규정(Travel expense policy)에서 무엇이 바뀌었나요?

에이전트는 두 문서를 모두 검색하여 차이점을 종합(Synthesize)합니다.

언제든지 인덱싱된 내용을 확인할 수 있습니다:

사용자: 어떤 문서들이 인덱싱되어 있나요?
에이전트(Agent): 2개의 문서가 인덱싱됨:

• policy-2024.pdf | 34 chunks | 수집일: 2025-05-21 09:14
• policy-2025.pdf | 38 chunks | 수집일: 2025-05-21 09:15

제한 사항

• 시맨틱 검색(Semantic search) 불가 — FTS5는 키워드/트라이그램(Trigram) 매칭 방식이며, 임베딩 유사도(Embedding similarity) 방식이 아닙니다. 문서에 "연차(annual leave)"라고 적혀 있고 사용자가 "휴가 일수(vacation days)"에 대해 묻는 경우, 에이전트는 언어 이해 능력을 통해 이를 연결하지만, 결과는 LLM의 추론 능력에 따라 달라집니다.
• 기본적으로 세션 범위(Session-scoped) 제한 — 인덱스는 state.db에 유지되지만, 검색은 현재 대화 키(Conversation key)로 범위가 제한됩니다. 새로운 세션을 시작하면 동일한 파일을 쿼리하기 위해 다시 수집(Re-ingesting)해야 합니다.
• 텍스트 전용 — PDF 내부의 이미지, 표, 차트는 추출되지 않습니다. 텍스트 콘텐츠만 처리됩니다.

요약

구분	Garudust RAG 방식
접근 방식 (Approach)	설정 한 줄 (One config line)
벡터 데이터베이스 (Vector DB) + 임베딩 API	SQLite (단일 파일) 저장
별도 서비스 (Separate service)	언어 무관 (Any) (trigram)
비용 (Cost)	임베딩 모델에 따라 다름 (Depends on embedding model)
비용 (Cost)	제로 (임베딩 호출 없음) (Zero (no embedding calls))
토큰당 임베딩 비용 (Per-token embedding cost)	FTS5 키워드 + LLM 추론 (FTS5 keyword + LLM reasoning)
검색 유형 (Search type)	의미론적 유사성 (Semantic similarity)

Garudust의 RAG는 대규모 프로덕션 검색을 위한 전용 벡터 검색 파이프라인 (vector search pipeline)을 대체하지는 못할 것입니다. 하지만 별도의 서비스를 실행하지 않고 지금 당장 자신의 문서에 대해 질문하고 싶은 개발자에게는, PDF에서 정답에 도달하는 가장 빠른 경로입니다.

Garudust Agent — GitHub · Releases