건설도면프로젝트 — AI 서포트 데이터엔지니어링 구성환경

항목내용
작성일2026년 11월 17일
목적데이터엔지니어링 프로젝트 구조 표준 골격(README·환경설정·컨테이너·src 5계층·CI/CD)에 이 프로젝트의 실물 구성환경(AWS 에뮬레이터 + 로컬 하이브리드) 을 그대로 사상한 구성 문서
판정 기준구성 요소가 실측으로 존재하고 동작하는가(R3). 상태 3값: [실재] 로컬 하이브리드 환경에 존재·실측 통과 / [부분] 일부만 존재하거나 수동 절차로 대체 중 / [제안] 실환경 전환(D-1) 시 새로 작성
실물 위치스크립트·규칙·검증기는 aws-emulator/local/·aws-emulator/scripts/, 근거 문서는 05·06·07·10·12호
주의이 문서의 트리는 목표 레포 골격(실환경 전환 시의 코드 배치)이며, 각 노드에 현재 실물 경로와 상태를 병기했다 — 아직 그 경로로 코드를 옮겼다는 뜻이 아니다

1 전체 구조 트리 (표준 골격 ← 실물 사상)

건설도면프로젝트/                       ← 데이터엔지니어링 표준 골격
├── README.md                  [실재] aws-emulator/08_README.md
├── .env.example               [부분] scripts/env-wsl.sh · env-windows.ps1 + 파이프라인 매개변수
├── .gitignore                 [제안] 모델 체크포인트·인증서·데이터 제외 규정 필요
├── docker-compose.yml         [부분] 컨테이너 4종이 개별 docker start 로 기동 중
├── Dockerfile                 [부분] osb-runner 컨테이너 수동 구성 (python 3.12-slim)
├── pyproject.toml             [제안] 현 검증 스크립트는 파이썬 표준라이브러리만 사용
├── src/
│   ├── ingestion/             [실재] OCR·합성 도면·S3 원본 적재·이벤트 소비
│   │   ├── ocr_extractor            ← api_extractor.py 자리 (test-ocr*.sh, Tesseract 5.5)
│   │   ├── synthetic_builder        ← 합성 도면 생성+기하 검출 (t23-pipes.py, 16/16)
│   │   └── event_consumer           ← kafka_consumer.py 자리 (SQS/EventBridge, t27-consumer.py)
│   ├── dags/                  [실재] 종단 파이프라인·manifest 배치
│   │   ├── pipeline_end2end         ← daily_sales_dag.py 자리 (test-pipeline.sh, 전 단계 통과)
│   │   └── manifest_batch           ← backfill_dag.py 자리 (t27-batch.py, 재실행 멱등 7/7)
│   ├── transform/
│   │   └── models/            [실재] 인덱스 매핑·임베딩 적재·질의 템플릿 계약
│   │       ├── index_mapping        ← stg_orders.sql 자리 (k-NN lucene·하이브리드 파이프라인)
│   │       └── query_templates      ← fct_sales.sql 자리 (t26-templates.json, 12/12)
│   ├── tests/                 [실재] 관계 제약 검사기·품질 규칙
│   │   ├── t24_check                ← test_transforms.py 자리 (t24-check.py, E101~E111·H201)
│   │   └── data_quality             ← data_quality.yml 자리 (t24-rules-v2.json + baseline)
│   └── infra/                 [실재] 인덱스·역할·RLS·기동 절차를 코드로
│       ├── setup_opensearch         ← main.tf 자리 (setup-opensearch.sh)
│       └── pg_roles_rls             ← variables.tf 자리 (test-pg-rls.sh, 전 항목 통과)
└── .github/workflows/         [제안]
    ├── ci.yml                       ← 모든 변경에 전 검증 재실행 (현재 수동)
    └── deploy.yml                   ← gold 게시 = 별칭 원자 전환 + 원장 기록

2 루트 파일 — 구성 카드

2.1 README.md [실재]

2.2 .env.example [부분]

2.3 .gitignore [제안]

2.4 docker-compose.yml [부분]

컨테이너포트용도
ornith-vllm8001메인 LLM(vLLM, Ornith-1.5-9B-FP8, 262K ctx, dflash 스펙추론)
llm-gateway8092T14 선별 메인 경로(OpenAI 호환, secu-mainllm → ornith-vllm 업스트림)
ollama-gpu11435임베딩(bge-m3 1024차·nomic 768차) + LLM 폴백(mica 4.2B, think:false 필수)
osb-runner—OpenSearch Benchmark 2.5.0 상시 컨테이너(python 3.12-slim)

2.5 Dockerfile [부분]

2.6 pyproject.toml [제안]

3 src/ingestion/ — 수집·원본 적재 [실재]

실물표준 자리내용·실측
test-ocr*.sh (Tesseract 5.5)api_extractor.py도면 OCR 추출·품질 기록(T21/S01). PUMP 정확 인식(conf 84·bbox 정확), P101→"Pil" 오인식은 오류 사례로 보존. 비전 OCR(Ornith)도 합성 비트맵은 오인식(P101→'P4H1') — 엔진 공통 스트레스 사례
t23-pipes.py(합성 생성기)합성 도면 5사례(접점/교차/끊김/타페이지/모호) 생성+기하 검출 — 도트 폭 임계로 교차≠연결 구분. 16/16 통과, 기하 파라미터는 결과 JSON geometry_rules에 항상 기록
t27-consumer.pykafka_consumer.pySQS/EventBridge 이벤트 소비 — 변경·삭제 이벤트 적용, 멱등(DUPLICATE)·역순(STALE) 판정, 새 판 reindex+별칭 원자 전환. 18/18 통과, 원장 seachdog_event_ledger·상태 seachdog_entity_state에 이력 영구 기록

4 src/dags/ — 오케스트레이션 [실재]

실물표준 자리내용·실측
test-pipeline.shdaily_sales_dag.py종단 통합: S3→OCR→적재→BM25→메인 LLM 선별(3초, 정확)→kev grounding(supported, conf 0.829)→v2 게시→SQS→재조회. 전 단계 통과. 메인 LLM 다운 시 mica 폴백, kev 다운 시 grounding 생략(기록) — 실패도 경로로 설계
t27-batch.pybackfill_dag.pymanifest 배치: 엔트리별 소비자 호출(표준입력), 부분 실패 지속·재실행 멱등. 7/7 통과 — 1차 applied=1/blocked=1/failed=1, 2차 duplicate=2, manifest 요약 원장 기록
test-failure-paths.sh(재시도·보류 규칙)LLM 결함 4종→전부 needs_review(보류), grounding 임계 단위, BLOCKED 종단, 승인 직전 후보 해시 대사 시 재검사(자동 이월 금지). 9/9 통과

5 src/transform/models/ — 변환·계층 모델 [실재]

표준 계층건설도면 실물보관소
bronze(staging)원본 도면 as-is(T07)S3(에뮬레이터 9297)
silver(intermediate)청크+벡터 색인·관계 판로컬 OpenSearch 9200 — 문서 인덱스·seachdog_relations_pub(관측 관계만 게시, 파생=DERIV-*+전제·규칙 버전)
gold(marts)게시 판(current)별칭 원자 전환 — reindex 후 스위치, 게시 이력은 원장에 영구 기록

6 src/tests/ — 검증·데이터 품질 [실재]

실물표준 자리내용·실측
t24-check.py + t24-rules-v2.jsondata_quality.ymlT24 관계 제약 검사기(코드·JSON 필수 최소) — v1 13사례 13/13: 참조 존재(E103)·유효기간(E109)·supersedes 순서(E110)·방향(E105) 구분 검출. v2 좌표 계약(E111: location={coord_system,page,bbox}) 4/4
t24-baseline.json(기준판)기대 결과 기준판 — 규칙 변경 시 새 버전 파일 + 기준판 갱신, 결과물은 규칙·기준판 버전과 후보 해시를 남긴다
test-grounding.sh(사실성 검사)kev-9b 3-way(지지 0.949/모순 0.966/근거불충분 0.988) — 3사례 전부 정확, ~1초/건. 주의: 검증기 입력에 게이트 이력("T24 통과")을 넣으면 supported로 편향(실측)
test-relation.sh(관계 사실성)중립 문구 5/5 정판 — 관계 검증도 grounding 위에 올라탄다

7 src/infra/ — 인프라 코드 [실재]

실물표준 자리내용·실측
setup-opensearch.shmain.tf로컬 OpenSearch 최초 설치·기동 — 전체 플러그인 배포(k-NN/neural/flow-framework)
start-opensearch.sh·start-kev.sh(서비스 기동)9200 엔진 / kev 검증기(GPU cuda+bf16, 로드 ~70초)
scripts/start·stop·status-emulator.ps1(플랫폼 기동)Windows→WSL 에뮬레이터 기동·중지·상태(localhost 포워딩 점검 포함)
test-pg-rls.shvariables.tf(IAM 자리)PG 18 제한 역할·RLS·읽기 전용·statement_timeout — 전 항목 통과: user_alpha는 ALPHA 1건만 노출, 소유자 우회 차단, 읽기전용 INSERT 거부, 타임아웃 취소, 역할별 기본 설정
t26-run.py + t26-templates.json(웨어하우스 접근 계약)제한 역할 sd_query(SELECT 전용·timeout 3s)·psql stdin·PGOPTIONS 세션 — 주입 4종·변조 템플릿·쓰기·장기질의 전부 차단 12/12. 역할 암호는 런타임 생성(.pgpass)

8 .github/workflows/ — CI/CD [제안]

워크플로걸어야 할 검증(전부 실측 통과 세트)
ci.ymlt23 16/16 · t24 13/13+v2 4/4 · t25 경로 18/18 · t26 12/12 · t27 이벤트 18/18+배치 7/7 · 실패 경로 9/9 · grounding 3사례 · 임베딩 비교 5/5 · PG RLS 전 항목 · 종단 파이프라인
deploy.ymlgold 게시 = 별칭 원자 전환 + 원장 기록(t27-consumer 적용 절차) — main 머지=승인 게시의 자동화. 게시 전 사람 review_status 승인은 유지(형식 통과와 사실성 승인 분리 원칙)

9 사상 총표

표준 골격표준 기술건설도면 실물상태근거
README.md—08/09/10 README 3종 + 14 drawio실재08·10
.env.exampledotenvenv-wsl.sh·env-windows.ps1 + EMB·KEV 매개변수부분08·10
.gitignore—(제외 규정 미작성)제안—
docker-compose.ymlAirflow·Kafka·Postgres컨테이너 4종(개별 기동) + 에뮬레이터·OS·PG·kev부분10
Dockerfile—osb-runner(python 3.12-slim) 수동부분10
pyproject.tomluv/pip표준라이브러리 전용(의최소) + 평가스위트 uv제안08
src/ingestionKafka·API 수집기OCR(T21/S01)·합성생성(T23)·이벤트 소비(T27)실재06·10
src/dagsAirflow DAG종단 파이프라인·manifest 배치·실패경로실재10
src/transform/modelsdbt SQL 3계층인덱스 매핑·하이브리드·템플릿 계약·원장 계보실재06·10
src/testspytest·dq.ymlt24 검사기+규칙 JSON v2·기준판·grounding실재10
src/infraTerraform셋업·기동 스크립트·PG 역할/RLS·sd_query 계약실재06·10
.github/workflowsGitHub Actions수동 검증 세트 → CI/CD화제안12

10 런타임 구성 실측표 (포트 기준)

구성요소주소용도상태
AWS Emulator 1.0.342127.0.0.1:9297S3·SQS/EventBridge·관리형 OS 도메인·Lambda·KMS/Secrets·Glue/Athena·DMS실재(메모리 상주)
로컬 OpenSearch 2.13.0127.0.0.1:9200k-NN(lucene 필수)·하이브리드·BM25·관계 판실재
ornith-vllm127.0.0.1:8001메인 LLM(vLLM, 262K ctx)실재
llm-gateway127.0.0.1:8092T14 선별 메인 경로(OpenAI 호환)실재
ollama-gpu127.0.0.1:11435임베딩(bge-m3·nomic) + LLM 폴백(mica)실재
kev/jev 검증기127.0.0.1:80093-way 근거 지지 판정(LoRA r16 head)실재(필요 시 기동)
PostgreSQL 18127.0.0.1:5432제한 역할·RLS·템플릿 질의(T26/T28)실재
Tesseract 5.5WSL CLIOCR 추출·품질 기록(T21/S01)실재
osb-runner컨테이너OSB 벤치마크(10k 규모: match-all p50 3.2ms·kNN-768 p50 3.7ms·오류 0%)실재

11 구성 관점의 불가·보류 (R3 기록 의무)

항목판정원인우회
에뮬레이터 Bedrock 추론불가스텁 응답만 제공로컬 LLM(8092/8001)·임베딩(11435)으로 보완
에뮬레이터 k-NN DSL·fgac 인증불가/부분질의 DSL·인증 체인 미지원로컬 OS 9200에서 엔진 실측, fgac은 오류 체인만 실증
에뮬레이터 RDS불가(해당 용도)SQLite 기반 구현로컬 PostgreSQL 18로 RLS·제한 역할 실측
Neptune 그래프 질의불가에뮬레이터·로컬 모두 미검증 자원앱 탐색 BFS + 관계 인덱스(T25, 18/18)
graphLookup(PPL)불가로컬 2.13 PPL 미지원(토큰 없음 오류 실증)앱 BFS로 동일 통제 구현
nmslib k-NN 엔진불가ARM64 세그폴트(병합 중 크래시)engine: lucene 고정
PaddleOCR불가aarch64 휠 부재·공식 이미지 amd64 단일Tesseract 5.5 + 패턴 정규화
실 AWS 자원·비용보류사람 합의 필요(C 그룹)13호 요청 패키지 발송 대기

12 재현 경로·근거