Hybrid KMS — 소스·문서 분석 요약
PostgreSQL 한 대에 pgvector(의미 검색)와 Apache AGE(지식 그래프)를 올린 Hybrid Knowledge Management System. 문서 수집 시 온톨로지 제약 하에 그래프를 만들고, 검색 시 벡터 + 그래프를 RRF로 융합합니다.
목차
이 페이지는 저장소 문서와 소스 코드 분석 결과를 한곳에 정리한 것입니다.
1. 한 줄 정의
문서를 넣을 때 온톨로지 제약 하에 파싱·추출·그래프화하고,
검색할 때 벡터(의미) + 그래프(관계)를 RRF로 융합해 문서를 찾는
단일 Postgres KMS.
핵심 원칙
| 원칙 | 내용 |
|---|---|
| SQL = Source of Truth | 문서·청크·엔티티·관계는 SQL; AGE는 sql_id 기준 파생 투영 |
| LLM은 트랜잭션 밖 | parse / embed / IE는 TX 밖, graph_write만 짧은 TX |
| 2-tier 온톨로지 | Core 고정 + Domain 확장(검수 큐) → ontology explosion 방지 |
| HybridRAG | Pure Vector / Pure Graph 단독이 아닌 융합 검색 |
2. 기술 스택
README 및 런타임 설정(src/core/config.py) 기준.
| 구성요소 | 기술 |
|---|---|
| API | FastAPI + uvicorn (127.0.0.1:8020) |
| DB | PostgreSQL + pgvector + Apache AGE + pg_trgm + unaccent |
| Embeddings | 기본 hashing-v1(로컬 해시); OpenAI-compatible 선택 |
| Jobs | DB 폴링 워커 (Redis 없음 — 설계 권장과 다름) |
| Auth | API Key (X-API-Key / Bearer) |
| 문서 파싱 | PDF, DOCX, PPTX, XLSX, HWP/HWPX, MD/TXT/HTML/CSV |
| UI | public/ 정적 웹 + /manual 설계 매뉴얼 |
3. 핵심 파이프라인
Ingest: Document → Parse → Chunk → Embed → Ontology-IE → Resolve → SQL(SoT) + AGE(projection) Search: Query → A(BM25+dense) → B(entity link + hop0–2) → C(RRF) → D(optional LLM Q&A)
문서 업로드 흐름 (구현)
- 원본 파일을
document_attachments(kind=original)로 저장 - 형식별 파서로 텍스트/표 추출 →
parsed.md+ 표 CSV - 청킹 · 임베딩 · 온톨로지 추출 · 엔티티 해소 · 그래프 반영
- 검색 / Q&A 및 첨부 다운로드 API로 이용
4. 데이터 모델 요약
마이그레이션: 001_relational.sql, 002_age_graph.sql, 003_attachments.sql
관계형 (SQL SoT)
- 문서 계층: documents → versions → sections → chunks (+ embeddings)
- 온톨로지: classes, relations, candidates(검수)
- 지식: entities, mentions, entity_relations, entity_embeddings
- ACL: principals, document_acls
- 잡/캐시: ingestion_jobs, query_cache, entity_merge_audit
- 첨부: document_attachments
AGE kms_graph
Vertex Document, Section, Chunk, Entity, Class
Edge HAS_SECTION, HAS_CHUNK, MENTIONS, INSTANCE_OF, RELATED_TO + 도메인 elabel
Core 온톨로지 시드
Class: Person, Organization, Location, Policy, Product, Event, Concept, Technology
Relation: PART_OF, LOCATED_IN, WORKS_AT, OWNS, REGULATES, USES, DEPENDS_ON (+ RELATED_TO last-resort)
검색 버전 계약: 항상
chunks.version = documents.current_version 이고
status = 'active' 인 청크만 검색 대상입니다.
5. 소스·문서 구조
docs/
README.md # 설계 인덱스
01-hybrid-kms-architecture.md # 핵심 설계서 (~1,700줄, v0.2.1)
src/
main.py # FastAPI lifespan, worker, / /manual /summary
api/routes.py # REST API
core/ # config, db pool, security, textutil
llm/ # embeddings + chat (OpenAI/Anthropic)
repositories/graph.py # AGE 투영 · health
services/
auth/ acl/ ingestion/ ontology/ retrieval/ qa/
workers/ingest_worker.py # queued job 폴링
public/ # 웹 UI + 매뉴얼 + 본 요약
migrations/ # 001 relational · 002 AGE · 003 attachments
storage/ # 원본 · parsed.md · 표 CSV
scripts/ # migrate.sh · seed_sample.sh
주요 문서
| 경로 | 역할 |
|---|---|
README.md | 운영·실행 요약 |
docs/01-hybrid-kms-architecture.md | 아키텍처·스키마·검색·보안·PR Plan |
| /manual | 설계 사상 HTML (Mermaid 포함) |
| /summary | 본 분석 요약 (현재 페이지) |
| /api/docs | OpenAPI UI |
6. 구현된 API (/api/v1)
| 영역 | 엔드포인트 |
|---|---|
| 상태 | GET /health, /me, /stats |
| 문서 | POST/GET/DELETE /documents, chunks, parsed, attachments |
| 잡 | GET /jobs/{id} |
| 검색 | POST /search (Hybrid, LLM 없음) |
| Q&A | POST /qa (retrieval + optional LLM) |
| 온톨로지 | classes / relations / candidates 조회 |
| 엔티티 | list / detail |
7. Hybrid 검색 파이프라인
| Stage | 동작 |
|---|---|
| A | BM25 (simple FTS + unaccent) + Dense (HNSW, ACL oversample) |
| B | 엔티티 링크 → hop 0–2 그래프 확장 → graph_score 정렬 청크 |
| C | 가중 RRF (w_dense=1.1, w_bm25=0.7, w_graph=1.0, k=60) + ACL 재검증 |
| D | Q&A — LLM 없으면 검색 스니펫 폴백 |
주요 Key Decisions (설계)
- 단일 Postgres + openCypher (AGE)
- RRF 융합; Cypher는 agtype 파라미터만 (injection 방지)
- 엔티티 해소: exact/alias → trgm+cosine, class hard-filter
- Auth v1: API Key; OIDC는 v1.1
- 청크: 512 tokens, overlap 12%
- 한국어: dense 가중치 ≥ BM25
성능 목표 (설계)
| 경로 | 목표 |
|---|---|
| Hybrid search p95 | < 500ms (튜닝 후, LLM 없음) |
| Q&A p95 | < 5s (LLM 포함) |
| 10p PDF ingest | 전형적으로 < 60s |
8. 설계 vs 현재 구현
아키텍처 골격은 동작하는 MVP 수준이며, 일부 운영·평가 항목은 설계 단계에 가깝습니다.
| 항목 | 설계 | 현재 구현 |
|---|---|---|
| Job 큐 | Redis + ARQ/Celery 권장 | DB 폴링 FOR UPDATE SKIP LOCKED |
| 임베딩 | bge-m3 등 프로덕션 모델 미정 | hashing-v1 로컬 deterministic |
| 테스트 / eval | PR-12 등 계획 | tests/ 비어 있음 |
| 온톨로지 admin write | approve + create_elabel | 조회 위주 |
| 수집·Hybrid 검색·ACL·첨부·Q&A | 전체 파이프라인 | MVP 연결됨 |
Non-goals (v1)
- 실시간 협업 편집
- 무검수 온톨로지 자동 진화
- Leiden community (Phase 2)
- LangChain 등 프레임워크 런타임 코어 의존
다음 단계 (설계 PR Plan 기준)
- 프로덕션 임베딩 모델 고정 (KD-13)
- 평가 / ACL recall 테스트
- 온톨로지 승인 API 강화
- 성능 튜닝 (PR-12)
- (선택) Leiden community summaries
9. 운영 · 접속
| 항목 | 값 |
|---|---|
| UI 앱 | https://kms.engineerstory.kr/ |
| 본 분석 요약 | /summary |
| 설계 매뉴얼 | /manual |
| OpenAPI | /api/docs |
| Health | /api/v1/health |
| 로컬 실행 | .venv/bin/uvicorn src.main:app --host 127.0.0.1 --port 8020 |
| systemd | kms-api |
| API 키 env | KMS_DEFAULT_API_KEY (프로덕션에서 교체) |
보안: 개발 기본 API 키를 프로덕션에 두지 마세요.
그래프에는 ACL이 인코딩되지 않으므로, 검색 Stage C 이후 청크 ID 재검증이 필수입니다.
정리
이 저장소는 “단일 Postgres 위에서 문서 KMS + HybridRAG를 통제된 온톨로지로 운영한다”는 설계와, 그에 맞춘 FastAPI 구현체가 함께 있는 프로젝트입니다.
- 문서: 아키텍처·스키마·검색 알고리즘·보안·PR Plan까지 상세
- 코드: 업로드 파이프라인, 다중 포맷 파서, Hybrid 검색, Q&A, AGE 투영, 웹 UI까지 MVP 연결
- 갭: 평가 스위트, 프로덕션 임베딩, 온톨로지 관리 write, 부하 튜닝