> ## 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.

# nora retrieval

> CLI에서 검색 실행, 리트리벌 프리셋 관리, 실패 진단

`retrieval` 명령 그룹이 리트리벌 서브시스템, 즉 에이전트 쿼리와 지식 사이 층의 CLI 표면.

## 명령

| 명령                                | 설명                          |
| --------------------------------- | --------------------------- |
| `retrieval search <query>`        | 검색 쿼리 실행.                   |
| `retrieval diagnose <cluster-id>` | 실패 클러스터에서 처음 깨진 리트리벌 스텝 짚기. |
| `retrieval presets list`          | 모든 리트리벌 프리셋 나열.             |
| `retrieval presets get <id>`      | 프리셋 하나의 설정 가져오기.            |
| `retrieval presets upsert <id>`   | 프리셋 생성/교체.                  |
| `retrieval presets delete <id>`   | 프리셋 삭제.                     |

## `retrieval search`

```bash theme={null}
nora retrieval search "환불은 어떻게 작동해" \
  --preset high-precision \
  --k 10 \
  --method hybrid \
  --filters '{"tag": "billing"}'
```

쿼리를 돌려 결과를 출력.

플래그:

* `<query>`(위치) 검색할 텍스트.
* `--preset <preset-id>` 저장된 프리셋 사용(아래 참고).
* `--k <n>` 돌려줄 top-K.
* `--method vector|keyword|hybrid|kg_rooted` 리트리벌 모드.
* `--filters <json>` 메타데이터 필터 표현식.
* `--include-subgraph` 관련 그래프 노드를 넣어 결과 확장.
* `--graph-expansion` 지식 그래프 순회 켜기.

`--preset`이 없으면 워크스페이스 기본 프리셋을 씀.

## `retrieval diagnose`

```bash theme={null}
nora retrieval diagnose cl_billing_misses
```

실패 클러스터(Signals → cluster)에서 처음 깨진 리트리벌 스텝을 짚음. "이 클러스터의 실패가 리트리벌 파이프라인 어디서 실제로 났나?" 에 답함. 필터가 버렸나? 벡터 점수가 너무 낮았나? 리랭커가 내렸나? 그라운딩이 거절했나?

출력이 그 스텝을 짚고, 실패 트레이스별 근거를 표시.

어느 리트리벌 레버를 손볼지 정하기 전, 겨냥한 진단으로 쓰기 좋음.

## 프리셋

프리셋이 리트리벌 설정(top-K, 가중치, 필터, 리랭커)을 묶어, 여러 Agent가 한 설정을 공유하게 함.

### List

```bash theme={null}
nora retrieval presets list
```

### Get

```bash theme={null}
nora retrieval presets get high-precision
```

프리셋 설정을 JSON으로 출력.

### Upsert

```bash theme={null}
nora retrieval presets upsert high-precision \
  --name "High Precision" \
  --config '{
    "k": 6,
    "method": "hybrid",
    "vector_weight": 0.6,
    "keyword_weight": 0.4,
    "reranker": true,
    "cutoff": 0.2
  }'
```

없으면 프리셋 생성, 있으면 교체.

플래그:

* `<id>`(위치, 필수) 프리셋 ID.
* `--name <n>`(필수) 표시 이름.
* `--config <json>`(필수) 전체 프리셋 설정. 필드 레퍼런스는 [리트리벌 프리셋](/ko/build/retrieval/presets) 참고.

### Delete

```bash theme={null}
nora retrieval presets delete high-precision
```

Agent가 프리셋을 쓰면 실패. 먼저 그 Agent를 고침.

## 레시피

### 프리셋 반복 튜닝

```bash theme={null}
# 현재 스냅샷
nora retrieval presets get high-precision --json > preset.json

# 로컬 편집 (예: vector_weight 올리기)
jq '.config.vector_weight = 0.7' preset.json > preset-tuned.json

# 다시 upsert
nora retrieval presets upsert high-precision \
  --name "$(jq -r '.name' preset-tuned.json)" \
  --config "$(jq -c '.config' preset-tuned.json)"

# 실제 쿼리로 테스트
nora retrieval search "샘플 질문" --preset high-precision
```

### 프리셋 둘 나란히 비교

```bash theme={null}
diff <(nora retrieval search "refund" --preset old) \
     <(nora retrieval search "refund" --preset new)
```

### 테넌트 사이 리트리벌 격리 테스트

```bash theme={null}
nora retrieval search "민감 질문" \
  --filters '{"tenant":"acme"}'
# tenant="other" 청크를 돌려주면 안 됨
```

앱의 격리 테스트 뷰와 함께 쓰면 확실히 확인.

### `agents sources update`로 프리셋 붙이기

프리셋을 다 맞췄으면 Agent 데이터 소스에 붙임:

```bash theme={null}
nora agents sources update ag_support \
  --kind documents_folder \
  --source-id billing \
  --set-preset high-precision
```

소스 붙임 옵션 전체는 [`nora agents`](/ko/cli/agents) 참고.

## CLI가 안 하는 것

* **리트리벌 결과를 데이터셋에 저장** 그건 앱의 트레이스 뷰를 씀(트레이스 검색 후 리트리벌 스텝을 데이터셋에 추가).
* **그라운딩 그래프 직접 설정** 그라운딩은 프리셋 설정으로 켬(`{"grounding": {"graph_id": "..."}}`). 그래프 편집은 [`nora causal`](/ko/cli/causal)로.

## 쿼리 디버깅

* 결과별 원시 점수 내역은 `--json`을 붙임.
* `--method vector`, 그다음 `--method keyword`를 따로 시도해 어느 패스가 더 센지 확인.
* 맞는 청크가 있는데 랭크가 안 되면, 비슷한 쿼리가 담긴 클러스터에 `retrieval diagnose`가 대개 이유를 설명.