로컬 RAG 기반 범용 문서 검색 서비스 MVP 기획서¶

1. 개요¶

이 프로젝트는 사용자가 보유한 내부 문서, 매뉴얼, 리포트, 지식 파일을 로컬에서 색인하고, 외부 또는 로컬 LLM을 선택해 자연어로 질의응답할 수 있는 범용 RAG 서비스의 MVP를 만든다.

핵심 목표는 특정 산업 하나에 종속된 챗봇이 아니라, 산업 문서, 게임 설정 자료, 제품 매뉴얼, 의료/연구 문헌, 사내 정책, 기술 문서 등 다양한 문서 기반 지식에 적용 가능한 일반형 정보 검색기를 만드는 것이다.

MVP의 핵심 원칙은 다음과 같다.

문서 원본, 메타데이터, 벡터 인덱스는 기본적으로 로컬에 둔다.
외부 LLM에는 전체 문서가 아니라 검색된 일부 근거 문맥만 전달한다.
모든 답변은 출처, 파일명, 페이지/섹션, 근거 스니펫을 함께 보여준다.
답을 만들 수 없는 경우에는 추측하지 않고 "문서에서 근거를 찾지 못함"을 반환한다.
LLM 제공자는 교체 가능해야 한다. OpenAI, Anthropic, Google, 로컬 모델 등을 같은 인터페이스로 다룬다.
도메인별 차이는 코드 분기가 아니라 도메인 프로필과 메타데이터 설정으로 흡수한다.

2. 문제 정의¶

개인과 조직은 많은 문서를 보유하지만, 실제 업무에서는 필요한 정보를 빠르게 찾기 어렵다.

문서가 PDF, Word, Markdown, CSV, 이미지 등 여러 형식으로 흩어져 있다.
키워드 검색만으로는 사용자의 의도와 문맥을 충분히 반영하기 어렵다.
외부 LLM은 강력하지만 내부 문서 내용을 알지 못한다.
내부 문서를 통째로 외부 서비스에 올리는 것은 보안과 컴플라이언스 리스크가 있다.
산업별 문서 구조는 다르지만, "문서에서 근거를 찾아 요약/응답한다"는 기본 문제는 동일하다.

따라서 로컬 문서를 안전하게 색인하고, LLM을 지식 생성 계층으로만 사용하는 범용 RAG 시스템이 필요하다.

3. 제품 비전¶

사용자는 문서를 넣고, 질문하고, 근거가 붙은 답을 받는다.

장기적으로는 다음과 같은 형태를 목표로 한다.

개인용 로컬 지식 검색기
팀 단위 내부 문서 QA 시스템
산업별 지식베이스 어시스턴트
제품/설비 매뉴얼 기반 트러블슈팅 도우미
연구/의료/법률/게임/교육 도메인용 문서 기반 질의응답 엔진

MVP에서는 "범용성의 골격"을 검증한다. 즉, 특정 도메인에 맞춘 완성형 제품보다, 여러 도메인 문서를 동일한 파이프라인으로 수집, 색인, 검색, 응답할 수 있는 기본 구조를 우선 만든다.

4. 대상 사용자¶

4.1 1차 사용자¶

본인의 문서 묶음에서 빠르게 정보를 찾고 싶은 개인 사용자
사내 매뉴얼, 정책, 기술 문서에서 답을 찾아야 하는 실무자
도메인 자료를 기반으로 QA 시스템을 빠르게 검증하려는 개발자/기획자

4.2 확장 사용자¶

제조/설비 매뉴얼 기반 현장 지원 담당자
게임 세계관, 퀘스트, 아이템, 운영 정책을 검색하려는 게임팀
의료/연구 문헌을 정리하고 근거 중심으로 탐색하려는 전문가
교육 자료, 강의록, 교재를 검색하려는 강사/학습자

5. MVP 목표¶

MVP의 목표는 "로컬 문서 기반 RAG 질의응답이 실제로 쓸 만한지"를 검증하는 것이다.

5.1 반드시 제공할 기능¶

로컬 문서 업로드 또는 폴더 등록
문서 파싱 및 텍스트 추출
청킹, 임베딩, 벡터 인덱싱
자연어 질의 입력
관련 문서 조각 검색
선택한 LLM을 통한 답변 생성
출처와 근거 스니펫 표시
기본 대화 히스토리 저장
문서 재색인
LLM 제공자 설정 분리
검색 품질을 확인할 수 있는 샘플 질문/정답 평가 파일

5.2 MVP에서 제외할 기능¶

복잡한 조직 권한 관리
다중 사용자 실시간 협업
완전한 의료/법률 판단 자동화
모든 파일 형식 완전 지원
파인튜닝 기반 모델 학습
대규모 엔터프라이즈 검색 클러스터
고급 워크플로 자동화 에이전트

6. 핵심 사용자 시나리오¶

시나리오 1: 문서 묶음 등록¶

사용자는 특정 폴더 또는 파일 묶음을 등록한다. 시스템은 지원 가능한 파일을 파싱하고, 문서 단위 메타데이터를 생성한 뒤, 검색 가능한 인덱스로 변환한다.

성공 기준:

사용자는 등록된 문서 수와 색인 상태를 확인할 수 있다.
실패한 문서는 실패 이유를 확인할 수 있다.
재색인 버튼으로 문서 변경 사항을 반영할 수 있다.

시나리오 2: 문서 기반 질문¶

사용자는 "이 장비의 오류 코드 E37은 무엇을 의미해?"처럼 자연어로 질문한다. 시스템은 관련 문서 조각을 검색하고, LLM에 근거 문맥을 전달해 답변을 생성한다.

성공 기준:

답변에는 최소 1개 이상의 출처가 붙는다.
출처에는 파일명, 페이지 또는 섹션, 스니펫이 포함된다.
문서에서 근거를 찾지 못하면 답변 생성을 중단하고 근거 부족을 알린다.

시나리오 3: LLM 제공자 교체¶

사용자는 동일한 인덱스를 유지한 채 LLM 제공자를 바꿔 응답 품질과 비용을 비교한다.

성공 기준:

LLM 제공자는 설정 파일 또는 UI에서 교체할 수 있다.
검색 파이프라인은 LLM 제공자에 종속되지 않는다.
동일 질문에 대해 제공자별 응답과 지연 시간을 비교할 수 있다.

시나리오 4: 도메인 프로필 적용¶

사용자는 "매뉴얼", "의료 문헌", "게임 기획서" 등 도메인 프로필을 선택한다. 시스템은 답변 형식, 금지 사항, 메타데이터 우선순위, 용어 사전 등을 프로필에 따라 조정한다.

성공 기준:

도메인 프로필은 코드 수정 없이 설정 파일로 추가할 수 있다.
프로필은 검색 필터, 답변 템플릿, 안전 정책을 포함한다.

7. 제품 구조¶

사용자 문서
  ↓
문서 수집기
  ↓
파서 / 텍스트 추출기
  ↓
정규화 / 메타데이터 생성
  ↓
청킹
  ↓
임베딩 생성
  ↓
로컬 벡터 DB + 메타데이터 DB
  ↓
검색 / 재랭킹
  ↓
프롬프트 구성
  ↓
LLM 제공자 어댑터
  ↓
근거 포함 답변

8. 추천 MVP 기술 스택¶

현재 저장소는 초기 상태이므로, MVP에는 단순하고 검증하기 쉬운 구성을 권장한다.

8.1 백엔드¶

Python
FastAPI
SQLite
Chroma 또는 Qdrant Local
문서 파싱: PDF, Markdown, TXT, DOCX 우선
환경 설정: .env

8.2 프론트엔드¶

MVP 초기에는 빠른 검증을 위해 둘 중 하나를 선택한다.

Streamlit: 가장 빠른 프로토타입 검증
Next.js: 이후 제품화 UI까지 고려할 때 적합

초기 MVP에서는 Streamlit 또는 간단한 웹 UI로 시작하고, 검색 품질이 검증된 뒤 제품형 UI로 확장하는 것이 현실적이다.

8.3 LLM/임베딩 추상화¶

LLM과 임베딩 모델은 직접 코드에 고정하지 않고 어댑터 인터페이스로 분리한다.

LLMProvider
  - generate(prompt, context, options) -> Answer

EmbeddingProvider
  - embed(texts) -> vectors

이 구조를 사용하면 외부 LLM과 로컬 LLM을 같은 방식으로 다룰 수 있다.

9. 핵심 모듈¶

9.1 Document Ingestion¶

역할:

파일 또는 폴더 등록
지원 파일 형식 감지
파일 해시 계산
변경 여부 판단
문서 상태 관리

MVP 지원 형식:

.pdf
.md
.txt
.docx
.csv

추후 확장:

.html
.pptx
이미지 OCR
웹페이지 크롤링
Notion, Google Drive, SharePoint 같은 외부 저장소 연동

9.2 Parser¶

역할:

원본 파일에서 텍스트 추출
페이지, 제목, 섹션, 표 등 가능한 구조 정보 보존
파싱 실패 로그 저장

품질 기준:

파싱 결과에는 원본 파일 경로와 위치 정보가 남아야 한다.
표와 목록은 의미가 깨지지 않도록 텍스트화한다.
비어 있는 페이지, 반복 헤더/푸터는 가능한 제거한다.

9.3 Chunking¶

역할:

긴 문서를 검색 가능한 조각으로 나눈다.
조각마다 문서 ID, 페이지, 섹션, 제목, 태그를 연결한다.

기본 전략:

섹션 단위 우선
섹션이 없으면 토큰 길이 기준 분할
앞뒤 문맥 유지를 위한 overlap 적용

MVP 기본값:

chunk size: 600~1,000 tokens
overlap: 80~150 tokens
heading, page number, source path 메타데이터 보존

9.4 Embedding & Vector Index¶

역할:

청크를 임베딩 벡터로 변환
로컬 벡터 DB에 저장
질의 임베딩과 유사한 청크 검색

요구사항:

임베딩 모델은 설정으로 교체 가능해야 한다.
동일 문서가 변경되지 않았으면 재임베딩하지 않는다.
검색 결과는 점수와 메타데이터를 함께 반환한다.

9.5 Retrieval¶

역할:

사용자 질문에서 관련 문서 조각을 찾는다.
벡터 검색, 키워드 검색, 메타데이터 필터를 조합할 수 있게 한다.

MVP 검색 방식:

벡터 검색 top-k
선택적 키워드 검색
중복 청크 제거
출처 다양성 보장

추후 고도화:

BM25 + vector hybrid search
cross-encoder reranker
query expansion
multi-hop retrieval
temporal/document-version filtering

9.6 Answer Generation¶

역할:

검색된 근거를 LLM 프롬프트에 구성
출처 기반 답변 생성
근거 없는 주장 방지
답변과 인용 정보 구조화

기본 답변 정책:

문서 근거 안에서만 답한다.
확실하지 않으면 불확실성을 표시한다.
문서에 없는 외부 지식은 사용하지 않는다.
사용자가 명시적으로 요청하지 않는 한 추론 범위를 넓히지 않는다.

권장 응답 구조:

요약 답변
근거
- 파일명 / 페이지 또는 섹션 / 관련 문장
추가로 확인할 문서
불확실한 점

9.7 LLM Provider Router¶

역할:

여러 LLM 제공자를 동일 인터페이스로 연결
모델명, 온도, 최대 토큰, 비용 정책 관리
실패 시 대체 모델 사용 여부 제어

MVP 요구사항:

provider별 API key는 .env에 저장한다.
답변 요청마다 사용 provider와 model을 기록한다.
provider 장애 시 명확한 오류 메시지를 반환한다.

지원 후보:

OpenAI
Anthropic
Google
로컬 Ollama 계열 모델

특정 모델명과 가격은 변동 가능성이 크므로 구현 시점에 공식 문서 기준으로 확정한다.

10. 도메인 일반화 전략¶

범용성을 확보하려면 도메인별 기능을 코드에 하드코딩하지 않아야 한다.

10.1 Domain Profile¶

도메인 프로필은 다음 정보를 가진 설정 단위다.

name: equipment-manual
description: 제품/설비 매뉴얼 검색
metadata_priority:
  - product_name
  - model_name
  - error_code
  - page
answer_style:
  format: troubleshooting
  include_steps: true
safety_policy:
  require_citation: true
  no_unsupported_advice: true
synonyms:
  error: ["fault", "alarm", "code"]

예상 프로필:

general
manual
medical-literature
legal-document
game-design
research-paper
internal-policy

10.2 공통 메타데이터¶

모든 도메인에서 공통으로 사용할 최소 메타데이터를 정의한다.

document_id
source_path
file_name
file_type
title
author
created_at
updated_at
indexed_at
page
section
tags
domain
language
chunk_id
chunk_text
hash

도메인별 메타데이터는 확장 필드로 둔다.

manual: product_name, model_name, error_code
medical: disease, drug, population, study_type
game: character, item, quest, patch_version
legal: jurisdiction, clause, effective_date

11. 보안 및 프라이버시 원칙¶

로컬 RAG의 차별점은 문서 전체를 외부로 보내지 않는 것이다.

MVP 보안 원칙:

원본 문서는 로컬에 저장한다.
외부 LLM에는 검색된 청크만 보낸다.
사용자가 선택한 provider와 model을 명확히 표시한다.
API key는 코드와 저장소에 포함하지 않는다.
질의/응답 로그 저장 여부를 설정할 수 있게 한다.
민감 문서 사용 시 외부 LLM 전송 경고를 제공한다.

추후 보안 확장:

로컬 LLM 전용 모드
PII 탐지 및 마스킹
문서별 접근 권한
감사 로그
암호화 저장
air-gapped 배포

12. 의료/법률 등 고위험 도메인 방침¶

이 시스템은 범용 정보 검색기이며, 의료 진단이나 법률 판단을 자동으로 대체하지 않는다.

고위험 도메인에서는 다음 정책을 적용한다.

답변은 반드시 문서 근거를 포함한다.
근거 없는 조언은 금지한다.
최종 판단은 전문가 확인이 필요하다는 문구를 표시한다.
임상/법률 결정 자동화는 MVP 범위에서 제외한다.
도메인 프로필에서 안전 정책을 강제할 수 있어야 한다.

13. 데이터 모델 초안¶

Document¶

id
source_path
file_name
file_type
title
hash
status
created_at
updated_at
indexed_at
metadata_json

Chunk¶

id
document_id
chunk_index
text
page
section
token_count
embedding_id
metadata_json

Query¶

id
question
provider
model
domain_profile
created_at
latency_ms

Answer¶

id
query_id
answer_text
citations_json
confidence_label
created_at

EvaluationCase¶

id
question
expected_sources
expected_answer_points
domain_profile

14. API 초안¶

MVP API는 프론트엔드와 CLI가 동시에 사용할 수 있도록 단순하게 설계한다.

POST /documents
  문서 또는 폴더 등록

POST /documents/reindex
  전체 또는 일부 문서 재색인

GET /documents
  등록 문서 목록 조회

POST /query
  질문 입력, 검색, 답변 생성

GET /query/{id}
  이전 질의 결과 조회

GET /providers
  사용 가능한 LLM/임베딩 제공자 목록

POST /profiles
  도메인 프로필 추가 또는 수정

GET /profiles
  도메인 프로필 목록 조회

POST /eval/run
  평가 케이스 실행

15. UI 초안¶

MVP UI는 기능 검증에 집중한다.

화면 1: 문서 관리¶

문서 업로드
폴더 경로 등록
색인 상태 표시
실패 문서 표시
재색인 실행

화면 2: 질의응답¶

질문 입력창
도메인 프로필 선택
LLM provider/model 선택
답변 표시
출처 리스트 표시
근거 스니펫 펼치기
"문서 근거 없음" 상태 표시

화면 3: 설정¶

LLM provider 설정
임베딩 provider 설정
chunk size / top-k 설정
로그 저장 여부
외부 LLM 전송 경고 설정

화면 4: 평가¶

샘플 질문 목록
검색된 출처 확인
정답 포인트 매칭 여부
provider별 응답 비교

16. 성공 지표¶

16.1 기능 지표¶

사용자가 문서 등록부터 첫 질문까지 10분 이내 완료
지원 파일 형식 5종 이상 처리
답변마다 출처 표시
provider 교체 후 같은 인덱스로 질의 가능
문서 변경 시 재색인 가능

16.2 품질 지표¶

샘플 질문 기준 관련 출처 top-5 검색 성공률 80% 이상
근거 없는 질문에 대한 "근거 없음" 응답률 90% 이상
답변의 인용 출처가 실제 답변 내용과 일치하는 비율 80% 이상
100개 문서 규모에서 일반 질문 응답 시간 10초 이내

16.3 사용자 가치 지표¶

사용자가 기존 수동 검색보다 빠르게 답을 찾는다고 판단
답변 근거를 보고 원문 확인이 가능
다른 도메인 문서 묶음에도 동일 파이프라인 적용 가능

17. 평가 전략¶

RAG 시스템은 "답변이 그럴듯한가"보다 "근거를 정확히 찾았는가"를 먼저 평가해야 한다.

17.1 평가 단계¶

Retrieval 평가
질문에 대해 올바른 문서/페이지/섹션이 top-k에 포함되는지 확인
Grounded Answer 평가
답변이 검색된 근거 안에서만 생성되었는지 확인
Citation 평가
인용된 출처가 답변 문장과 실제로 연결되는지 확인
Abstention 평가
문서에 없는 질문에 대해 모른다고 말하는지 확인

17.2 평가 데이터¶

초기에는 도메인별로 10~20개 질문을 수동 작성한다.

question
expected_source
expected_answer_points
must_not_include
domain_profile

도메인 예시:

매뉴얼: 오류 코드, 설치 절차, 주의사항
게임: 아이템 효과, 퀘스트 조건, 캐릭터 설정
의료 문헌: 연구 대상, 결과 지표, 제한점
사내 정책: 승인 절차, 예외 조건, 책임 부서

18. 구현 로드맵¶

Phase 0: 프로젝트 기준 정리¶

목표:

기술 스택 확정
폴더 구조 확정
기본 실행 방식 확정

산출물:

README
.env.example
기본 폴더 구조
샘플 문서
샘플 질문 파일

Phase 1: 로컬 문서 색인¶

목표:

문서 등록
파싱
청킹
임베딩
벡터 DB 저장

검증:

샘플 문서가 색인된다.
청크별 메타데이터가 보존된다.
같은 문서를 중복 색인하지 않는다.

Phase 2: 검색 API¶

목표:

질의 임베딩
top-k 검색
메타데이터 포함 결과 반환

검증:

샘플 질문에 대해 기대 문서가 top-k에 포함된다.
검색 결과에 파일명과 위치가 포함된다.

Phase 3: LLM 답변 생성¶

목표:

provider adapter 구현
prompt template 구현
citation 포함 답변 생성

검증:

답변에 출처가 붙는다.
근거 없는 질문에는 답변을 거절한다.
provider 설정 변경이 가능하다.

Phase 4: 최소 UI¶

목표:

문서 관리 화면
질의응답 화면
설정 화면

검증:

비개발자도 문서를 넣고 질문할 수 있다.
답변에서 원문 근거를 확인할 수 있다.

Phase 5: 평가 루프¶

목표:

평가 케이스 정의
검색/답변 품질 측정
provider별 비교

검증:

평가 명령 하나로 품질 리포트가 생성된다.
retrieval, groundedness, citation 지표를 볼 수 있다.

19. 권장 프로젝트 구조¶

RAG_system/
  AGENTS.md
  README.md
  .env.example
  docs/
    local-rag-mvp-plan.ko.md
    architecture.md
  data/
    samples/
    indexes/
  app/
    api/
    core/
    ingestion/
    parsing/
    chunking/
    embeddings/
    retrieval/
    generation/
    providers/
    profiles/
    evaluation/
  tests/
    unit/
    integration/
  scripts/
    ingest_sample.py
    run_eval.py

주의:

data/indexes/와 실제 사용자 문서는 기본적으로 git에 포함하지 않는다.
샘플 문서는 공개 가능한 더미 문서만 둔다.

20. 주요 리스크와 대응¶

리스크 1: 답변은 자연스럽지만 근거가 틀림¶

대응:

답변마다 citation 필수
citation과 답변 문장 매칭 평가
근거 부족 시 답변 거절

리스크 2: PDF 파싱 품질이 낮음¶

대응:

파싱 결과 미리보기 제공
실패 문서 목록화
OCR은 MVP 이후로 분리

리스크 3: 도메인별 요구가 너무 달라짐¶

대응:

공통 RAG 파이프라인 유지
도메인 차이는 profile, metadata, prompt template로 처리
도메인별 플러그인 구조는 PMF 확인 후 도입

리스크 4: 외부 LLM 사용 시 민감 정보 유출 우려¶

대응:

외부 전송 문맥 미리보기
로컬 LLM 모드 지원
PII 마스킹은 후속 단계에서 추가
로그 저장을 opt-in으로 설계

리스크 5: 검색 품질 튜닝이 끝없이 늘어남¶

대응:

MVP 평가 질문 세트를 고정
검색 품질 목표를 수치화
chunk size, top-k, reranker 도입은 단계별 비교로 결정

21. 운영 정책 초안¶

기본 모드는 로컬 저장이다.
외부 LLM 호출은 사용자가 provider를 설정했을 때만 가능하다.
API key는 .env에만 둔다.
사용자 문서와 인덱스는 git 추적 대상이 아니다.
답변은 항상 근거 중심으로 생성한다.
고위험 도메인에서는 전문가 확인 필요 문구를 표시한다.

22. 오픈 질문¶

다음 결정은 구현 전에 확정해야 한다.

MVP UI를 Streamlit으로 빠르게 만들지, Next.js로 제품형 구조를 먼저 잡을지
첫 벡터 DB를 Chroma로 할지 Qdrant Local로 할지
임베딩 모델을 외부 API로 쓸지 로컬 모델로 쓸지
외부 LLM에 전송 가능한 문서 범위를 사용자가 매번 확인해야 하는지
첫 테스트 도메인을 무엇으로 잡을지
문서 업로드 방식은 파일 업로드가 우선인지 폴더 감시가 우선인지
의료/법률 같은 고위험 도메인을 MVP 데모에 포함할지, 후속 검증으로 둘지

23. MVP 완료 기준¶

MVP는 다음 조건을 만족하면 완료로 본다.

사용자는 로컬 문서 100개 이상을 등록하고 색인할 수 있다.
사용자는 자연어 질문을 입력해 문서 기반 답변을 받을 수 있다.
모든 답변에는 출처와 근거 스니펫이 표시된다.
문서에 없는 질문에는 근거 부족을 명확히 표시한다.
LLM provider를 설정으로 교체할 수 있다.
최소 2개 도메인 문서 묶음에서 동일 파이프라인이 동작한다.
평가 질문 세트로 검색 품질과 답변 품질을 확인할 수 있다.

24. 한 줄 제품 정의¶

로컬 문서를 안전하게 색인하고, 여러 LLM을 선택해 근거 있는 답변을 받을 수 있는 범용 문서 지식 검색기.