검색·색인 단계 준비 (초안)
작성: 2026-09-14 · 확정: 2026-09-15 — PLATFORM_VISION.md §9-5 결정. 세 저장소의 실제 라우트를 읽어 권고안(A)이 맞음을 검증했고(§3), 콘솔용 관리·상태 API 계약 초안을 §6에 정리했다. 관련 문서: PLATFORM_VISION.md · AI_FEATURE_REGISTRY.md(retrieval 능력) · ONTOLOGY_SCOPE.md(추출 입력) · DECISION_LOG.md
1. 왜 지금 필요한가
앞의 두 단계가 끝나 있다.
| 단계 | 상태 |
|---|---|
| 문서 | 문서 라이브러리 운영 중(24건 게시·조회, docs/** 변경 시 자동 게시) |
| 지식 | 온톨로지 1단계 완료 — 승인된 개념·관계·용어팩을 포털이 버전 고정으로 받는다(ONTOLOGY_SCOPE.md) |
남은 연결은 색인이다. 문서·정책·비정형 문서를 색인에 태워야 (a) 자연어 질의와 (b) 온톨로지 추출 입력(ontology.extract)을 얻는다.
2. 결정 (§9-5, 2026-09-15 확정)
| 후보 | 내용 | 평가 |
|---|---|---|
| A · 확정 | 오케스트레이션 = ExploreGateway · 색인·RAG·citation = RagService | 2026-09-13 "RAG 소유자" 결정과 정합. 다중 포털 탐색 조합은 Explore, 문서 색인·근거는 RagService |
| B | 한 서비스로 통합 | 이미 분리 운영 중이라 통합 비용이 크고 업무 경계가 섞인다 ❌ |
| C | ExploreGateway 가 색인까지 | 2026-09-13 정정(RagService 가 색인·RAG·citation 소유)과 충돌 ❌ |
확정: A. 남은 작업은 관리·상태 API 계약(§6)이다 — 콘솔이 서버 간 토큰으로 각 서비스를 호출할 때 쓸 경로와 응답 모양.
3. 검증 — 실제 계약과 맞는가 (2026-09-15)
세 저장소의 실제 라우트를 읽어 A안이 맞음을 확인했다.
| 서비스 | 실제 계약 | 판정 |
|---|---|---|
| RagService | POST /api/v1/search · POST /api/v1/chat/stream · POST /api/v1/questions/embedding · GET·PUT /api/v1/admin/settings · GET /api/v1/admin/overview · GET /api/v1/admin/operations · GET /api/v1/admin/tuning/recommendations(+ approve) · DELETE /api/v1/admin/documents/{id} | 색인·검색·RAG·citation·튜닝을 한 서비스가 소유 ✅ A안과 일치 |
| ExploreGateway | GET /healthz · POST /api/explore/v1/search | 검색 조합 실행만 소유(색인 없음) ✅ 오케스트레이터 |
| 인증 | RagService 는 디렉터리가 서명한 JWT(Bearer, audience rag-center, scope rag:admin)를 검증 | 콘솔이 이미 서명 주체라 서버 간 호출에 같은 체계를 재사용 ✅ |
| 색인 입력 | 파일 경로 기반 배치(BatchDocumentJob{path, metadata} → parse_document) | FileStore 가 원본을 두고 경로를 넘기는 방식 ✅ 비전 §6-2 와 일치 |
4. 결정 후 할 일
- 관리·상태 API 계약 — 초안 작성 완료(§6). 실제 연결은 RagService 가용과 경로 규약 확정 후
- 콘솔 사용량 뷰에 검색·색인 지표 연결 —
AI_FEATURE_REGISTRY.md§6 - 문서 라이브러리 색인 연동 — 첫 소비자는 플랫폼 문서(자연어 질의)
- 온톨로지 추출 입력 연결 — 같은 색인을
ontology.extract의 입력으로 쓴다
5. 하지 않는 것
- 새 검색 서비스 신설 ❌ (이미 분리 운영 중)
- 플랫폼이 업무 로직을 실행 ❌ (근거 제공까지 — 비전 §2 경계)
- 콘솔이 색인을 소유 ❌ (표시·정책·프록시만)
6. 콘솔용 관리·상태 API 계약 (초안)
콘솔은 각 서비스에 직접 붙지 않고 서버 간 호출로만 접근한다(브라우저 비노출 — MODEL_GATEWAY_SCOPE §8-7 과 같은 원칙).
| 콘솔 표면 | 호출 | 용도 |
|---|---|---|
| 검색·색인 상태 | GET {RAG_SERVICE_URL}/api/v1/admin/overview | 색인 문서·청크 수, 마지막 색인 시각 → 사용량 뷰 |
| 운영 지표 | GET {RAG_SERVICE_URL}/api/v1/admin/operations | 처리량·실패·지연 |
| 설정 | GET·PUT {RAG_SERVICE_URL}/api/v1/admin/settings | 색인·검색 파라미터(콘솔에서 조회·수정) |
| 튜닝 제안 | GET /api/v1/admin/tuning/recommendations · POST .../approve | 제안 검토·승인(사람 승인 원칙과 정합) |
| 색인 제거 | DELETE /api/v1/admin/documents/{sourceDocumentId} | 문서 폐기 시 색인 정리 |
| 탐색 상태 | GET {EXPLORE_GATEWAY_URL}/healthz | 오케스트레이터 가용성 |
인증: 콘솔이 서명한 JWT(Authorization: Bearer, audience·scope 지정)를 그대로 쓴다 — RagService 가 이미 디렉터리 토큰을 검증하므로 새 토큰 체계를 만들지 않는다.
남은 것: 파일 경로 기반 색인에 넘길 공유 스토리지 경로 규약(FileStore 원본 위치 ↔ RagService 가 읽는 경로)과 재발행 시점(승인 즉시 vs 배치 · ONTOLOGY_SCOPE.md §7 의 질문과 같은 문제). 경로 규약의 후보와 제약(FileStore 로컬 위치자는 local:// 불투명 locator · RagService 입력은 파일 경로 배치 · 발행 포트는 현재 로그 스텁)은 FILE_STORE_SCOPE.md §6 에 정리했다 — 저장소 라우팅 소유자·콘솔 표면은 그 문서에서 확정됐다(2026-09-15).