> ## Documentation Index
> Fetch the complete documentation index at: https://docs.platform.nora.my/llms.txt
> Use this file to discover all available pages before exploring further.

# 리트리벌 진단

> 왜 내 청크가 안 나오지?

가장 흔한 리트리벌 질문: *"이 문서에 답이 있는 걸 아는데 왜 Agent 가 못 찾지?"*

Diagnostics 도구는 파이프라인을 역방향으로 걸어 무엇이 잘못됐는지 찾습니다.

## Diagnostics 열기

두 진입점:

* **트레이스에서** — 리트리벌 스텝 어디서든 "Diagnose retrieval" 클릭. 사용된 정확한 쿼리와 프리셋 로드.
* **문서에서** — 지식의 청크 우클릭 → "Test retrievability". 그것을 찾아야 할 쿼리 시뮬레이션.

## Diagnostics 가 보여주는 것

주어진 쿼리와 기대 청크에 대해 Diagnostics 가 답하는 것:

1. **청크가 인덱스에 있나?** — 정상 확인. 없으면 파이프라인 보기 (Clean 중 필터됐나? 청커가 스킵했나?).
2. **필터가 배제하나?** — 필터 세트와 청크가 통과하는지 표시.
3. **벡터 점수는?** — 쿼리와 청크의 코사인 유사도. 낮은 점수 (\< 0.2) 는 시맨틱 불일치 — 청크가 쿼리와 "의미가 다름".
4. **키워드 점수는?** — BM25 점수. 낮은 점수는 쿼리에 청크 안 단어가 없다는 뜻 (동의어 추가 고려).
5. **융합 순위는?** — 청크가 top 50 에서 어디 랭크됐는지.
6. **리랭커가 드롭했나?** — 리랭킹이 켜져 있었고 top K 밖으로 떨어졌나.
7. **그라운딩이 드롭했나?** — 그라운딩이 켜져 있었고 청크가 그래프와 충돌했나.

## 흔한 실패와 해결

| 증상             | 유력 원인                       | 해결                               |
| -------------- | --------------------------- | -------------------------------- |
| 인덱스에 없음        | Clean 됨, 청커가 스킵, 소스 필터가 드롭  | 소스 항목의 Foundry 실행 로그 확인          |
| 필터에 배제됨        | 메타데이터 불일치 — 청크에 태그/필드 없음    | 강화 스테이지에서 태그 추가 또는 필터 완화         |
| 낮은 벡터 점수       | 쿼리 표현이 청크 표현과 멂             | 문서에 별칭 추가 또는 쿼리 확장 켬             |
| 낮은 키워드 점수      | 공통 리터럴 용어 없음                | 위와 동일 — 또는 벡터가 처리하는 것 수용         |
| 랭크됐지만 top-K 아래 | 다른 소스 부스트가 더 큼              | 소스/태그 부스트 조정                     |
| 리랭커가 드롭        | 크로스 인코더가 다른 청크가 더 관련 있다고 판단 | 때로 옳음 — 승자 청크 검사                 |
| 그라운딩이 드롭       | 그래프에 모순 사실                  | 그래프 조정 또는 그라운딩 액션을 `demote` 로 설정 |

## 대규모 수정

진단이 여러 쿼리에서 같은 근본 원인을 계속 가리키면, 그것이 시그널. 개선 플로우 ([최적화](/ko/reliable/optimization/proposals) 참고) 가 반복되는 리트리벌 미스를 새 태그·프리셋 변경·청커 조정 제안으로 전환할 수 있음.

## 리트리버빌리티 테스트

"기대되는" 청크-쿼리 쌍 세트를 **Retrievability test** 로 저장. CI (또는 수동) 에서 실행. top-K 가 예전에 포함하던 청크를 더 이상 포함 안 하면 실패.

좋은 패턴: "X 를 왜 못 찾지" 이슈를 고칠 때마다 수정이 회귀하지 않도록 리트리버빌리티 테스트 추가.