핵심 특징
KB 생성부터 문서 수집·인덱싱·검색으로 이어지는 파이프라인과, 그 위를 둘러싼 접근제어· 통합 인터페이스·관리 콘솔·운영 지원까지 영역별 전체 기능·파라미터 목록을 정리한다. 전체 구성을 먼저 보려면 Introduction을 먼저 참고한다.
1. 지식베이스(KB) 관리
| 기능 | 설명 |
|---|---|
| 복수 KB 운영 | 조직 내 목적별 KB를 개수 제한 없이 생성·운영. 이름, 설명, 태그 부여 |
| KB 수명주기 | 생성/수정/삭제. 삭제 시 벡터·원본 파일·메타데이터를 일괄 정리(cascade) |
| KB 현황 집계 | KB별 문서 상태(인덱싱 완료/대기/처리 중/실패/삭제) 카운트를 단일 호출로 조회 |
2. 문서 수집
2.1 직접 업로드
| 기능 | 설명 |
|---|---|
| 파일 업로드 | 단일/배치 업로드. 업로드 즉시 비동기 인덱싱 시작, 진행 상태 URL 반환 |
| 지원 포맷 | PDF, Word(docx), 한글(HWP), 텍스트(txt), 마크다운(md), HTML, reStructuredText |
| 동일 파일 재업로드 | 같은 파일명 재업로드 시 기존 문서로 인식해 새 내용으로 재인덱싱 (중복 문서 생성 없음) |
| 파일 크기 제한 | 설정 기반 업로드 상한 (기본 10 MB) |
2.2 커넥터 — 외부 소스 자동 수집
| 커넥터 | 수집 대상 | 주요 설정 |
|---|---|---|
| 웹 크롤러 | 사내 포털, 문서 사이트 | 시작 URL, 탐색 깊이, 페이지 상한, URL 포함/제외 패턴, 인증 헤더/Basic 인증, 본문 최소 길이 필터(네비게이션 페이지 자동 제외) |
| Confluence | 스페이스 페이지 + 첨부파일 | Cloud/Server 자동 감지, 레이블 기반 제외, 첨부파일 크기 상한 |
| GitHub | 저장소 문서·소스코드 | 브랜치, 경로 접두사, 파일 수/크기 상한. 소스코드는 언어별 AST 단위 청킹 자동 적용 |
커넥터 공통 기능:
| 기능 | 설명 |
|---|---|
| 증분 동기화 | 버전 지표(Confluence 버전 번호, git blob SHA, ETag)가 같으면 재처리 생략 — 변경분만 재인덱싱 |
| 스케줄 동기화 | cron 표현식으로 자동 실행 (예: 매일 새벽 2시). 활성/비활성 즉시 토글 |
| 수동 트리거 / 일시정지 / 재개 | 스케줄과 무관한 즉시 실행, 커넥터 단위 pause/resume |
| 동기화 중단(abort) | 진행 중인 수집을 즉시 중단 — 대기 문서 제거, 실행 중 작업 종료 |
| 실패 가시성 | 마지막 동기화 오류 메시지를 API/화면에서 확인 (last_error), 커넥터별 문서 상태 집계 |
| 인증 정보 보호 | 접속 토큰은 환경변수 참조 방식 — 토큰 값 자체는 DB에 저장하지 않음 |
2.3 고급 문서 이해 [ENT]
일반 텍스트 추출만으로는 놓치는 이미지·스캔 문서·표 콘텐츠를 검색 가능한 형태로 끌어올리는 opt-in 인제스트 확장
모두 기본값은 꺼져 있으며 KB별로 다르게 켜고 끌 수 있다(3장 "KB별 설정 오버라이드" 참고).
| 기능 | 설명 |
|---|---|
| 이미지 캡셔닝 | 문서에 포함된 이미지를 비전 언어 모델(VLM)로 분석해 캡션을 생성하고 검색 가능한 청크로 인덱싱 |
| 스캔 문서 OCR 폴백 | 텍스트 레이어가 없거나 페이지당 추출 글자 수가 기준 미만인 스캔 PDF를 자동 감지해 로컬 OCR 엔진으로 전환 |
| PDF 표 구조 보존 파싱 | 표를 한 줄 텍스트로 뭉개는 대신 셀/행/열 구조를 인식해 마크다운 표로 추출. 텍스트 레이어가 있는 PDF와 스캔 PDF 양쪽 모두 지원 |
세 기능 모두 외부 API 호출 없는 로컬 추론(온프레미스 배포에서도 데이터가 외부로 나가지 않음) 이며, 활성화 시 문서당 처리 시간이 늘어나는 트레이드오프가 있다.
3. 인덱싱 파이프라인
| 기능 | 설명 |
|---|---|
| 문서 단위 격리 처리 | 문서 1건 = 독립 실행 1건. 특정 문서 실패가 다른 문서에 영향 없음, 문서별 재시도 |
| 병렬 처리 | 다중 문서 동시 인덱싱 (동시 실행 수 설정 가능), dense/sparse 임베딩 병렬 수행 |
| 청킹 전략 | 재귀 분할(recursive), 의미 기반 분할(semantic), 소스코드 AST 분할 — 크기/오버랩 설정 가능 |
| 임베딩 | 로컬(Ollama, 기본 bge-m3 다국어) 또는 OpenAI 선택. dense + 키워드(sparse) 이중 인덱싱 |
| 중복 문서 감지 | 2단계 자동 감지 — 해시 기반(SHA-256/SimHash) 완전·근사 중복 + MinHash Jaccard·제목 퍼지 매칭 유사 중복. 한국어 형태소 분석(Kiwi) 기반, 사용자 사전 확장 가능 |
| 문서 상태 추적 | 업로드-수집-대기-처리-완료-실패-삭제 전 단계 상태 머신. 실패 시 원인 메시지 보존 |
| 재인덱싱 | KB 전체/문서 단위, 변경분만 또는 강제(force). 실패 문서 개별 재처리 |
| 장애 복구 | 비정상 종료로 고착된 문서 자동 감지·복구(Dagster 모드), 수동 복구/강제 실패 API |
| 삭제 관리 | soft delete(원본 보존, 검색 제외) / hard delete(완전 삭제) 구분. 처리 중 문서에 대한 충돌 요청은 안전하게 차단(409) |
| KB별 설정 오버라이드 | 청킹 전략/크기/오버랩, 중복 감지 임계값, 업로드 파일 크기 제한 등 인제스트 설정을 KB마다 전역값과 다르게 지정 가능. 미지정 필드는 전역 설정을 그대로 상속. (ENT) 2.3의 이미지 캡셔닝/OCR 폴백/표 구조 보존 파싱 on/off 및 세부 파라미터도 같은 방식으로 KB별 오버라이드 대상이며, 조회는 viewer 이상, 변경은 owner 이상 역할이 필요 |
4. 검색
| 기능 | 설명 |
|---|---|
| 하이브리드 검색 | 의미(dense) + 키워드(sparse) 결합, RRF로 순위 통합. alpha 파라미터로 의미/키워드 가중 조절 |
| 유사도 검색 | 코사인 유사도 단독 모드, min_score로 저품질 결과 차단 |
| 복수 KB 통합 검색 | 여러 KB를 한 번에 검색해 단일 순위로 병합. KB별 장애 격리(한 KB 실패가 전체 검색을 막지 않음) |
| 리랭킹 | Jina 리랭커 연동으로 상위 결과 재정렬. API 장애 시 자동 폴백(검색 자체는 항상 성공) |
| 요청 단위 튜닝 | top_k, alpha, min_score, rerank 여부를 검색 요청마다 오버라이드 |
| 응답 메타데이터 | 문서 출처, 페이지 번호, 점수, 지연시간, 리랭킹 적용 여부 등 부가 정보 포함 |
5. 접근제어 [ENT]
| 기능 | 설명 |
|---|---|
| 기업 SSO | OIDC(Keycloak 등) 연동 Bearer JWT 인증. 관리 콘솔은 Authorization Code + PKCE 로그인 |
| KB 단위 RBAC | KB마다 viewer(조회) / editor(문서 작업) / admin(설정·멤버) / owner(삭제·이전) 4단계 역할 |
| 권한 적용 범위 | REST API 전체 + 검색(접근 불가 KB 자동 제외) + MCP 툴까지 일관 적용 |
| 멤버십 관리 | 멤버 등록/역할 변경/제거. 이메일 기반 — 미가입 사용자는 초대장이 생성되고 첫 로그인 시 자동 활성화 (SMTP 알림 발송) |
| 소유권 관리 | 소유권 이전, owner 이탈 시 자동 승계(최고참 admin 승격), 승계 불가 시 KB 동결(frozen) 및 관리자 복구 절차 |
| 공개 KB | KB를 public으로 전환하면 모든 인증 사용자에게 조회 권한 부여 (전사 공지·규정 KB 용도) |
| 슈퍼관리자 | IdP 그룹 기반 전역 관리자 — 모든 KB에 owner 권한, 고아 KB 복구 |
| RBAC 온오프 | 시스템 설정으로 KB 권한 체크 전체를 켜고 끔 (도입 초기 단계적 적용 가능, 활성화 시 기존 KB 소유자 자동 백필) |
| 사용자별 요청 제한 | 검색·업로드·재인덱싱 등 경로별로 사용자당 요청 한도 설정, 초과 시 429 반환. super-admin은 우회, Redis 장애 시 제한 없이 통과(fail-open) |
| 사용자 디프로비저닝 | 이메일 또는 user_id로 사용자를 전체 KB에서 한 번에 제거. owner였던 KB는 자동 승계 또는 동결 |
| 민감정보 보호 | 커넥터 인증 토큰 대칭키 암호화 저장, API 응답 마스킹 |
6. 통합 인터페이스
| 기능 | 배포 | 설명 |
|---|---|---|
| REST API | Core | 전체 기능 API 제공, Swagger UI 대화형 문서 내장 |
| MCP 서버 | Core | 검색/KB 목록 툴을 MCP(streamable HTTP)로 노출 — Claude, IDE 에이전트 등 MCP 클라이언트 연동 |
| 인증 MCP | ENT | MCP 경로에도 JWT 인증 + KB 권한 필터 적용 (search / list_knowledge_bases / get_document) |
| CLI | Core | 서버 기동, 문서 인제스트, 검색을 명령줄에서 직접 실행 |
7. 관리 콘솔
| 화면 | 기능 |
|---|---|
| 대시보드 | 인프라 구성요소(벡터 DB, 큐, 스토리지, 메타 DB, 임베딩 서버) 상태 타일, 30초 자동 갱신 |
| Knowledge Bases | KB 목록/생성/수정/삭제, 태그, (ENT) 내 역할 배지·public 표시 |
| Connectors | 커넥터 생성 마법사(소스별 설정 폼), 동기화 트리거/중단/일시정지, 상태·문서 집계, 실패 원인 표시 |
| Documents | 페이지네이션·상태 필터·파일명 검색·정렬, 드래그앤드롭 업로드(진행률 폴링), 선택 재인덱싱/삭제, 고착 문서 복구 |
| Query | 검색 콘솔 — KB 멀티선택, 모드/파라미터 조정, 점수·출처·발췌 표시 (검색 품질 확인용) |
| Access Management [ENT] | KB별 멤버 테이블, 이메일 초대(가입/미가입/기존멤버 자동 분기), 역할 변경, 소유권 이전, 공개 설정 |
| Configuration | KB별 인제스트 설정 오버라이드 편집 — ingestion/chunking/dedup 탭, 필드 단위 오버라이드 표시·리셋 및 전체 리셋, 유효 설정 JSON 다운로드 |
8. 운영 지원
| 기능 | 설명 |
|---|---|
| 헬스체크 | liveness(/health) / readiness(/ready, 전체 인프라 연결 점검) — k8s 프로브 대응 |
| 파이프라인 운영 UI | Dagster UI로 문서별 실행 이력, 실패 로그, 센서 상태 확인 |
| 분산 트레이싱 | OpenTelemetry 기반 Langfuse 연동 (검색·MCP 호출 추적), 설정으로 온오프 |
| 실행 모드 선택 | Dagster 모드(운영 권장) / 내장 워커 모드(경량 구성) — 동일 큐를 소비하는 이중 모드 |
| 컨테이너 배포 | Docker Compose 제공, 전 구성요소 컨테이너화 |