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

# nora retrieval

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

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

## 명령

| 명령                                | 설명                          |
| --------------------------------- | --------------------------- |
| `retrieval search <query>`        | 검색 쿼리 실행.                   |
| `retrieval diagnose <cluster-id>` | 실패 클러스터의 첫 깨진 리트리벌 스테이지 고정. |
| `retrieval presets list`          | 모든 리트리벌 프리셋 나열.             |
| `retrieval presets get <id>`      | 한 프리셋의 설정 fetch.            |
| `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 bump)
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` 가 보통 왜인지 설명.