一键在 Manus 中运行任何 Skill

troubleshoot-rag

星标0

分支0

更新时间2026年3月8日 14:08

RAG 파이프라인 디버깅 가이드 (검색 품질, 할루시네이션, 인용 오류, 답변 품질 등). RAG 문제, 답변 품질 이슈, 검색이 안 됨, 할루시네이션, 인용 오류, 파이프라인 실패 시 사용. 답변 품질에 대한 불만이 있을 때도 자동 트리거.

安装

用 Codex 或 Claude 帮你安装复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。

在 Manus 中运行

来源

bigbulgogiburger

bigbulgogiburger/rag-bio

打开 GitHub 仓库查看创作者相关仓库

下载

在 Manus 中运行

Purpose

RAG 파이프라인의 각 단계에서 발생할 수 있는 문제를 체계적으로 진단하고 해결합니다.

Pipeline Overview

질문 입력
  ↓
[DECOMPOSE] 질문 분해 (multi-question 탐지)
  ↓
[EXTRACT_PRODUCTS] 제품명 추출 (confidence 0.6-0.9)
  ↓
[RETRIEVE Level 0] 제품 필터 정확 검색
  ↓ (0 결과)
[RETRIEVE Level 1] 카테고리 확장 검색
  ↓ (0 결과)
[RETRIEVE Level 2] 필터 제거 전체 검색
  ↓ (0 결과)
[ADAPTIVE] AI 기반 적응형 검색 (3회 재시도)
  ↓
[MULTI_HOP] 교차 추론 2단계 검색
  ↓
[VERIFY] 근거 검증 (SUPPORTED/CONDITIONAL/REFUTED)
  ↓
[COMPOSE] 답변 작성
  ↓
[CRITIC] 자가 비평 (최대 3회)
  ↓
[SELF_REVIEW] 품질 검토 (최대 2회)
  ↓
답변 초안 완성

Symptom → Diagnosis Map

1. 검색 결과 없음 (No Evidence)

증상: 답변이 "확인 후 별도로 답변드리겠습니다"로 생성됨

진단 체크리스트:

문서가 인덱싱되었는가?

# API로 인덱싱 상태 확인
curl localhost:8081/api/v1/inquiries/{id}/documents/indexing-status

벡터 DB에 청크가 존재하는가?
- VECTOR_DB_PROVIDER 설정 확인 (mock이면 영구 저장 안 됨)
제품명이 올바르게 추출되었는가?
- ProductExtractorService의 12개 Bio-Rad 제품 패턴 확인
- 로그: product.extracted 키워드로 검색
최소 벡터 스코어 임계값 확인
- MIN_VECTOR_SCORE=0.25 (application.yml)
- 너무 높으면 결과 필터링됨

해결: 인덱싱 재실행, 제품 패턴 추가, 임계값 조정

2. 검색 품질 낮음 (Irrelevant Evidence)

증상: 근거는 있지만 질문과 관련 없는 내용

진단 체크리스트:

HyDE 가상 문서 품질 확인
- 로그: hyde.generated 키워드
리랭킹 점수 분포 확인
- 0.4 미만이 대부분이면 검색 품질 문제
하이브리드 검색 가중치 확인
- vector-weight: 1.0, keyword-weight: 1.0 (application.yml)
청크 크기/오버랩 확인
- 청크가 너무 작으면 문맥 손실, 너무 크면 노이즈
Parent-Child 청크 구조 확인
- CHILD 매칭 시 PARENT 내용이 LLM에 제공되는지

해결: 리랭킹 임계값 조정, 청크 전략 변경, HyDE 프롬프트 개선

3. 할루시네이션 (Hallucination)

증상: 근거에 없는 내용이 답변에 포함됨

진단 체크리스트:

CriticAgent 결과 확인
- faithfulness_score < 0.70이면 needs_revision=true
- 로그: critic.result 키워드
ComposeStep 프롬프트 확인
- prompts/compose-system.txt에 "근거에 없는 내용 금지" 규칙 있는지
EVIDENCE_CHAR_BUDGET (12,000자) 초과 여부
- 근거가 잘리면 LLM이 빈 공간을 추측으로 채울 수 있음
모델 티어 확인
- 경량 모델일수록 할루시네이션 위험 증가

해결: CriticAgent 임계값 조정, 프롬프트 강화, 모델 업그레이드

4. 인용 오류 (Citation Errors)

증상: 인용 형식 불일치, 잘못된 페이지 번호

진단 체크리스트:

Citation 형식 확인
- 프론트엔드 파싱: chunk=UUID score=... documentId=... fileName=... pageStart=... pageEnd=...
ComposeStep의 인라인 인용 지시 확인
- (파일명, p.XX-YY) 형식 사용하는지
번호 인용([1], [2]) 사용 금지 확인
페이지 범위 정확성
- ChunkingService의 콘텐츠 기반 페이지 매핑 확인

해결: 프롬프트에 인용 형식 규칙 보강, 페이지 매핑 로직 수정

5. 톤/포맷 불일치

증상: 격식체가 아니거나, 마크다운이 포함되거나, 채널 포맷이 맞지 않음

진단 체크리스트:

preferredTone 파라미터 전달 확인
customerChannel 파라미터 전달 확인 (EMAIL/MESSENGER)
ComposeStep 프롬프트의 톤/채널 규칙 확인
- 이메일: 인사말 + 본문 + 마무리
- 메신저: [요약] 태그, 260자 이내

해결: 프롬프트 톤 규칙 수정, 채널별 분기 로직 확인

6. 파이프라인 실패 (Step Failure)

증상: 특정 단계에서 예외 발생

진단 도구:

-- 오케스트레이션 실행 로그 조회
SELECT step, status, latency_ms, error_message, created_at
FROM orchestration_runs
WHERE inquiry_id = '{id}'
ORDER BY created_at DESC;

Fallback 체인:

Step	실패 시 Fallback
OpenAiVerifyStep	→ DefaultVerifyStep (규칙 기반)
OpenAiComposeStep	→ DefaultComposeStep (템플릿 기반)
CriticAgent	→ 원본 draft 사용
MultiHopRetriever	→ 기존 evidences 유지
AdaptiveRetrieval	→ NO_EVIDENCE 경로
SelfReviewStep	→ 원본 draft 반환 (최대 2회 재시도)

Key Configuration

설정	위치	기본값	영향
`OPENAI_ENABLED`	.env	false	true여야 실제 LLM 사용
`MIN_VECTOR_SCORE`	application.yml	0.25	벡터 검색 최소 점수
`HYBRID_SEARCH_ENABLED`	application.yml	true	하이브리드 검색 활성화
`search.hybrid.rrf-k`	application.yml	60	RRF 퓨전 K값
EVIDENCE_CHAR_BUDGET	OpenAiComposeStep	12,000	근거 텍스트 최대 길이

Related Files

File	Purpose
`backend/app-api/src/main/java/.../answer/orchestration/AnswerOrchestrationService.java`	파이프라인 오케스트레이터
`backend/app-api/src/main/java/.../search/HybridSearchService.java`	하이브리드 검색
`backend/app-api/src/main/java/.../analysis/AnalysisService.java`	증거 분석
`backend/app-api/src/main/resources/prompts/`	외부화된 프롬프트
`backend/app-api/src/main/resources/application.yml`	검색/모델 설정

同仓库更多 Skills

同仓库

manage-skills

bigbulgogiburger/rag-bio

세션 변경사항을 분석하여 검증 스킬 누락을 탐지합니다. 기존 스킬을 동적으로 탐색하고, 새 스킬을 생성하거나 기존 스킬을 업데이트한 뒤 CLAUDE.md를 관리합니다.

2026-03-150

verify-api-contracts

bigbulgogiburger/rag-bio

REST API 응답 DTO 일관성 및 에러 코드 표준 검증. API 엔드포인트 추가/수정, DTO 변경, 에러 처리 수정 후 사용. API 계약 변경이 프론트엔드에 영향을 줄 수 있을 때 사용.

2026-03-150

verify-flyway-migrations

bigbulgogiburger/rag-bio

Flyway DB 마이그레이션 일관성 검증. 마이그레이션 추가/수정 후 사용.

2026-03-150

verify-frontend-ui

bigbulgogiburger/rag-bio

프론트엔드 UI 컴포넌트 품질 검증 (shadcn/ui + Tailwind 기준). UI 컴포넌트 수정 후 사용.

2026-03-150

verify-kb-indexing

bigbulgogiburger/rag-bio

KB 비동기 인덱싱 파이프라인 검증. 인덱싱 관련 코드 수정 후 사용.

2026-03-150

verify-rag-pipeline

bigbulgogiburger/rag-bio

RAG 파이프라인 (답변 작성 + 분석 + 다운로드) 검증. 답변 작성/분석/다운로드 관련 코드 수정 후 사용.

2026-03-150

name	troubleshoot-rag
description	RAG 파이프라인 디버깅 가이드 (검색 품질, 할루시네이션, 인용 오류, 답변 품질 등). RAG 문제, 답변 품질 이슈, 검색이 안 됨, 할루시네이션, 인용 오류, 파이프라인 실패 시 사용. 답변 품질에 대한 불만이 있을 때도 자동 트리거.

Purpose

RAG 파이프라인의 각 단계에서 발생할 수 있는 문제를 체계적으로 진단하고 해결합니다.

Pipeline Overview

질문 입력
  ↓
[DECOMPOSE] 질문 분해 (multi-question 탐지)
  ↓
[EXTRACT_PRODUCTS] 제품명 추출 (confidence 0.6-0.9)
  ↓
[RETRIEVE Level 0] 제품 필터 정확 검색
  ↓ (0 결과)
[RETRIEVE Level 1] 카테고리 확장 검색
  ↓ (0 결과)
[RETRIEVE Level 2] 필터 제거 전체 검색
  ↓ (0 결과)
[ADAPTIVE] AI 기반 적응형 검색 (3회 재시도)
  ↓
[MULTI_HOP] 교차 추론 2단계 검색
  ↓
[VERIFY] 근거 검증 (SUPPORTED/CONDITIONAL/REFUTED)
  ↓
[COMPOSE] 답변 작성
  ↓
[CRITIC] 자가 비평 (최대 3회)
  ↓
[SELF_REVIEW] 품질 검토 (최대 2회)
  ↓
답변 초안 완성

Symptom → Diagnosis Map

1. 검색 결과 없음 (No Evidence)

증상: 답변이 "확인 후 별도로 답변드리겠습니다"로 생성됨

진단 체크리스트:

문서가 인덱싱되었는가?

# API로 인덱싱 상태 확인
curl localhost:8081/api/v1/inquiries/{id}/documents/indexing-status

벡터 DB에 청크가 존재하는가?
- VECTOR_DB_PROVIDER 설정 확인 (mock이면 영구 저장 안 됨)
제품명이 올바르게 추출되었는가?
- ProductExtractorService의 12개 Bio-Rad 제품 패턴 확인
- 로그: product.extracted 키워드로 검색
최소 벡터 스코어 임계값 확인
- MIN_VECTOR_SCORE=0.25 (application.yml)
- 너무 높으면 결과 필터링됨

해결: 인덱싱 재실행, 제품 패턴 추가, 임계값 조정

2. 검색 품질 낮음 (Irrelevant Evidence)

증상: 근거는 있지만 질문과 관련 없는 내용

진단 체크리스트:

HyDE 가상 문서 품질 확인
- 로그: hyde.generated 키워드
리랭킹 점수 분포 확인
- 0.4 미만이 대부분이면 검색 품질 문제
하이브리드 검색 가중치 확인
- vector-weight: 1.0, keyword-weight: 1.0 (application.yml)
청크 크기/오버랩 확인
- 청크가 너무 작으면 문맥 손실, 너무 크면 노이즈
Parent-Child 청크 구조 확인
- CHILD 매칭 시 PARENT 내용이 LLM에 제공되는지

해결: 리랭킹 임계값 조정, 청크 전략 변경, HyDE 프롬프트 개선

3. 할루시네이션 (Hallucination)

증상: 근거에 없는 내용이 답변에 포함됨

진단 체크리스트:

CriticAgent 결과 확인
- faithfulness_score < 0.70이면 needs_revision=true
- 로그: critic.result 키워드
ComposeStep 프롬프트 확인
- prompts/compose-system.txt에 "근거에 없는 내용 금지" 규칙 있는지
EVIDENCE_CHAR_BUDGET (12,000자) 초과 여부
- 근거가 잘리면 LLM이 빈 공간을 추측으로 채울 수 있음
모델 티어 확인
- 경량 모델일수록 할루시네이션 위험 증가

해결: CriticAgent 임계값 조정, 프롬프트 강화, 모델 업그레이드

4. 인용 오류 (Citation Errors)

증상: 인용 형식 불일치, 잘못된 페이지 번호

진단 체크리스트:

Citation 형식 확인
- 프론트엔드 파싱: chunk=UUID score=... documentId=... fileName=... pageStart=... pageEnd=...
ComposeStep의 인라인 인용 지시 확인
- (파일명, p.XX-YY) 형식 사용하는지
번호 인용([1], [2]) 사용 금지 확인
페이지 범위 정확성
- ChunkingService의 콘텐츠 기반 페이지 매핑 확인

해결: 프롬프트에 인용 형식 규칙 보강, 페이지 매핑 로직 수정

5. 톤/포맷 불일치

증상: 격식체가 아니거나, 마크다운이 포함되거나, 채널 포맷이 맞지 않음

진단 체크리스트:

preferredTone 파라미터 전달 확인
customerChannel 파라미터 전달 확인 (EMAIL/MESSENGER)
ComposeStep 프롬프트의 톤/채널 규칙 확인
- 이메일: 인사말 + 본문 + 마무리
- 메신저: [요약] 태그, 260자 이내

해결: 프롬프트 톤 규칙 수정, 채널별 분기 로직 확인

6. 파이프라인 실패 (Step Failure)

증상: 특정 단계에서 예외 발생

진단 도구:

-- 오케스트레이션 실행 로그 조회
SELECT step, status, latency_ms, error_message, created_at
FROM orchestration_runs
WHERE inquiry_id = '{id}'
ORDER BY created_at DESC;

Fallback 체인:

Step	실패 시 Fallback
OpenAiVerifyStep	→ DefaultVerifyStep (규칙 기반)
OpenAiComposeStep	→ DefaultComposeStep (템플릿 기반)
CriticAgent	→ 원본 draft 사용
MultiHopRetriever	→ 기존 evidences 유지
AdaptiveRetrieval	→ NO_EVIDENCE 경로
SelfReviewStep	→ 원본 draft 반환 (최대 2회 재시도)

Key Configuration

설정	위치	기본값	영향
`OPENAI_ENABLED`	.env	false	true여야 실제 LLM 사용
`MIN_VECTOR_SCORE`	application.yml	0.25	벡터 검색 최소 점수
`HYBRID_SEARCH_ENABLED`	application.yml	true	하이브리드 검색 활성화
`search.hybrid.rrf-k`	application.yml	60	RRF 퓨전 K값
EVIDENCE_CHAR_BUDGET	OpenAiComposeStep	12,000	근거 텍스트 최대 길이

Related Files

File	Purpose
`backend/app-api/src/main/java/.../answer/orchestration/AnswerOrchestrationService.java`	파이프라인 오케스트레이터
`backend/app-api/src/main/java/.../search/HybridSearchService.java`	하이브리드 검색
`backend/app-api/src/main/java/.../analysis/AnalysisService.java`	증거 분석
`backend/app-api/src/main/resources/prompts/`	외부화된 프롬프트
`backend/app-api/src/main/resources/application.yml`	검색/모델 설정