건설도면 실환경 전환 아키텍처 설계서 (D-1, 초안 v0.1)
| 항목 | 내용 |
|---|
| 작성일 | 2026년 11월 14일 |
| 지위 | 초안(가설 병기) — 11 검토의 미결정 변수(실서비스 구성·모델 환경·실적 DB)는 가설 H1~H3으로 두고, 응답 도착 시 확정한다 |
| 근거 | 로컬 하이브리드 실증 전체(06 보고서) — 수치 인용은 모두 실측 |
| 원칙 | 설계 문서 원칙(01 실행계획 4.3절): 실증 없는 구성요소는 표시하고 검증 계획을 함께 둔다 |
1 목적·범위
- 목적: 로컬 하이브리드(AWS 에뮬레이터 + 로컬 엔진)에서 실증된 파이프라인을 실 AWS 환경으로 이행하기 위한 목표 아키텍처와 이행 순서의 확정.
- 범위: 관리형 OpenSearch, 저장·이벤트(S3/SQS), 관계형 DB, 모델 서빙, 앱 컴포넌트(소비자·검사기·탐색), 권한, 운영 요건, 이행.
- 범위 밖: 실데이터 품질 실험(T21 확장·D-3), 다단계 질의 대량 트래픽(그래프 제품 채택은 미채택 기록 유지).
2 목표 아키텍처 개요
[원본] S3 원본 버킷(sha256 체크섬, T07)
│ (변경 감지: EventBridge 규칙 — 로컬 실증은 수동 이벤트, 실환경은 S3 이벤트 → SQS)
▼
[적재 배치] ①추출(OCR/파서) ②임베딩 ③BM25+벡터 적재(v{N} 인덱스) ← 컴퓨팅: ECS/Fargate 태스크
▼
[검색] 관리형 OpenSearch 도메인 — 별칭 seachdog_units_current (원자 전환)
│ k-NN(lucene 엔진) + BM25 + 하이브리드(정규화 파이프라인)
▼
[선별·검증] ④LLM 선별(17.5절 검증) ⑤kev grounding(신뢰도 임계 0.5)
▼
[관계 게이트] ⑥T24 제약 검사(규칙 v2) → ⑦관계 판 게시(pass만)
▼
[게시] v{N+1} reindex + 별칭 원자 전환(이전 판 보존)
▼
[동기화] ⑧SQS 하류 이벤트 → 소비자(멱등 원장·시효 판정) — manifest 배치 지원
│
├─ [탐색] T25 경로 탐색(앱 탐색) — 관계 인덱스에서 근거 추적 답변
└─ [실적 질의] RDS PostgreSQL — 템플릿 사전·제한 역할(T26 3층 방어)
[공통] 원장(seachdog_event_ledger)·기준 개체판·관계 사전 — OpenSearch/KMS/Secrets Manager
앱 컴포넌트(①~⑧)는 로컬에서 검증된 스크립트(local/)의 로직을 그대로 이식한다 — 각 단계의 검증 증거(통과율·실패 경로)는 §9 이행 시 회귀 기준이 된다.
3 컴포넌트 매핑 (로컬 실증 → 실환경)
| 기능 | 로컬 실증 | 실환경 대응 | 이식 근거(실측) |
|---|
| 원본 보관 | 에뮬레이터 S3 + sha256 | S3(버저닝·객체 잠금 옵션) + EventBridge | 체크섬 왕복 실증 |
| 검색 엔진 | 로컬 OpenSearch 2.13(knn lucene) | 관리형 OpenSearch 도메인 [H1] | BM25·k-NN·별칭 원자 전환·하이브리드 phase_results_processors 전부 실증 |
| 배치 판 관리 | v{N} 인덱스 + 별칭 원자 전환 + reindex | 동일 패턴(관리형) | T27 18/18(전환·보존·판 고정) |
| 이벤트 | SQS 왕복 + 소비자(멱등·시효) | SQS + 소비자(ECS 서비스/Lambda) | 18/18+배치 7/7 |
| OCR | Tesseract 5.5 + 비전 비교 | 형식별 파서 선택은 D-3(샘플 수령 후) — 초기는 Tesseract | 정상/오인식 기록 방식 실증 |
| 임베딩 | Ollama bge-m3(1024차) | Bedrock Titan/자체 서빙 [H2] | 한국어 5/5 vs nomic 3/5, 지연 212ms |
| LLM 선별 | llm-gateway→Ornith-9B | Bedrock Converse/자체 vLLM [H2] | 3초·정확·17.5절 검증 통과 |
| 근거 검증 | kev-9b(System One, 8009) | 자체 GPU 서빙 유지(관리형 대응 없음 → 자체 호스팅 필수) | 3-way 정판·저신뢰 보류 실증 |
| 제약 검사(T24) | t24-check(코드·JSON) | 앱 컴포넌트(컨테이너) — 변경 없음 | v1 13/13 + v2 4/4 |
| 관계 판/탐색(T25) | relations_pub + 앱 탐색 | OpenSearch 인덱스 + 앱(그래프 제품 미채택) | 18/18 |
| 실적 질의(T26) | PG18 + 템플릿 실행기 | RDS PostgreSQL + 동일 실행기 | 12/12(3층 방어) |
| 원장·기준판 | OpenSearch 문서 | 동일(+KMS 암호화, 스냅샷) | 해시·버전 기록 실증 |
4 가설 (응답 도착 시 확정 — B 질의서와 1:1 대응)
| 가설 | 내용 | 대안 | 확정 조건 |
|---|
| H1 | 관리형 OpenSearch 2.13 호환 구성, k-NN engine: lucene, fgac 미사용(도메인 정책+IAM) | fgac 사용(세부 역할 매핑 필요 — 검증 시나리오는 05 보고서 체인 준비됨) | 실서비스 버전·fgac 여부 응답(P-02) |
| H2 | 모델은 자체 서빙 유지(기존 llm-gateway→vLLM 토폴로지, kev는 자체 GPU 필수) | Bedrock 임베딩+LLM(선별만), kev만 자체 | 모델 호출 경로·권한·비용 응답(P-04) — 전환 시 T12/T14 비교 프로토콜 재실행 |
| H3 | 실적 DB는 RDS PostgreSQL 15+, T26 실행기·역할 패턴(sd_query류) 그대로 | 스키마가 타 엔진(예: Aurora MySQL)이면 템플릿 재작성 | 스키마·계정 응답(P-05) |
5 권한 체계 (설계 확정분 — 로컬 실증 패턴 이식)
| 계층 | 설계 | 실증 근거 |
|---|
| AWS IAM | 파이프라인 역할(적재·reindex·SQS 발행 분리), 사람은 읽기 전용 | 에뮬레이터 정책 강제 실증 |
| OpenSearch | 도메인 접근 정책(IAM 또는 fgac[H1]) + 색인/검색 역할 분리 | 05 보고서 정책 체인 |
| 앱 게이트 | LLM 응답 검증(17.5절)·kev 임계(0.5)·T24 규칙 — 권한과 무관하게 모든 경로에 적용 | 실패 경로 9/9 |
| RDS | 제한 역할(SELECT 전용·statement_timeout·읽기전용 세션) + 템플릿 사전 밖 질의 거부 | T26 12/12, RLS 필요 시 test-pg-rls 패턴 |
| 비밀 | 역할 암호는 Secrets Manager(런타임 발급) — 코드/스크립트에 평문 없음 | 로컬에서도 런타임 생성+.pgpass 패턴 유지 |
6 데이터 흐름 상세 (판·이벤트 계약)
- 판 관리: 적재/변경은 항상 새 판(v{N+1}) reindex 구성 → 별칭 원자 전환. 이전 판 보존(롤백 단위). 실행별 판 고정(전환 중 일관 조회) — 실증: T27 판 고정.
- 이벤트 계약:
{event_id, entity_id, source_version, operation, run_id, payload} — 소비자는 ①event_id 멱등(원장) ②source_version 시효 ③게이트(선별·grounding·T24) 후 적용. 실패·차단은 보류(reject 아님). manifest 배치는 부분 실패 지속+재실행 스킵. - 관계: 후보(T23 추출/수동) → T24(형식) → kev(사실성, 저신뢰 보류) → 승인만 relations_pub → T25 탐색. 사람 검수 칸(review_status)은 항상 분리.
7 모델 서빙 선택지 (H2 — 근거 병기)
| 항목 | 안A: 자체 서빙 유지(vLLM 게이트웨이+kev) | 안B: Bedrock(LLM·임베딩)+kev만 자체 |
|---|
| 실측 근거 | Ornith 선별 3초/정확, bge-m3 5/5, kev 3-way — 전부 이 구성으로 실증 | 에뮬레이터 Bedrock은 스텁 — 미실증 |
| 운영 | GPU 자원·패치 부담(기존 자산 활용) | 관리형(운영 최소), 호출 비용·리전 제약 |
| 전환 비용 | 없음(현행) | T12/T14 비교 프로토콜 재실행 필요(스크립트 준비됨) |
| 판정 | 초안 권고: 안A 유지 — 실증 자산 그대로, 비용·성능 데이터 확보 후 재검토 | 응답(비용·권한)에 따라 전환 가능 |
8 운영 요건 (D-2 런북의 입력)
- 용량 산정 근거(실측 프로파일): kNN-768 p50 3.7ms/195 ops·BM25 3.2ms/227 ops@10k건 단일 클라이언트(오류 0%) — 실환경 합의 부하(P-07) 도착 시 클라이언트 수·코퍼스 규모를 곱해 인스턴스 타입 산정, OSB 워크로드(
run-osb.sh, test-osb-scale.sh)로 실환경에서 동일 재측정. - 백업·복구: S3 버전 관리(원본), OpenSearch 스냅샷(자동 일일+판 전환 전 수동), RDS 자동 백업(PITR), 원장 인덱스 스냅샷. 복구 훈련 절차는 D-2.
- 알림: 배치 실패(failed>0)·BLOCKED 증가·grounding 생략(kev 다운)·판 전환 실패 — 소비자 원장 상태가 알림 소스(실증: 원장 status=partial).
- SLO 초안(합의 대상): 배치 종단 파이프라인 처리 시간, 검색 p95, 게시 지연 — 실측 기반치는 로컬 값, 실환경 재측정 후 확정.
9 이행 단계 (마이그레이션·롤백)
| 단계 | 내용 | 완료 기준 | 롤백 |
|---|
| M1 기반 | 도메인[H1]·S3·SQS·RDS[H3]·Secrets 생성, IAM 역할 | 환경 대사표 작성 | 개별 리소스 삭제 |
| M2 엔진 이전 | 로컬 매핑·파이프라인 인덱스를 관리형에 재적재(스키마 동일) | 문서 수·k-NN 질의 대사 일치 | 로컬 9200 병행 유지(병행 기간) |
| M3 앱 이식 | 소비자·검사기·실행기 컨테이너화(ECS) — local/ 스크립트 로직 그대로 | 회귀: 전 로컬 시험 스크립트를 실환경 엔드포인트로 재실행 (T27 18/18, 실패경로 9/9, T24 17/17, T25 18/18, T26 12/12) | 로컬 경로로 즉시 환원(별칭 미전환) |
| M4 모델 연결[H2] | 안A: 게이트웨이 엔드포인트 교체 / 안B: Bedrock 전환+T12/T14 재실행 | 선별·grounding 회귀 통과 | 안A 엔드포인트 복원 |
| M5 운영 이양 | D-2 런북 실행·부하 시험·백업 복원 훈련 | T28 전체 검증(G4) | — |
병행 운영: M2~M4 동안 로컬 9200을 읽기 참조(대사용)로 유지, M5에서 폐쇄.
10 미결정 항목 (확정 조건 = B 질의서 응답)
OpenSearch 버전/fgac/플러그인 · 모델 호출 경로·권한·비용 · 실적 DB 엔진·스키마·계정 정책 · 부하 목표·가용성 요건 · 데이터 상주/암호화 요건 · 네트워크(VPC·프라이빗 링크) · 담당자·승인 절차(G0 연계).
11 위험과 대응
| 위험 | 대응 |
|---|
| 관리형 버전이 로컬 2.13과 상이(하이브리드 파이프라인 키 등) | M2에서 파이프라인 호환 확인 우선 — 로컬에서 단수형 키 오류 사례(06 §1) 참조 |
| kev 자체 GPU 운영 부담 | 안A 요건에 명시 — 미충족 시 grounding 단계 축소(생략 기록 모드)하고 T15 사람 검수 비중 확대 |
| 실스캔 품질 저하(OCR 오인식) | T21 오인식 목록 방식 그대로 — 판독 불가 보류 원칙(D-3에서 파서 대응) |
| 실데이터에서 식별자 규칙 상이 | 기준판 버전 관리(baseline 버전)로 흡수 — 실증 패턴(14b) 유지 |
*다음: B 응답 도착 시 v0.2 확정(가실→확정 표기). 동시 발행: 13 외부 요청 패키지.*