> ## Documentation Index
> Fetch the complete documentation index at: https://docs.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에서 걸림, 청커가 건너뜀, 소스 필터가 버림 | 그 소스 항목의 파운더리 실행 로그를 봅니다         |
| 필터에 걸림           | 메타데이터가 안 맞음. 청크에 태그/필드가 없음     | 강화 단계에서 태그를 더하거나 필터를 풉니다         |
| 낮은 벡터 점수         | 쿼리 표현이 청크 표현과 멂                | 문서에 별칭을 더하거나 쿼리 확장을 켭니다          |
| 낮은 키워드 점수        | 공통 리터럴 용어가 없음                  | 위와 같음, 또는 벡터가 잡는 걸 받아들입니다        |
| 랭크는 됐는데 top-K 아래 | 다른 소스 부스트가 더 큼                 | 소스/태그 부스트를 손봅니다                  |
| 리랭커가 버림          | 크로스 인코더가 다른 청크를 더 관련 있다고 봄     | 맞을 때도 있습니다. 이긴 청크를 보세요           |
| 그라운딩이 버림         | 그래프에 부딪히는 사실이 있음               | 그래프를 고치거나 그라운딩 액션을 `demote`로 둡니다 |

## 대규모 수정

진단이 여러 쿼리에서 같은 근본 원인을 계속 가리키면, 그게 신호입니다. 개선 플로우([최적화](/ko/reliable/optimization/proposals) 참고)가 되풀이되는 리트리벌 미스를 새 태그, 프리셋 변경, 청커 조정 제안으로 바꿔 줍니다.

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

"기대하는" 청크-쿼리 쌍 묶음을 **Retrievability test**로 저장합니다. CI(또는 수동)에서 돌립니다. top-K가 예전에 담던 청크를 더는 안 담으면 실패합니다.

좋은 습관이 있습니다. "X를 왜 못 찾지" 문제를 고칠 때마다, 그 수정이 회귀하지 않도록 리트리버빌리티 테스트를 하나 더해 두세요.