nora retrieval

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

명령

명령	설명
`retrieval search <query>`	검색 쿼리 실행.
`retrieval diagnose <cluster-id>`	실패 군집에서 처음 깨진 리트리벌 스텝 짚기.
`retrieval presets list/get/upsert/delete`	리트리벌 프리셋 CRUD.
`retrieval type-profile show`	활성 타이핑 프로파일 · 레지스트리 · 조준 가능한 타입 id 표시.
`retrieval type-profile set <id>`	워크스페이스 활성 프로파일 전환.
`retrieval type-profile backfill`	활성 프로파일로 기존 청크 재타이핑.
`retrieval type-profile custom list/put`	워크스페이스 정의 커스텀 프로파일 관리.

`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> FiltersBody 전체 모양(documentIds / pipelineIds / tags / kgInstanceId / kgOnly / kgScopeNodeId / excludeDocumentIds). @file · @- 도 받습니다.
--include-subgraph KG-rooted 상위 히트에서 걸어낸 컴팩트 트리플 서브그래프를 포함 (KG 바인딩 필요).
--graph-expansion 온톨로지 엣지에 spreading activation 을 켭니다 (KG in-scope 필요).
--routing-mode pinned|auto pinned(기본, --preset 사용) vs auto(라우터가 쿼리 의도로 프리셋 선택).
--target-type <type-id> hybrid 풀을 이 청크 타입에 조준 (예약 슬롯 + 부스트, hybrid 전용). 반복 가능. 유효 id 는 retrieval type-profile show 로 확인.
--target-entity <entity> 이 엔티티가 태그된 청크에 조준. 반복 가능.
--expand-window <n> 상위 청크 주변 이웃 n 개를 상위 섹션 컨텍스트로 함께 가져옴 (0 = 끔).
--reserved-per-type <n> 조준 타입당 최소 예약 top-k 슬롯 수.

--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를 고치세요.

타입 인지 리트리벌

청크 타이핑은 인제스트 시점에 청크마다 타입 라벨(heading, table, policy_clause, benefit_table 등) 을 붙여, 검색이 딱 맞는 콘텐츠 모양에 조준할 수 있게 합니다. 워크스페이스에는 활성 타이핑 프로파일 하나가 걸립니다. generic(도메인 중립 기본), insurance 같은 빌트인 도메인 프로파일, 오퍼레이터가 정의한 커스텀 프로파일 중 하나입니다.

`type-profile show`

nora retrieval type-profile show

활성 프로파일과 전체 프로파일 레지스트리(빌트인 ∪ 커스텀), 그리고 활성 프로파일이 조준할 수 있는 타입 id 를 출력합니다. UI 의 타입 체크박스 · 프로파일 셀렉터가 렌더하는 목록과 같습니다. 타입 id 를 retrieval search --target-type <id> 에 그대로 씁니다.

`type-profile set`

nora retrieval type-profile set insurance
nora retrieval type-profile set legal      # 커스텀 프로파일

활성 프로파일을 전환합니다. 빌트인 id(generic, insurance) 도, custom put 으로 만든 커스텀 id 도 받습니다. 기존 청크를 재타이핑하지는 않습니다. 현재 코퍼스를 다시 분류하려면 이 명령 뒤에 backfill 을 붙이세요.

`type-profile backfill`

nora retrieval type-profile backfill

기존 청크를 활성 프로파일로 재타이핑합니다. 이미 타이핑된 행은 건너뛰는 idempotent 실행. {scanned, typed, abstained} 을 출력합니다.

`type-profile custom`

빌트인이 없는 도메인(예: legal, medical) 을 위한 커스텀 프로파일. 빌트인 프로파일은 코드에서 관리하므로 여기서는 다루지 않습니다.

# 워크스페이스 커스텀 프로파일 나열(빌트인 제외)
nora retrieval type-profile custom list

# 커스텀 목록 전체를 JSON 으로 bulk 교체
nora retrieval type-profile custom put --file @profiles.json
nora retrieval type-profile custom put --file '[{"id":"legal","types":[...],"rules":{...}}]'

custom put 은 bulk 교체 라, 페이로드에 없는 프로파일은 지워집니다. 항목 하나의 모양:

{
  "id": "legal",
  "label": "Legal",
  "types": [{ "id": "clause", "label": "Clause" }, ...],
  "rules": { "clause": ["shall", "hereby", ...] },
  "entity_suffixes": ["Inc.", "LLC", ...]
}

검증: id 비어 있으면 안 되고, 유일해야 하고, generic · insurance 를 덮어쓰면 안 됩니다.

레시피

프리셋 반복 튜닝

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

프리셋 둘 나란히 비교

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가 대개 이유를 설명합니다

CLI

SDK

Local App

nora retrieval

명령

`retrieval search`

`retrieval diagnose`

프리셋

List

Get

Upsert

Delete

타입 인지 리트리벌

`type-profile show`

`type-profile set`

`type-profile backfill`

`type-profile custom`

레시피

프리셋 반복 튜닝

프리셋 둘 나란히 비교

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

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

CLI가 안 하는 것

쿼리 디버깅

​명령

​retrieval search

​retrieval diagnose

​프리셋

​List

​Get

​Upsert

​Delete

​타입 인지 리트리벌

​type-profile show

​type-profile set

​type-profile backfill

​type-profile custom

​레시피

​프리셋 반복 튜닝

​프리셋 둘 나란히 비교

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

​agents sources update로 프리셋 붙이기

​CLI가 안 하는 것

​쿼리 디버깅

명령

`retrieval search`

`retrieval diagnose`

프리셋

List

Get

Upsert

Delete

타입 인지 리트리벌

`type-profile show`

`type-profile set`

`type-profile backfill`

`type-profile custom`

레시피

프리셋 반복 튜닝

프리셋 둘 나란히 비교

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

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

CLI가 안 하는 것

쿼리 디버깅