تشغيل أي مهارة في Manus بنقرة واحدة

troubleshoot-rag

النجوم٠

التفرعات٠

آخر تحديث٨ مارس ٢٠٢٦ في ١٤:٠٨

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

التثبيت

التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.

تشغيل في Manus

المصدر

bigbulgogiburger

bigbulgogiburger/rag-bio

فتح مستودع GitHub عرض مستودعات المنشئ

تنزيل

تشغيل في Manus

المهن ذات الصلةSOC

استنادا إلى تصنيف SOC المهني

مطوّرو البرمجياتمهن الحاسوب والرياضيات·SOC 15-1252

SKILL.md

readonly

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`	검색/모델 설정

المزيد من هذا المستودع

نفس المستودع

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`	검색/모델 설정