OpenSQL 기반 AI 문서 검색·벡터 데이터 플랫폼

2026 오픈소스 개발자대회 — 티맥스티베로 지정과제 문서를 업로드하면 AI가 자동으로 읽고(임베딩), 바뀌면 알아서 갱신하고(변경 로그 동기화), 어떤 AI든 표준 규격(MCP)으로 검색해 쓸 수 있는 무중단 문서 관리 플랫폼.

무엇을 해결하나

기업이 쌓아 둔 문서는 세 가지 이유로 AI 검색에 잘 붙지 않는다.

1. 형식이 제각각이다. PDF·DOCX·HWP가 섞여 있고, 특히 HWP는 국내 공공·대학 문서의 사실상 표준인데 파싱 도구가 마땅치 않다.

2. 문서는 계속 개정된다. 규정집 하나가 매년 바뀌는데 벡터 인덱스를 사람이 손으로 다시 맞춰야 한다면 운영이 불가능하다.

3. 검색 결과를 아무 AI나 쓰지 못한다. 시스템마다 전용 API를 새로 만들어야 한다.

4. 문서가 곧 기밀이다. 규정집·계약서·인사자료가 DB에 평문으로 쌓이면 DB 파일 유출이 곧 문서 유출이다.

이 프로젝트는 업로드부터 검색까지 전 과정을 자동화하고, 검색 인터페이스를 MCP 표준으로 노출한다. 저장소는 고가용성 DB인 Tmax OpenSQL이며, 문서 본문은 국산 표준 암호 ARIA-256으로 DB 안에서 암호화한다. 로컬 개발은 동일 계열인 PostgreSQL 16 + pgvector로 한다.

DB가 죽어도 멈추지 않는다. Patroni가 PostgreSQL을 자동으로 되살리고(실측 RTO 9.73초), 그 동안 앱은 재접속을 시도하며 버틴다. 서비스는 전 계층이 상시 구동으로 등록돼 재부팅 후 사람 개입 없이 복귀한다.

Related MCP server: PDFDashboardWithMCP

아키텍처

데이터 흐름 (CRUD)

문서 하나가 시스템에서 겪는 일을 CRUD로 나눠 보면 이렇다. 네 갈래 모두 같은 변경 로그(CDC)를 거친다 — 업로드든 개정이든 삭제든 워커가 보는 입구는 하나다.

flowchart LR
    subgraph client["클라이언트"]
        U["사용자"]
        AI["AI 클라이언트<br/>(MCP)"]
    end

    subgraph create["C · 생성"]
        C1["POST /documents"]
        C2["파서<br/>PDF·DOCX·HWP→텍스트"]
        C3["버전 INSERT<br/>status=pending"]
    end

    subgraph update["U · 개정"]
        U1["POST /documents/{id}/versions"]
        U2["내용 해시 비교<br/>같으면 건너뜀"]
        U3["새 버전 INSERT<br/>이전 버전 보존"]
    end

    subgraph delete["D · 삭제"]
        D1["DELETE /documents/{id}"]
        D2["CASCADE<br/>버전·청크 제거"]
    end

    subgraph read["R · 조회"]
        R1["GET /search<br/>MCP search_documents"]
        R2["질의 임베딩 → 벡터 검색<br/>절대 하한 + 상대 컷"]
        R3["GET /documents · /changelog"]
    end

    CDC[["변경 로그 (CDC)<br/>insert · update · delete"]]
    W["임베딩 워커<br/>청킹 → BGE-M3 → 청크 저장"]
    DB[("OpenSQL<br/>pgvector · ARIA 암호문")]

    U --> C1 --> C2 --> C3 --> CDC
    U --> U1 --> U2 --> U3 --> CDC
    U --> D1 --> D2 --> CDC
    CDC --> W --> DB
    AI --> R1 --> R2 --> DB
    U --> R3 --> DB
    DB -.->|"본문 변경 감지"| CDC

읽기만 워커를 거치지 않는다. C·U·D는 변경 로그를 남기고 워커가 비동기로 처리하며, R은 DB를 직접 조회한다. 그래서 업로드 응답이 임베딩을 기다리지 않는다 — 버전 행을 pending으로 넣고 즉시 응답하고, 워커가 끝내면 ready가 된다.

무중단 구조

flowchart TB
    subgraph mac["개발·앱 계층 (macOS, LaunchAgent 상시 구동)"]
        API2["FastAPI :8000<br/>/health 자기 진단"]
        WK["임베딩 워커<br/>BGE-M3 (Apple GPU)"]
    end

    subgraph vm["DB 계층 (Rocky Linux 9.7 VM, systemd 상시 구동)"]
        PAT["Patroni<br/>장애 감지·자동 재기동"]
        PG[("PostgreSQL 17.8<br/>+ pgvector · opencrypto")]
        ETCD["etcd<br/>클러스터 상태"]
        PROXY["OpenProxy<br/>커넥션 풀"]
    end

    API2 -->|"재접속 재시도<br/>지수 백오프"| PG
    WK -->|"동일"| PG
    PAT -->|감시·복구| PG
    PAT <--> ETCD
    PROXY -.->|"HA 전환 시 사용 예정"| PG

DB가 죽어도 앱이 함께 죽지 않는다. Patroni가 PostgreSQL을 되살리는 동안(실측 9.73초) 앱은 지수 백오프로 재접속을 시도하며 버틴다. 임베딩 모델은 재접속과 무관하게 메모리에 남아 재로딩 비용이 없다.

현재 상태

OpenSQL 위에서 전 구간이 동작한다. 2026-07-30 기준 실제 OpenSQL(single 모드)에 배포해 파이프라인·암호화·자가복구를 모두 실측 검증했다.

검증 결과

uv run pytest
114 passed, 6 skipped

스킵 6건은 실모델(RUN_MODEL_TESTS=1)·코퍼스·opencrypto 게이트로, 해당 리소스가 있는 환경에서만 실행된다.

실측값 (OpenSQL VM, 2026-07-30)

회귀 방지 테스트 — 모두 실제로 발생했던 문제를 막기 위해 추가됐다.

검색 품질

두 단계로 거른다.

1. 절대 하한 0.47 — 질의 자체가 문서와 무관하면 빈 결과를 준다. 없는 내용에 그럴듯한 오답을 주는 것보다 없다고 답하는 게 정직하다.

2. 상대 컷 80% — 1위와 격차가 큰 꼬리를 잘라낸다.

하한값은 질의 30개로 측정해 정했다.

0.47~0.48이 완전 분리 구간이며 정상 질의 쪽에 여유를 둬 0.47을 택했다. 코퍼스가 바뀌면 분포도 바뀌므로 SEARCH_MIN_SCORE로 조정할 수 있다.

상대 컷만으로는 무관 질의를 막을 수 없다 — 무관 질의도 top_k를 채우고 그 안에서는 점수가 서로 비슷해 비율 검사를 통과한다("김철수 연락처"가 0.2550/0.2479로 97% 비율을 만족해 2건 반환됐다).

OpenSQL 고유 기능 활용

순정 PostgreSQL로 대체할 수 없는 것을 쓴다.

암호화는 검색을 막지 않는다. 유사도 계산은 embedding 컬럼만 보므로 본문이 암호문이어도 벡터 검색이 정상 동작한다.

한계 (과장하지 않는다): 주장할 수 있는 것은 "DB가 유출돼도 문서 내용을 읽을 수 없다"까지다. 임베딩 벡터·파일명·내용 해시는 평문으로 남으므로 "어떤 문서가 있는지 알 수 없다"는 성립하지 않는다. 상세는 설계 문서에 적었다.

기술 스택

시작하기

1. 의존성 설치

git clone https://github.com/4thIS/opensource_contest_tmax.git
cd opensource_contest_tmax
uv sync                      # uv 필요: https://docs.astral.sh/uv/

2. 환경 설정 — 암호화 키 (필수)

문서 본문은 암호화해 저장하므로 키 없이는 업로드가 실패한다.

cp .env.example .env
openssl rand -base64 32        # 출력값을 .env의 DOC_ENC_KEY에 넣는다

키를 잃어버리면 저장된 모든 문서를 영원히 복구할 수 없다. 백업도 소용없다 — 암호문만 남기 때문이다. 키는 DB에 저장되지 않으며, 그래야 DB가 통째로 유출돼도 복호화가 불가능하다. 안전한 곳에 따로 보관할 것.

.env는 .gitignore가 커밋을 차단하고, pre-commit 훅이 키 문자열을 감지해 한 번 더 막는다. 훅은 클론마다 한 번 활성화해야 한다.

git config core.hooksPath .githooks

3. 로컬 개발 DB 기동

호스트 포트는 5436을 쓴다. 5432는 다른 PostgreSQL과 충돌하기 쉽다.

docker run -d --name opensql-dev \
  -e POSTGRES_PASSWORD=dev -p 5436:5432 \
  pgvector/pgvector:pg16

docker exec opensql-dev psql -U postgres -c "CREATE DATABASE opensql_doc"

로컬은 pgcrypto + AES-256으로 동작한다. OpenSQL 배포에서는 DOC_CIPHER_ALGO=aria256으로 국산 표준 암호로 전환한다 — 함수 시그니처가 같아 코드 변경이 없다.

4. 스키마 적용

export DATABASE_URL="postgresql://postgres:dev@localhost:5436/opensql_doc"
uv run python -c "from core.db import get_conn, init_schema; init_schema(get_conn())"

core/schema.sql은 멱등이라 반복 적용해도 안전하다.

이전 버전으로 만든 DB가 있으면 재시딩이 필요하다. 스키마가 CREATE TABLE IF NOT EXISTS라 이미 있는 테이블의 컬럼 타입(TEXT → BYTEA)이 바뀌지 않는다. 그 상태로 쓰면 업로드는 성공하는데 워커만 조용히 죽는다.

psql "$DATABASE_URL" -c "DROP VIEW IF EXISTS latest_ready_versions;
  DROP TABLE IF EXISTS change_log, chunks, document_versions, documents CASCADE;"

5. 테스트

uv run pytest

Windows 초기 세팅은 docs/PROMPTS.md 하단을 참조한다.

실행

세 프로세스를 각각 띄운다. .env에 DATABASE_URL과 DOC_ENC_KEY를 넣어 두면 --env-file로 한 번에 넘길 수 있다 — 키를 명령줄에 노출하지 않는 방법이기도 하다.

백엔드 API — http://127.0.0.1:8000

uv run --env-file .env uvicorn core.api:app --host 127.0.0.1 --port 8000

임베딩 워커 — 변경 로그를 폴링한다 (기본 3초, WORKER_INTERVAL로 조정)

uv run --env-file .env python -m core.worker

DB가 재시작되거나 페일오버가 일어나도 워커는 죽지 않는다. 지수 백오프로 재접속하며 버티고, 임베딩 모델은 메모리에 남아 재로딩하지 않는다.

여러 개를 띄워도 안전하다 — FOR UPDATE SKIP LOCKED로 같은 이벤트를 중복 처리하지 않는다(테스트로 검증). 다만 워커마다 임베딩 모델을 로드하므로 메모리 여유를 확인할 것.

MCP 검색 서버 — stdio

claude mcp add opensql-doc \
  -- uv run --env-file .env python -m core.mcp_server

상태 확인

curl -s http://127.0.0.1:8000/health | python3 -m json.tool

DB가 죽었으면 503 unavailable, 워커가 멈췄으면 503 degraded를 준다 — 둘을 구분해 알려주므로 무엇을 재기동해야 하는지 알 수 있다.

CDC 시연 스크립트 — 업로드 → 개정본 반영 → 검색 결과 변화를 6단계로 보여준다

--env-file .env가 필수다 — uv는 .env를 자동으로 읽지 않는다. 빼면 DOC_ENC_KEY 미설정으로 업로드 단계에서 죽고, DATABASE_URL 대신 스크립트 기본 DSN(로컬 5436)에 붙는다.

uv run --env-file .env python scripts/demo_cdc.py                         # 내장 샘플 문서
uv run --env-file .env python scripts/demo_cdc.py 규정.hwp 규정_개정.hwp --no-pause

API

업로드는 50MB 상한, 확장자 화이트리스트(pdf·docx·hwp·txt), 경로 조작 문자 차단을 거친다. 원본 파일은 파싱 직후 삭제하며 보관하지 않는다.

삭제는 하드 삭제다. 다만 변경 로그는 남는다 — change_log에 version_id 외래키를 걸지 않은 것이 이 때문이며, 이미 삭제된 버전 id를 감사 기록으로 보존한다.

MCP 도구

테스트

테스트 픽스처는 테이블을 DROP하므로 데모와 분리된 전용 DB를 쓴다. tests/conftest.py가 TEST_DATABASE_URL 기본값을 opensql_test로 선점하고, 그 DB가 없으면 자동 생성한다.

다른 DB를 쓰려면 환경변수로 덮어쓴다. 데모 DB를 가리키면 test_db_isolation.py가 실패한다.

TEST_DATABASE_URL="postgresql://postgres:dev@localhost:5436/other" uv run pytest

DB 서버가 떠 있지 않으면 DB 의존 테스트는 자동으로 skip된다.

OpenSQL 배포

배포 완료. Rocky Linux 9.7 VM에 single 모드로 설치해 운영 중이다.

• 지원 환경은 x86_64 Linux 전용이다 (Rocky·RHEL·Oracle·AlmaLinux 8·9, Ubuntu 22.04·24.04). 대회 지급 패키지는 Rocky Linux 9.7 전용 빌드다. macOS·ARM은 지원 목록에 없어 Apple Silicon 개발 머신에서는 x86_64 리눅스 VM을 거친다.

• etcd·Patroni·OpenProxy를 systemd 서비스로 등록해 VM 재부팅 후 자동 기동한다. 통합 인스톨러 기본값은 etcd만 systemd로 등록하므로 별도 설정이 필요하다.

• 라이선스는 Patroni가 도는 노드마다 1개가 필요하고 hostname·CPU 수에 묶인다. 대회 지급분이 1개이므로 single 모드이며, 따라서 노드 간 자동 페일오버는 검증하지 못했다 — 증명한 것은 프로세스 수준 자가복구(kill -9 → Patroni 자동 재기동, RTO 9.73초)까지다.

• 앱은 현재 PostgreSQL에 직결한다. OpenProxy 경유는 HA 구성(2노드 이상) 시점에 전환할 예정이다.

백업·복구 (barman PITR)

자가복구는 "프로세스가 죽어도 살아난다"까지다. 사람이 지운 데이터는 되살리지 못한다 — 그래서 시점 복구를 붙였다. 패키지에 포함된 barman 3.11.1을 쓴다.

스트리밍 방식을 택했다. rsync·archive 방식은 archive_command를 바꿔야 하는데 그 파일은 Patroni가 관리한다. 스트리밍은 복제 슬롯만 쓰므로 클러스터 설정을 건드리지 않는다. (현재 archive_command는 Patroni 기본값 /bin/true, 즉 실제 보관은 barman의 pg_receivewal이 전담한다.)

barman check opensql        # 20개 항목 전부 OK
barman backup opensql       # 50.4 MiB / 5초
barman recover --target-name <복구지점> opensql latest <디렉토리>

실제로 복구되는지 확인했다. 복구 지점을 만들고 → DROP TABLE documents CASCADE로 파괴 → 백업에서 별도 디렉토리로 복구 → 격리 포트(5433)로 기동 → 문서 1건·버전 1건·청크 15건이 그대로 돌아왔고, 본문은 여전히 ARIA 암호문이었다(복구가 암호화를 훼손하지 않는다). 복구본의 archive recovery complete LSN이 목표 지점과 일치했다.

Patroni와 함께 쓸 때 걸린 것 두 가지 — 둘 다 재기동 시 조용히 사라져서, 백업이 도는 줄 알았는데 안 도는 상태가 된다.

조치 후 kill -9로 다시 검증했다 — 슬롯·pg_hba·barman check 모두 유지됐고 RTO는 4.86초였다.

복구본을 OpenSQL 바이너리로 기동하려면 OPENSQL_LICENSE_PATH 환경변수가 필요하다(라이선스 검증 모듈이 shared_preload_libraries에 있다). 이걸 빠뜨리면 license is invalid로 기동이 실패한다.

임베딩 모델(BGE-M3)은 VM이 아니라 개발 머신에서 돌린다. VM은 x86 에뮬레이션이라 연산이 네이티브의 1/1000 수준(실측 0.77 GFLOPS vs 837 GFLOPS)이어서 모델 추론에 적합하지 않다. 라이선스가 묶는 대상은 DB뿐이므로 이 분리는 규정상 문제가 없다.

디렉토리 구조

core/       임베딩 파이프라인 · DB 스키마 · CDC 동기화 · 암호화 · 검색 API · MCP 서버
parser/     문서(PDF/DOCX/HWP) → 텍스트 추출 모듈
docs/       모듈 계약(INTERFACES) · 프롬프트 가이드(PROMPTS) · 라이선스 목록(THIRD_PARTY)
  superpowers/  설계 문서(specs) · 구현 계획서(plans)
scripts/    CDC 시연 스크립트
tests/      pytest 테스트
.githooks/  pre-commit — 비밀정보·벤더 패키지 커밋 차단

모듈 간 계약은 docs/INTERFACES.md에 정의한다. core/ 내부 설계는 core/SCHEMA.md, core/EMBEDDING.md, core/API.md, core/MCP.md에 있다.

로드맵

• 팀 규칙·모듈 계약·개발 가이드 문서화

• 문서 파서 (parser/) — PDF · DOCX · HWP

• 업로드 API + 자동 임베딩 파이프라인 (core/)

• 메타데이터·버전 스키마 + pgvector 저장

• 변경 로그(CDC) 기반 재임베딩 동기화

• MCP 검색 서버 + 검색 데모 UI

• 테스트 DB 격리 — 데모 데이터 보호

• OpenSQL 배포 — Rocky 9.7 VM, single 모드

• ARIA-256 문서 암호화 — opencrypto (순정 PostgreSQL로 재현 불가)

• 감사 로그 — pgaudit (write, ddl, role)

• 자가복구 — Patroni 자동 재기동 + 앱 재접속 (RTO 9.73초 실측)

• CRUD 완성 — 삭제 API + 헬스체크

• 검색 품질 — 무관 질의에 오답 반환 차단

• 하이브리드 검색 — 정확 참조("제25조")·고유명사 보강. 본문이 암호화돼 키워드 검색이 불가능하므로 BGE-M3 sparse 벡터 + pgvector sparsevec이 유일한 경로다

• 재색인 — 모델·청킹 전략 변경 시 기존 문서 재처리

• 버전 diff — 개정본에서 무엇이 바뀌었는지 제시 (API + MCP 도구)

• 노드 간 페일오버 — 라이선스 추가 확보 시 2node-witness 전환

• 백업·복구 — barman PITR (DROP TABLE → 시점 복구 실증, 백업 5초·복구 4초)

• 권한 반영 검색 — 부서·기밀등급별 결과 차등

팀

라이선스

MIT. 사용한 외부 라이브러리와 라이선스는 docs/THIRD_PARTY.md에 기록한다. 탑재 AI 모델은 오픈웨이트(가중치 공개·로컬 구동) 모델만 사용한다.