Nexus 웹 사용 가이드
본 가이드는 웹 브라우저를 통해 Nexus 엔터프라이즈 검색 콘솔을 활용하는 절차를 기술합니다 (환경 기동 방법은 Nexus 빠른 시작 참조).
브라우저에서 http://localhost:8000/ 접속 시 웹 콘솔이 제공되며, 시스템은 색인된 지식 코퍼스에 입각하여 검증된 답변 근거 및 출처 메타데이터와 함께 답변을 산출합니다.
질의응답 콘솔 (채팅)
- 자연어 질의: 검색창에 질의어를 입력하여 실행합니다.
- 엔티티 범위 한정:
@엔티티명(예:@payment-service) 접두사를 입력하여 특정 서비스 또는 도메인 모듈로 검색 컨텍스트를 한정할 수 있습니다. - 결정론적 기각 응답: 코퍼스 내에 질의를 뒷받침하는 충분한 답변 근거가 존재하지 않는 경우, 허위 정보를 생성하지 않고 **“제공된 문서에서 해당 정보를 찾을 수 없습니다”**라는 표준 기각 응답을 반환합니다.
답변 및 답변 근거 패널 (Evidence Panel)
모든 답변에는 인용 표기([출처: 문서 제목, 섹션])가 포함되며, 우측 답변 근거 패널을 통해 다음 항목을 확인하고 검증할 수 있습니다:
- 원천 문서 식별자 및 섹션명
- 출처 거버넌스 신뢰 배지 (하단 참조)
- 관련도 점수 지표 (BM25 및 벡터 융합 점수 백분율)
- 추출된 원천 텍스트 청크 스니펫
출처 신뢰도 배지 (Trust Badges)
각 답변 근거 데이터는 문서의 거버넌스 승인 수준에 따라 3단계 등급으로 구분되어 표시됩니다:
| 배지 식별자 | 상태 정의 및 신뢰도 | 적용 아티팩트 예시 |
|---|---|---|
| 거버넌스 (Governance) | 승인 게이트 및 무결성 검증을 거친 정본 사양 (신뢰 최상) | 승인된 ADR, 정식 설계 사양(SPEC), RFC |
| 추적 (Tracked) | 기술 검토가 진행되었으나 불변 스탬프는 부재한 운영 문서 | PRD, 운영 런북, 사후 분석(Postmortem) 보고서 |
| 메모 배지 | 비공식 참조용 메모 (미승인 문서) | 개인 엔지니어링 노트, 외부 수집 자료 |
분류 체계가 지정되지 않은 신규 문서는 기본값으로 참조 메모 등급이 부여됩니다.
코퍼스 및 문서 관리
문서(Documents) 탭에서는 색인된 전체 문서 목록, 신뢰 배지, 수집 소스(Notion, 파일 업로드, Git) 및 현재 가시성 상태를 관리할 수 있습니다:
- 논리적 삭제: 문서를 물리적으로 파기하지 않고 검색 가시성 대상에서 제외하며, 언제든지 복원(Revive)할 수 있습니다.
- 승계 이력 추적 (Supersede): 특정 문서가 신규 사양으로 대체된 경우, 대체한 최신 문서 식별자를 상호 참조 링크로 노출합니다.
외부 소스 동기화 (Notion 연동)
소스(Sources) 탭에서 원격 Notion 워크스페이스의 루트 페이지 URL을 등록하여 하위 문서 트리를 자동 동기화할 수 있습니다:
- 인증 및 도달성 검증: 연동 토큰의 유효성 및 대상 루트 페이지의 접근 권한을 사전 검증합니다.
- 트리 수집 실행 (Sync): 하위 페이지 트리를 순회하며 형태소 분석 및 임베딩을 생성하여 색인합니다.
- 삭제 반영 미리보기: 원격에서 삭제된 페이지를 색인에서 제외하기 전 대상 목록을 사전 검토한 후 soft_delete 상태로 반영합니다.
지식 그래프 뷰어
그래프(Graph) 탭은 문서 기반의 정적 설계 관계와 OTel 분산 트레이스 기반의 런타임 관측 관계를 토폴로지 다이어그램으로 시각화합니다.
접근 권한 및 보안 경계
인증 토큰 없이 접속할 경우 시스템은 익명 모드로 전환되어 PUBLIC 분류 문서에 한해서만 검색 결과를 반환합니다. INTERNAL 및 RESTRICTED 등급 문서에 접근하기 위해서는 유효한 인증 토큰(NEXUS_DEV_TOKEN 등)을 통한 헤더 인증이 요구됩니다.