RAGFlow 사용법: 안정적인 RAG 앱 구축을 위한 실용적인 가이드
업데이트 날짜: 2025년 9월 19일
8 분
RAGFlow 사용법: 신뢰성 있는 RAG 앱 구축을 위한 실용적인 가이드
검색 증강 생성(RAG) 시스템을 구축해 본 적이 있다면 환각 현상, 불안정한 검색, 느린 파이프라인, 복잡한 문서 전처리 등과 같은 고질적인 문제에 직면했을 것입니다. RAGFlow는 문서 수집, 청크 분할, 벡터화, 검색, 생성을 보다 효과적으로 제어하고 관찰할 수 있도록 지원하는 엔드 투 엔드 워크플로 도구입니다.
본 가이드는 실용적이고 솔루션 지향적인 접근 방식을 취합니다. 깔끔한 설정 방법을 안내하고, 실제 문서에 RAGFlow를 사용하는 방법을 보여주며, 환각 현상을 줄이고 답변 품질을 향상시키는 패턴을 공유합니다.
RAGFlow란 무엇이며 왜 사용해야 할까요?
RAGFlow는 검색 증강 생성 파이프라인 구축을 위한 시스템입니다. 일반적인 RAG 설정에서는 다음을 수행합니다.
- 문서 수집 (PDF, 웹 페이지, 슬라이드, 코드 등)
- 검색 가능한 단위로 콘텐츠를 청크 분할
- 의미론적 검색을 위해 청크를 벡터로 임베딩
- 질문 시점에 상위 k개의 관련 청크 검색
- LLM을 사용하여 근거 있는 답변 생성
RAGFlow는 의견이 반영된 기본 설정, 워크플로 블록 및 안전 장치를 추가하여 더 빠르게 반복하고 더 안정적인 앱을 출시할 수 있도록 지원합니다. 다음과 같은 경우 특히 유용합니다.
- 일관된 청크 분할 및 메타데이터: 더 나은 검색은 더 나은 청크에서 시작됩니다.
- 플러그형 임베딩 및 LLM: OpenAI, 로컬 모델 또는 엔터프라이즈 엔드포인트를 교체합니다.
- 평가 및 안전 장치: 검색 품질을 측정하고 환각 현상을 줄입니다.
- 배포 가능한 파이프라인: 더 적은 재작성으로 노트북에서 프로덕션으로 이동합니다.
빠른 시작: 제로(0)에서 작동하는 RAGFlow 파이프라인으로
다음은 적용할 수 있는 최소한의 엔드 투 엔드 워크플로입니다. 환경이 다르더라도 시퀀스 및 안전 장치는 이식 가능합니다.
1) 환경 준비
- 키와 함께
.env파일을 만듭니다.
OPENAI_API_KEY(또는 다른 LLM 제공업체)
EMBEDDINGS_API_KEY(별도의 제공업체를 사용하는 경우)
VECTOR_DB_URL(예: Pinecone, Weaviate, Qdrant 또는 로컬)
- 프로젝트 디렉터리를 설정합니다(예:
ragflow-project/). 폴더 포함:
data/raw/(소스 파일)
data/processed/(정리된 청크)
configs/(파이프라인 설정을 위한 YAML/JSON)
eval/(데이터 세트 및 보고서)
2) 깨끗한 메타데이터로 문서 수집
좋은 메타데이터 = 더 나은 검색. 제목, 작성자, 날짜 및 출처를 정규화합니다.
- 강력한 파서를 사용하여 PDF 및 슬라이드를 텍스트로 변환합니다.
- 구조 유지: 제목, 목록, 코드 블록 및 표
- 각 청크에 메타데이터 첨부:
출처,섹션,페이지,타임스탬프,버전
팁: 인용 및 재수집을 지원하기 위해
doc_id 및 chunk_id를 유지합니다.3) 콘텐츠에 맞는 청크 분할 전략 선택
청크 분할은 검색 품질 및 대기 시간에 큰 영향을 미칩니다.
- 설명 문서의 경우: 의미론적 청크 분할 (제목/단락별 분할)
- 기술 문서의 경우: 하이브리드 청크 분할 사용 (의미론적 + 고정 창)
- 코드의 경우: 작은 슬라이딩 창으로 함수/클래스별로 청크 분할
시작하기 위한 권장 설정:
chunk_size: 600–1,000 토큰
chunk_overlap: 50–100 토큰
max_depth: 단편화를 방지하기 위해 중첩된 섹션을 2–3레벨로 제한
4) 임베딩 및 벡터 저장소 선택
- 강력한 범용 임베딩 모델(예: text‑embedding‑3‑large 또는 최신 로컬 모델)로 시작합니다. 개인 정보 보호가 중요한 경우 자체 호스팅 임베딩을 고려하십시오.
- 다음을 지원하는 벡터 DB를 사용합니다.
- 하이브리드 검색 (밀도 + 키워드)
- 필터 (메타데이터 제약 조건)
- 일괄 업서트 및 인덱스 메트릭
테스트할 인덱스 설정:
- 초기 검색을 위한
top_k = 5–10
similarity_metric = cosine(또는 특정 모델의 경우 dot)
- 중복성을 줄이기 위해 최대 한계 관련성(MMR) 활성화
5) 검색 오케스트레이션
2단계 검색기 구현:
- 빠른 후보 리콜
- 하이브리드 검색(BM25 + 밀도)
- 큰
top_k(예: 30–50)
- 재정렬
- 교차 인코더 재정렬 또는 LLM 기반 점수 매기기
- 최종
top_k로 축소 (예: 5–8)
신뢰할 수 있는 문서로 답변을 제한하려면
source:"handbook" AND section:"benefits" AND version:"v2"와 같은 메타데이터 필터를 추가합니다.6) 구조화된 근거 있는 생성
프롬프트는 증거가 약할 때 인용 및 거부를 시행해야 합니다.
예제 시스템 프롬프트:
당신은 신중한 도우미입니다. 제공된 컨텍스트에서 지원하는 정보만 사용하여 답변하십시오.- [doc_id:chunk_id]와 같이 출처를 인라인으로 인용하십시오.- 컨텍스트가 불충분한 경우 "제공된 문서에 충분한 정보가 없습니다."라고 말하십시오.- 사실을 날조하지 마십시오.사용자 프롬프트 템플릿:
질문: {query}컨텍스트:{top_chunks}지침:- 먼저 간결한 답변을 제공한 다음 세부 정보를 제공하십시오.- 각 사실적 주장의 뒤에 인용문을 포함하십시오.7) 환각 현상을 줄이기 위해 안전 장치 추가
- 답변 가능성 확인: 생성을 시작하기 전에 작은 모델에 “검색된 청크에 직접적인 증거가 있습니까?”라고 묻습니다. 그렇지 않은 경우 명확히 묻는 질문을 반환합니다.
- 인용 또는 침묵 정책: 인용문이 없는 출력물은 차단합니다.
- 엔터프라이즈 콘텐츠에 대한 유해성/PII 필터.
8) 평가 및 지속적인 개선
다음을 사용하여
eval/ 세트 만들기:- 50–200개의 실제 사용자 질문
- 정답 (또는 신뢰할 수 있는 참조)
- 해당되는 경우 예상 출처 (문서 ID)
측정:
- 검색 적중률 (골드 소스가 상위 k에 나타나는가?)
- 답변 충실도 (인용문으로 뒷받침되는 진술)
- 대기 시간 (p95 엔드 투 엔드)
- 비용 (100개 쿼리당)
반복:
- 청크 크기 및 중복
- 임베딩 모델 선택
- 재정렬 vs. 더 높은 상위 k
- 프롬프트 구조 및 제약 조건
전체 RAGFlow 파이프라인: 예제 구성
다음은 도구 체인에 맞게 조정할 수 있는 개념적 구성입니다. 필요에 따라 공급자 이름을 바꿉니다.
project: product-handbook-ragio:input_path: data/raw/output_index: product-handbook-indexparsing:pdf:strategy: autokeep_layout: trueextract_tables: truemarkdown:preserve_headings: truechunking:method: semantic_hybridtarget_tokens: 800overlap_tokens: 80windowing: 2metadata:fields: [doc_id, title, section, page, version, source]embeddings:provider: openaimodel: text-embedding-3-largevectorstore:type: qdranturl: ${VECTOR_DB_URL}similarity: cosineretrieval:hybrid: truelexical_weight: 0.35semantic_weight: 0.65candidate_top_k: 40rerank:enabled: truemodel: bge-reranker-largefinal_top_k: 7generation:llm: gpt-4otemperature: 0.2cite_or_silence: trueguardrails:answerability_check: truepii_filter: truetoxicity_filter: moderatemonitoring:log_traces: truelatency_budget_ms: 3500cost_budget_per_100: 1.25다양한 콘텐츠 유형에 RAGFlow를 사용하는 방법
제품 설명서 및 핸드북
- 명확한 섹션 경계가 있는 의미론적 청크 분할 선호
- 버전 및 유효 날짜를 첨부하여 오래된 답변 방지
- 엄격한 필터 사용: 항상
version = latest필요
지식 베이스 및 FAQ
- 정확한 답변을 위해 더 작은 청크(400–600 토큰) 사용
- 후보 풀을 늘리고 정확한 스니펫을 찾기 위해 재정렬에 의존
- 어휘 검색을 통해 리콜을 높이기 위해 정식 Q/A 쌍 자동 생성
엔지니어링 문서 및 코드
- 함수/모듈별로 청크 분할하고 메타데이터에 가져오기 그래프 포함
- 상위-하위 검색 활성화: 함수 + 해당 문서 문자열 컨텍스트 반환
- 관련 기호를 우선시하기 위해 코드 인식 재정렬기 사용
법률 및 규정 준수
- 단락 수준의 인용문 필요
- 불완전한 컨텍스트에 대한 거부 로직 추가
- 별도의 인덱스에 규제 기관 승인 출처의 골든 세트 유지
실제로 작동하는 프롬프트 패턴
- 답변 후 인용: 맨 위에 짧은 답변; 각 주장의 뒤에 인라인으로 인용문
- 검색 체인: 모델에 각 청크를 먼저 요약한 다음 종합하도록 요청
- 쿼리 재작성: 검색 전에 동의어 및 도메인 용어로 사용자 쿼리 확장
- 대조 프롬프트: “컨텍스트를 기반으로 옵션 A가 B보다 나은 이유를 설명하십시오.” 이렇게 하면 증거 사용이 강제됩니다.
예제 쿼리 재작성 단계:
원래: "PTO 이월 정책은 무엇입니까?"재작성: "유급 휴가 이월 정책; 휴가 롤오버; 최대 시간; 최신 정책 버전"관찰 가능성 및 피드백 루프
- 사용된 청크, 해당 점수 및 무시된 청크를 기록
- 짧은 설명과 함께 찬성/반대를 캡처합니다. 이를 검색기 조정에 다시 피드백합니다.
- 모델 변경 사항을 배포하기 전에 매주 평가 세트에서 회귀 테스트를 실행합니다.
성능 조정 요약
- 답변이 일반적인 느낌이 들면
candidate_top_k를 늘리고 더 강력한 재정렬기를 추가합니다.
- 답변에 세부 정보가 누락된 경우: 청크 크기를 줄입니다. 어휘 가중치를 약간 높입니다.
- 인용문이 동일한 청크를 반복하는 경우: MMR을 활성화하고 다양성을 높입니다.
- 대기 시간이 긴 경우: 임베딩을 캐시하고, 쿼리 재작성을 미리 계산하고, 더 작은 재정렬기를 사용합니다.
- 비용이 급증하는 경우: 생성 온도를 낮추고, 프롬프트를 단축하고, 첫 번째 패스에 더 작은 LLM을 사용해 봅니다.
보안 및 거버넌스 필수 사항
- 저장된 벡터를 암호화하고 메타데이터에서 중요한 필드를 수정합니다.
- 인덱스별 액세스 제어를 사용합니다. 팀 또는 데이터 민감도별로 분할합니다.
- 데이터 계보 기록 유지: 문서 출처 URL, 체크섬 및 수집 타임스탬프
사례 연구 스냅샷: 지저분한 PDF에서 신뢰할 수 있는 답변으로
지원팀에서 1,200페이지의 PDF를 수집했습니다. 초기 검색은 일관성이 없었습니다. 에이전트는 봇을 신뢰하지 않았습니다. 의미론적-하이브리드 청크 분할(800 토큰, 80 오버랩)로 전환하고, 교차 인코더 재정렬을 활성화하고, 인용 또는 침묵을 시행한 후 상위 k 적중률이 62%에서 89%로 상승하고 에이전트 채택률이 두 배로 증가했습니다. 핵심은 더 큰 LLM이 아니라 더 깔끔한 청크와 더 엄격한 검색이었습니다.
도구 팁: AI 사이드바를 사용한 빠른 반복
주목할 가치가 있습니다. 많은 문서에서 프롬프트와 검색 스니펫을 실험하는 경우 브라우저에서 직접 PDF, 웹 페이지 및 코드를 통해 채팅할 수 있는 AI 어시스턴트를 사용하면 반복 속도를 높일 수 있습니다. 그런데 Sider.AI(https://sider.ai/)는 페이지에서 컨텍스트를 가져오고, 요약하고, 프롬프트를 빠르게 개선할 수 있는 AI 사이드바를 제공합니다. 파이프라인을 공식화하기 전에 RAG 프롬프트를 프로토타입하고 청크 품질을 테스트하는 데 유용합니다.
RAGFlow 문제 해결: 빠른 수정
- "모델이 자신 있지만 잘못되었습니다."
- 답변 가능성 확인 활성화; 온도 낮추기; 인용문 필요
- "검색에서 거의 중복된 항목이 반환됩니다."
- MMR을 켭니다. 재정렬기 추가; 청크 중복 감소
- "피크 시 대기 시간이 급증합니다."
- 일괄 임베딩; 쿼리 재작성 캐시; 스트리밍 생성 사용
- "오래된 정책이 계속 표시됩니다."
version = latest로 필터링합니다. 오래된 문서를 더 이상 사용하지 않거나 비석 처리합니다.
다음 단계: 프로덕션에서 RAGFlow를 안정적으로 만들기
- 작고 신뢰할 수 있는 코퍼스로 시작합니다. 먼저 청크 분할 및 필터를 완벽하게 만듭니다.
- LLM을 업그레이드하기 전에 재정렬기 추가
- 100개 질문 평가 세트를 구축하고 매주 적중률을 추적합니다.
- 사용자 피드백을 연결하여 검색을 지속적으로 조정합니다.
주요 내용:
- 검색 품질이 RAG의 모델 크기를 능가합니다.
- 청크 분할, 메타데이터 및 재정렬은 핵심 레버입니다.
- 인용 또는 침묵과 같은 안전 장치는 신뢰도를 크게 높입니다.
- 관찰 가능성 및 평가에 조기에 투자하십시오.
이러한 방식을 통해 RAGFlow는 헬프 봇, 개발자 코파일럿 또는 내부 지식 어시스턴트를 지원하든 근거 있는 답변을 위한 신뢰할 수 있는 중추가 됩니다.
FAQ
Q1:RAGFlow란 무엇이며 문서 QA에 어떻게 사용합니까?
RAGFlow는 검색 증강 생성 파이프라인을 구축하기 위한 프레임워크입니다. 환각 현상을 줄이고 정확도를 높이기 위해 인용문과 함께 답변을 수집, 청크 분할, 임베딩, 검색 및 생성합니다.
Q2:RAGFlow에서 문서를 어떻게 청크 분할해야 합니까?
600–1,000 토큰 청크와 50–100 토큰 오버랩으로 의미론적 또는 하이브리드 청크 분할을 사용합니다. 코드의 경우 함수 또는 클래스별로 청크 분할하고 주변 컨텍스트를 포함합니다.
Q3:어떤 벡터 데이터베이스가 RAGFlow에 가장 적합합니까?
하이브리드 검색, 메타데이터 필터 및 재정렬을 지원하는 저장소를 선택합니다. Qdrant, Weaviate, Pinecone 또는 로컬 옵션이 모두 일반적인 선택입니다.
Q4:RAGFlow 앱에서 환각 현상을 어떻게 방지합니까?
인용 또는 침묵 정책을 시행하고, 생성을 시작하기 전에 답변 가능성 확인을 추가하고, 검색된 컨텍스트만 사용하도록 프롬프트를 엄격하게 유지합니다.
Q5:RAGFlow를 평가하기 위해 어떤 메트릭을 추적해야 합니까?
검색 적중률, 답변 충실도, 대기 시간 및 100개 쿼리당 비용을 모니터링하고 작지만 대표적인 평가 세트를 유지합니다.
