nora retrieval

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`

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`

nora retrieval diagnose cl_billing_misses

실패 클러스터 (Signals → cluster) 에 첫 깨진 리트리벌 스테이지 고정. “이 클러스터의 실패가 리트리벌 파이프라인 어디서 실제 일어났나?” 에 답 — 필터가 드롭? 벡터 점수 너무 낮음? 리랭커가 강등? 그라운딩이 거부? 출력이 특정 스테이지 식별하고 실패 트레이스별 증거 표시. 어느 리트리벌 레버 튜닝할지 결정 전 타겟된 진단으로 사용 최적.

프리셋

프리셋이 리트리벌 설정 (top-K, 가중치, 필터, 리랭커) 을 번들해 여러 Agent 가 하나의 설정 공유 가능.

List

nora retrieval presets list

Get

nora retrieval presets get high-precision

프리셋 설정을 JSON 으로 인쇄.

Upsert

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> (필수) — 전체 프리셋 설정. 필드 레퍼런스는 리트리벌 프리셋 참고.

Delete

nora retrieval presets delete high-precision

Agent 가 프리셋 참조하면 실패. 먼저 그 Agent 업데이트.

레시피

프리셋 반복 튜닝

# 현재 스냅샷
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

두 프리셋 나란히 비교

diff <(nora retrieval search "refund" --preset old) \
     <(nora retrieval search "refund" --preset new)

테넌트 간 리트리벌 격리 테스트

nora retrieval search "민감 질문" \
  --filters '{"tenant":"acme"}'
# tenant="other" 청크 반환 안 해야

앱의 격리 테스트 뷰와 결합해 확정 체크.

`agents sources update` 로 프리셋 붙임

프리셋이 다이얼링되면 Agent 데이터 소스에 붙임:

nora agents sources update ag_support \
  --kind documents_folder \
  --source-id billing \
  --set-preset high-precision

전체 소스 붙임 옵션은 nora agents 참고.

CLI 가 하지 않는 것

리트리벌 결과를 데이터셋에 저장 — 그건 앱의 트레이스 뷰 사용 (트레이스 검색, 리트리벌 스텝을 데이터셋에 추가).
그라운딩 그래프 직접 설정 — 그라운딩은 프리셋 설정으로 활성 ({"grounding": {"graph_id": "..."}}), 그래프 편집은 nora causal 로.

쿼리 디버깅

결과별 원시 점수 분해에 --json 추가.
--method vector, 그 다음 --method keyword 별도 시도해 어느 패스가 더 강한지 확인.
올바른 청크가 존재하지만 랭크 안 되면, 유사 쿼리 담은 클러스터에 retrieval diagnose 가 보통 왜인지 설명.

시작

플로우

블록

데이터·지식

신뢰성

워크스페이스

레퍼런스

nora retrieval

명령

`retrieval search`

`retrieval diagnose`

프리셋

List

Get

Upsert

Delete

레시피

프리셋 반복 튜닝

두 프리셋 나란히 비교

테넌트 간 리트리벌 격리 테스트

`agents sources update` 로 프리셋 붙임

CLI 가 하지 않는 것

쿼리 디버깅

​명령

​retrieval search

​retrieval diagnose

​프리셋

​List

​Get

​Upsert

​Delete

​레시피

​프리셋 반복 튜닝

​두 프리셋 나란히 비교

​테넌트 간 리트리벌 격리 테스트

​agents sources update 로 프리셋 붙임

​CLI 가 하지 않는 것

​쿼리 디버깅

명령

`retrieval search`

`retrieval diagnose`

프리셋

List

Get

Upsert

Delete

레시피

프리셋 반복 튜닝

두 프리셋 나란히 비교

테넌트 간 리트리벌 격리 테스트

`agents sources update` 로 프리셋 붙임

CLI 가 하지 않는 것

쿼리 디버깅