RagService 구현·검증 보고서

검증일: 2026-08-25 GMT+9
대상 브랜치: feat/private-document-pipeline
검증 기준 커밋: 0f3d42f

완성 범위

RagService는 PortalConsole의 서명 identity와 FileStore의 원본 수명주기를 전제로 동작하는 독립 B2B private RAG data plane이다. 브라우저가 tenant·조직·clearance를 제출하거나 변경하지 못하며, 서버가 Directory JWT를 검증한 뒤 요청별 PostgreSQL transaction 안에서만 SET LOCAL을 적용한다. RLS가 vector/keyword 후보를 제거한 이후에만 RRF와 LLM context가 실행된다.

영역	구현 결과	핵심 산출물
격리형 인프라	PostgreSQL 16 custom image, pgvector 0.7, pg_bigm, mecab-ko/textsearch_ko, local BGE-M3, Ollama/vLLM GPU profile, optional vision/CDC/evaluation profile	`infra/postgres/`, `services/local_embedding/`, `docker-compose.offline.yml`
RLS·lifecycle	FORCE RLS, non-superuser `rag_app`, tenant/org/clearance/admin GUC, RRF, source/checksum replacement, parent-delete cascade	`10-b2b-rag-rls.sql`, `db_context.py`, `offline_ingestion.py`
문서 parser	PDF 표 Markdown/HTML merge, HWPX native XML, isolated HWP adapter, DOCX/XLSX/PPTX/ODF/CSV/HTML/RTF/OCR 및 legacy Office/general adapters	`structured_parser.py`, `document_pipeline.py`, `layout_parser.py`
Semantic Chunking·ingestion	Markdown H1/H2/H3 semantic split, trusted org/security/creator/hash injection, async embedding retry, COPY lifecycle	`chunking.py`, `async_ingestion.py`, `indexing.py`
질문·답변	1024-dimension async embedding, JWT-derived RLS RRF top-5, context-only SSE response validation	`api.py`, `repository.py`, `streaming_chat.py`
PII·감사·관측성	regex + optional internal KoBERT NER redaction, immutable masked audit, private Phoenix profile	`pii_guardrail.py`, `audit.py`, `infra/observability/`
실시간 CDC	wal2json logical slot peek→target commit→advance, board insert/update reindex, delete parent/cascade purge	`cdc.py`, `infra/postgres/cdc/`
품질 평가·튜닝	RLS registry sample, internal vLLM Ragas evaluator, isolated 300/500/1000 chunk profile, approval-gated runtime setting	`evaluation.py`, `evaluation_runner.py`, `Dockerfile.evaluation`
관리자 운영	RRF/pipeline policy, work manifest, parser·vision·PII·audit·CDC status, Ragas candidate approval panel	`web/admin/`, `admin_settings.py`

가드레일은 database 권한 제어를 대체하지 않는다. PII redaction, output validation, audit은 defense-in-depth 계층이며 권한 제외는 PostgreSQL FORCE RLS가 담당한다.

요청별 RLS와 동일 질문 권한 검증

tests/test_rag_pipeline.py는 기획팀 CONFIDENTIAL 사용자와 인사팀 INTERNAL 사용자가 동일 질문인 **“올해 연봉 조정 가이드라인은 어떻게 돼?”**를 보낼 때, database session binding/RRF/guardrail 경계를 확인한다.

사용자	검색 context	응답 계약	검증
기획팀 A, `CONFIDENTIAL`	기획 승인 문서만 반환	허가 context 기반 answer/citation	통과
인사팀 B, `INTERNAL`	0개	정확히 `관련 사내 정보를 찾을 수 없습니다.`	통과
source replacement	기존 child vector 0개	lifecycle event와 parent cascade	통과

실행계획 audit log는 1024 value 전체를 [1024-dimension embedding redacted]로 치환한다. raw query/context는 audit table과 관리자 화면에 저장·노출하지 않고 masking snapshot과 fingerprint만 남긴다.

확장 parser·vision 경계

PDF high-end path는 page image/word/table bounding box를 읽기 순서대로 정렬한다. table은 완전히 빈 행·열만 제거한 뒤 ragged row를 padding하고 Markdown/HTML 구조를 본문 stream의 위치에 병합한다. figure/chart는 private allow-list vision endpoint에만 전달되며 caption 및 수치 JSON은 schema 검증이 실패하면 저장하지 않는다.

HWPX는 native XML 구조를 읽는다. binary HWP는 application runtime에 pyhwp를 결합하지 않고, 배포 책임자가 license를 검토한 isolated hwp5html adapter를 별도 제공할 때만 활성화한다. .doc/.xls/.ppt는 isolated LibreOffice conversion이 구성된 환경에서만 처리하며, TSV/JSON/JSONL/XML/YAML/INI/EML은 structured text adapter를 사용한다.

CDC·평가 운영 경계

CDC listener는 source PostgreSQL publication과 wal2json plugin을 사용한다. target lifecycle/COPY transaction 및 embedding이 성공한 뒤에만 slot LSN을 advance하므로 downstream failure가 event loss로 이어지지 않는다. source server에는 wal_level=logical, replication slot/sender capacity, dedicated replication role 및 WAL lag monitoring이 필요하다. [1] [2]

Ragas job은 API image와 분리된 Python 3.11 evaluator image에서 실행한다. registry 표본 question/reference 생성과 judge call은 internal vLLM OpenAI-compatible endpoint에만 보낸다. 300/1000 chunk size 평가는 production index를 변경하지 않고 같은 registry snapshot에서 만든 isolated reindex profile DB를 필요로 한다. 추천값은 CANDIDATE로 저장되고, reindex가 필요 없는 retrieval-only profile만 Directory admin 승인 후 runtime setting으로 적용한다. Ragas metric contract는 context ranking, claim grounding, answer relevance를 분리해 평가한다. [3] [4]

재현한 검증 결과

검증	결과
Python 문법	`python3 -m compileall -q ragcenter services scripts tests` 성공
전체 기본 test suite	`python3 -m unittest discover -s tests -p 'test_.py'` → 55 tests OK, 2 skipped*(python:3.11 컨테이너 `ragtest`, 저장소 `/app` 마운트)
공용 버킷(전사 공지) RLS	실제 PostgreSQL 16 + pgvector 0.7 임시 DB에서 이 저장소 DDL·정책을 그대로 적용해 4 시나리오 확인 — ① 같은 테넌트 다른 조직 사용자가 자기 조직 + 공용 버킷 3건 ② 공용 GUC 미설정이면 1건(공용 미노출) ③ 등급 PUBLIC이면 공용 PUBLIC 문서만 1건(공용 버킷에도 등급 조건 적용) ④ 다른 테넌트는 자기 문서 1건(공용 버킷이 테넌트를 넘지 않음). 모두 기대값 일치, 전 구문 `ROLLBACK`(운영 데이터·정의 무변경)
선택적 skip	legacy ProcessCenter Compose copy test와 local external runtime 의존 test는 명시 환경 변수에서만 실행
parser·layout·PII·CDC·evaluation	title chunking, general format adapter, PDF layout/vision contract, PII masking/audit, CDC LSN acknowledgement, tuning candidate unit tests 통과
JWT API·admin API	forged RLS header 거부, signed claim principal, advanced operations summary admin scope test 통과
fresh PostgreSQL schema	extensions `vector`, `pg_bigm`, `textsearch_ko`; evaluation/runtime tables FORCE RLS; `rag_app` transaction insert과 commit 뒤 GUC clear 확인
admin UI	Python 3.11 image의 browser preview에서 advanced operations/tuning layout과 secret·raw query/context 미노출 확인

vLLM model weights와 isolated 300/500/1000 profile DB는 이번 sandbox에 provision하지 않았다. 따라서 actual vLLM Ragas score 및 multi-profile benchmark는 on-prem staging에서 local model cache를 준비한 뒤 실행해야 한다. 코드·Compose·schema·unit contract는 검증했지만, 운영 score를 임의로 만들거나 production parameters를 자동 적용하지 않는다.

배포 전 확인사항

온프레미스 Compose가 GPU/model cache/custom PostgreSQL extension/internal network를 모두 제공하므로 primary deployment target이다. 관리형 클라우드에는 API/admin container를 배포할 수 있으나, GPU, mounted model cache, pg_bigm/mecab image, logical decoding plugin과 source replication network는 별도로 제공·검증되어야 한다. API와 admin UI만 cloud에 두는 경우에도 vector DB 및 private inference endpoint의 network boundary는 유지해야 한다.

아키텍처 그림은 ARCHITECTURE_STACK.md와 docs/assets/ragcenter-architecture-stack-standalone.png에 있다. CDC와 evaluator의 실행 절차는 각각 POSTGRES_CDC_BOARD_POSTS.md, RAGAS_EVALUATION_TUNING.md에 정리했다.