목차
건설도면 기술용어집 · 기술요소 총람
항목 내용 작성일 2026년 11월 17일 지위 최초 통합 용어집 — 기존에는 기술요소가 03 범위분석 ·04 보완기술(S01~S10) ·10_README 운영메모 ·14 drawio 에 분산 존재했고 통합 문서는 없었음 → 본 문서로 first 작성정의 근거 코드가 진실 : 정의·열거값은 aws-emulator/local/ 실증 스크립트에서 직접 추출(t24-check.py·t27-consumer.py·t25-paths.py·t26-run.py·test-pipeline.sh). 수치·판정은 05·06·07 보고서 실측형제 문서 16 HTML 판 16_KIKUM_건설도면_기술용어집_20261117.html — 동일 내용의 검색 가능한 단일 HTML(다이어그램 SVG 내장, 오프라인 완전 동작)
1 기술 스택 한눈에
레이어 구성요소 실증 환경(전부 가동 실측) 원본·수집 S3(체크섬·버전)·EventBridge·SQS AWS Emulator 1.0.342 @ https://127.0.0.1:9297 검색 엔진 OpenSearch 2.13.0 — BM25·k-NN(lucene)·하이브리드 파이프라인 로컬 @ http://127.0.0.1:9200 (WSL) 임베딩 Ollama bge-m3(1024차, 채택)·nomic-embed-text(768차, 비교용) 로컬 @ 127.0.0.1:11435 선별 LLM llm-gateway → ornith-vllm(Ornith-1.5-9B-Vision-NVFP4, 262K ctx) @ 8092 → 8001 근거 검증기 kev-9b(System One 3-way, 자체 GPU RTX Spark N1X) @ 8009 /v1/systemone 실적 DB PostgreSQL 18 — 제한 역할·RLS·timeout WSL @ 127.0.0.1:5432 OCR Tesseract 5.5(+kor)·Ornith 비전 대조 WSL 로컬 앱 컴포넌트 배치·소비자·T24 검사기·T25 탐색·T26 실행기 aws-emulator/local/ 파이썬·셸 스크립트부하 측정 OpenSearch Benchmark 2.5.0(osb-runner 컨테이너) docker python:3.12-slim
2 기술용어집
2.1 인프라·플랫폼
용어 정의 비고·실증 AWS Emulator AWS API를 로컬에서 흉내내는 공식 패키지(1.0.342, WSL2 arm64 네이티브) S3/SQS/Lambda 등 실동작, Bedrock 등은 스텁 — 05 보고서 S3 객체 저장소. 원본 도면 보관 sha256 체크섬(ChecksumType FULL_OBJECT)·버전관리·SSE AES256 실증 SQS 메시지 큐. 배치 트리거·하류 이벤트 왕복 실증, T27 이벤트 계약의 전송로 EventBridge 이벤트 규칙 엔진. S3 변경 감지→SQS 로컬 실증은 수동 이벤트로 대체(동일 계약) Lambda 서버리스 함수. 실제 핸들러 실행 에뮬에서 런타임 실동작 확인 KMS / Secrets Manager 암호화 키·비밀 저장 런타임 발급 패턴(코드에 평문 없음) IAM·정책 강제 접근 정책 검증 도메인 정책 체인 실증(오탐 사례 포함) fgac OpenSearch Service 세부 접근 제어(사용자·역할 매핑) 에뮬 미지원 — 실환경 검증 과제(P-03)OpenSearch Service 관리형 검색 도메인. 에뮬은 실제 OS 2.13 프록시 BM25·별칭·정책 가능 / k-NN DSL·파이프라인·fgac 미지원 AOSS 관리형 벡터 검색(Zero-ETL) 에뮬 생성 실패 → 로컬 OS로 기능 대체·미채택Neptune 관리형 그래프 DB 에뮬 생성 실패 → 앱 탐색(T25)으로 대체·미채택RDS 관리형 관계형 DB. 에뮬은 PG 표기·SQLite 와이어 호환 기본 SQL만·역할 로그인/RLS 불가 → 로컬 PG18 보완 Bedrock 관리형 LLM/임베딩 API 에뮬 스텁 (고정 안내문) — 실환경 선택지 D-1 H2 안BTextract 관리형 OCR. 에뮬은 bbox 실제·텍스트 스텁 텍스트 경로는 Tesseract 보완 ECS/Fargate 컨테이너 실행 환경(실환경 앱 배치 대상) D-1 전환 설계의 배치 컴퓨팅
2.2 검색·색인
용어 정의 비고·실증 BM25 어휘 기반 랭킹 함수(키워드 검색) 에뮬·로컬 모두 실증 k-NN k-최근접 이웃 벡터 검색 로컬 lucene 엔진으로 실증(ARM64 필수 조건) lucene engine k-NN의 Apache Lucene 구현체 ARM64에선 nmslib가 세그폴트 → lucene 필수 (실측) nmslib k-NN 비벡터 라이브러리(JNI) 로컬 ARM64 색인 중 JVM 사망 — 불가 실증 하이브리드 검색 BM25+벡터 동시 질의 후 결합 query.hybrid.queries + ?search_pipeline=정규화 파이프라인 하이브리드 결과 점수 정규화·가중치 결합 키는 phase_results_processors(복수형) — 단수형 오류 사례 기록 임베딩 차원 벡터 밀도. bge-m3=1024, nomic=768 전환 시 매핑 차원 변경 필수(종단 재실행 실증) bge-m3 다국어 임베딩 모델(채택) 한국어 5/5 vs nomic 3/5, 지연 212ms 인덱스 v{N} 판 단위 물리 인덱스(seachdog_units_v2 등) 판 관리의 단위 별칭(alias) 클라이언트가 보는 고정 이름(seachdog_units_current) 전환 대상 — 판 교체의 접점 별칭 원자 전환 한 요청으로 별칭이 가리키는 인덱스 교체 조회 중 일관성(판 고정) 실증 reindex 기존 인덱스 문서를 새 인덱스로 복사 변경 적용은 항상 새 판 구성 후 전환 매핑(mapping) 필드 타입 정의 충돌 사례 실측: location string vs object _bulk / NDJSON 대량 색인 API·개행 구분 JSON 종결 개행 누락 시 400 (실측), 항목별 오류 검사 필수refresh 지연 색인 후 검색 가능해지기까지 지연(~1s) 직후 읽기는 GET _doc (실시간) 사용 — 실측 교훈 seunjeon 한국어 형태소 분석기(ko) 기존 서비스 화면에서 확인(사진9) OSB OpenSearch Benchmark. 부하·지연 측정 osb-runner 컨테이너로 구동(WSL Python 3.14 호환 불가 대체)
2.3 문서 처리·입력 추출
용어 정의 비고·실증 OCR 이미지→텍스트 변환 합성 비트맵 오인식 사례 기록(PUMP→PUP 등) Tesseract 오픈소스 OCR 5.5(+kor) 흰목록+패턴+정규화로 실증. conf는 요동(0~90)해 필터 폐기 흰목록(whitelist) 인식 가능 문자 제한 -c tessedit_char_whitelist=PVTK0123456789.- 인접 태그 단어 병합 방지 간격 조정 병용 PaddleOCR 오픈소스 OCR(중국권 강세) ARM64 불가 (aarch64 휠 부재+docker amd64 단일) 실증Docling 문서→구조화(텍스트·표·bbox) 파서 PDF 텍스트 경로 채택 — 실증은 샘플 수령 후 ezdxf DXF 파이팅 라이브러리 TEXT/MTEXT·블록·선분·레이어·좌표. DWG 직접 판독 불가 IfcOpenShell IFC(BIM) 파싱 라이브러리 속성·공간/시스템 관계 활용 bbox 원문 내 사각 영역(bounding box, 4실수) T24 v2 위치 계약 필드 위치 계약 {coord_system, page, bbox} 구조화 위치t24-rules-v2 evidence_location_schema, E111 검사 P&ID 태그 설비·밸브 식별자(P101·V201 등) 정규화 규칙(O→0, L/I→1) 실증 개정(revision) 문서 버전(A/B/C, order·status·valid_until) 기준판에서 관리, supersedes 관계의 기초 도트 vs 교차 배관 접점 판별 — 도트 폭≥14px, 교차~8px, 임계 10px/연속 6px "교차≠연결" 규칙 실증(T23 16/16) width_profile 세그먼트 축 방향 폭 프로파일 도트 검출 원리
2.4 LLM·근거 검증
용어 정의 비고·실증 LLM 선별 검색 후보 중 정답 후보를 고르고 근거를 제시하는 단계 프롬프트 계약: candidate_id·decision·reason 필드 구조화 출력 LLM 응답을 JSON으로 강제 JSON Schema/Pydantic 검증 대상 17.5절 검증 앱이 하는 LLM 응답 검증 — ID 대사·허용값·재시도 제한 결함 4종 전부 needs_review行 실증 needs_review 기계 판정 보류 상태 오류를 reject로 바꾸지 않는다 (17.5.4)kev-9b 근거 검증기(Qwen3.5-9B-Base+어댑터) 자체 GPU 필수 — 관리형 대응 없음 System One kev 서빙 프로토콜 POST /v1/systemone state+3-way choice, 응답 choice·confidence·probabilities·latency_ms choice 3값 supported / contradicted / insufficient_evidence코드 추출(t27-consumer.py criteria) KEV_MIN_CONF 신뢰도 하한 = 0.5 미만은 supported여도 보류(저신뢰 강등) grounding 주장↔원문 근거 대조 판정 3사례 정확(0.949/0.966/0.988) 중립 문구 원칙 검증기 입력은 질문·주장·근거만 "T24 통과" 등 이력 언급 시 supported 편향 실측 환각(hallucination) 근거 없는 생성 형식 통과≠사실성 — 검증 단계 존재 이유
2.5 관계·온톨로지·탐색 (T24/T25)
용어 정의 비고·실증 온톨로지 개체 유형·관계 유형의 형식 명세 코드·JSON 검사 채택, RDF/SHACL은 필요 시(미채택) 관계 유형 4종 shown_in·supersedes·part_of·connected_tot24-rules-v1/v2 allowed_pairs 출발→도착 유형 허용 쌍 사전 유형·방향 검사의 기준 방향 대칭(symmetric)·순방향(forward) 탐색 hop 허용 판정에 사용 T24 제약 검사 관계 후보의 기계적 형식·무결성 검사 v1 13/13 + v2 4/4 기준판(baseline) 개체·문서·개정·유효기간 등록부 버전 관리(예: entity-baseline-2026-11-14b) candidate_hash 후보 정준(canonical) JSON sha256 앞 16자리 후보 수정 감지→재검사 트리거(18.2절) 실증 validation_status 기계 검사 결과(pass/hold/fail) review_status(사람)와 분리 저장 — 21.24.4relations_pub 승인 관계만 게시하는 공개 인덱스 관측 관계만, 파생은 별도 관측 vs 파생 원문에서 읽은 관계 vs 규칙으로 유도한 관계 파생은 DERIV-{원본ID} + 규칙 버전 기록 전제 무효화 파생 관계의 원본이 무효화되면 파생도 제거 t25 invalidate 실증 BFS 탐색 앱 레벨 다단계 경로 탐색 PPL graphLookup 부재 실증 → 앱 탐색 채택 도달≠영향 경로 도달과 영향 전파는 별개 판정 impact는 flow_direction 정의 관계만 순방향 flow_direction 유체 흐름 방향(예: P101->V201) t25-impact-rules-v1이 사용, 미정의=보류 순환 제한 경로 내 동일 노드 중복 금지 REL-04 사이클 사례로 실증 권한 경계 경로 양끝의 프로젝트 일치 검사 17.4.5 위반 사례 발견→수정 실측
T24 오류 코드 전체(코드 추출) : E101 필수 ID/필드 누락 · E102 관계 유형 허용값 밖 · E103 참조 개체/문서 부재 · E104 출발·도착 유형쌍 불일치 · E105 방향 위반(역순쌍은 사전에 존재) · E106 문서에 없는 개정 참조 · E107 근거 필수필드 누락 · E108 근거 source_ref 미등재 · E109 무효(superseded) 개정 끝점(supersedes 대상은 예외) · E110 supersedes 개정 순서 위반(source≤target) · E111 위치 계약 위반(구조·coord_system·bbox 4실수) · H201 식별 신뢰 낮음→hold. 상태 판정: E 있으면 fail, H201만 hold, 아니면 pass.
2.6 이벤트·판 관리 (T27)
용어 정의 비고·실증 이벤트 계약 {event_id, entity_id, source_version, operation, run_id, payload}소비자 입력 형식 멱등(idempotency) 같은 이벤트 재처리 결과 불변 원장 event_id 조회로 duplicate 스킵 — 실증 원장(ledger) seachdog_event_ledger — 처리 이력 인덱스 배치 요약도 기록(manifest) 원장 상태 5종 applied / duplicate / stale / blocked / failed코드 추출(t27-batch counts) entity_state 개체 최신 상태 인덱스(status: active/deleted) GET _doc 실시간 조회 (refresh 지연 회피)stale(시효) source_version ≤ 최신 버전인 오래된 이벤트 스킵 처리 — 역순 도착 실증 판 고정 실행이 시작할 때의 인덱스명으로 조회 전환 중 일관 응답 실증 manifest 배치 목록 단위 일괄 처리 + 부분 실패 지속 + 재실행 스킵 요약 complete/partial — 7/7 실증 BLOCKED=보류 게이트 미통과는 원장에 blocked+사유 reject 아님(17.5.4)
2.7 실적 질의·데이터 방어 (T26)
용어 정의 비고·실증 T2SQL 자연어→SQL 변환 흐름 앱의 5단계(예시→용어→객체→규칙→엔터티 검색) 템플릿 사전 승인된 SQL 틀 목록(t26-templates.json) 사전 밖 질의 거부 — 1층 파라미터 바인딩 '$2' 등 위치 표지자에 값 치환전역 치환 구현('$%d'→값) 값 검증 enum·regex 화이트리스트 주입 4종·변조 템플릿 차단 실증 — 2층 이스케이프 작은따옴표 등 메타문자 무효화 값 치환 시 적용 3층 방어 ①템플릿 사전+SELECT 검사 ②값 검증+이스케이프 ③제한 역할 12/12 실증 제한 역할(sd_query) SELECT 전용 계정 직접 INSERT·pg_sleep6 차단 실증 — 3층 RLS 행 수준 보안(로컬 PG18 실증) 필요 시 test-pg-rls 패턴 재사용 statement_timeout 쿼리 시간 제한(3초) PGOPTIONS로 세션 적용 PGOPTIONS 세션 옵션 환경변수 psql -c는 stdin을 안 읽음 → stdin 방식과 병용
2.8 운영·품질
용어 정의 비고·실증 p50 / ops 중위 지연 / 초당 처리량 kNN-768 p50 3.7ms·195ops@10k 문서·오류 0% SHA256 체크섬 원본 무결성 증명 S3 왕복 대사 실증 SSE 서버 측 암호화(AES256) 원본 버킷 적용 스냅샷 OpenSearch 인덱스 백업 자동 일일+판 전환 전 수동(D-1 설계) 판 롤백 이전 판으로 별칭 되돌림 이전 판 보존이 전제 회귀(regression) 전 로컬 시험 스크립트를 실환경 엔드포인트로 재실행 D-1 M3 완료 기준 병행 운영 전환 기간 로컬 9200 읽기 참조 유지 대사용, M5에서 폐쇄 SLO 서비스 목표 수준(배치 처리시간·검색 p95·게시 지연) 실환경 재측정 후 확정(합의 대상)
3 기술 플로우 — 종단 파이프라인
flowchart LR
A[S3 원본 업로드<br>sha256·버전] --> B[입력 형식 분기<br>PDF·스캔·DXF·DWG·IFC]
B --> C[추출 파서<br>Docling·Tesseract·ezdxf·IfcOpenShell]
C --> D[추출 레코드<br>태그·bbox·페이지·개정]
D --> E[임베딩 bge-m3<br>1024차]
E --> F[색인 v{N} bulk<br>NDJSON]
F --> G[하이브리드 검색<br>BM25+kNN·정규화 가중치]
G --> H[LLM 선별<br>17.5절 검증]
H --> I[kev grounding<br>choice·conf≥0.5]
I --> J[T24 제약 검사<br>E코드·H201]
J --> K[판 게시<br>relations_pub·별칭 원자 전환]
K --> L[SQS 이벤트 → T27 소비자<br>멱등·시효·원장]
L --> M[하류: 재조회·T25 탐색·T26 실적질의]
실패 경로(전부 실증): LLM 결함→needs_review · kev 저신뢰→보류 · T24 E코드→fail(미게시) · 후보 수정→해시 불일치→재검사 · 네트워크 오류→needs_review.
4 데이터 플로우 — 데이터 산출물 계약
flowchart LR
A[원본 객체<br>source_id·sha256·형식] --> B[추출 레코드<br>태그·text·bbox/좌표·변환식·품질]
B --> C[색인 문서<br>text·vector·location·개정]
C --> D[검색 후보<br>doc_id·score·페이지]
D --> E[선별 결과<br>candidate_id·decision·reason]
E --> F[grounding 판정<br>choice·confidence]
F --> G[관계 후보<br>candidate_hash·evidence.location]
G --> H[T24 결과<br>codes·validation_status]
H --> I[게시 관계<br>relations_pub·review_status 분리]
I --> J[이벤트<br>event_id·source_version]
J --> K[원장·entity_state<br>status·processed_at]
5 아키텍처 색 구분 요약
색 규약은 14 drawio 와 동일하다.
flowchart TB
subgraph EMUL["🟩 에뮬 가능(실동작)"]
S3[S3] --- SQS[SQS·EventBridge] --- LMD[Lambda] --- KMS[KMS·Secrets] --- ATH[Athena·Glue]
end
subgraph PART["🟨 부분 지원"]
OSD[OpenSearch Service<br>BM25만·kNN/fgac 미지원] --- RDS[RDS<br>기본 SQL만] --- TX[Textract<br>bbox만]
end
subgraph IMPO["🟥 에뮬 불가"]
BD[Bedrock 스텁] --- NPT[Neptune] --- AOS[AOSS] --- FGC[fgac 인증]
end
subgraph LOC["🟪 로컬 보완 엔진"]
OS13[OpenSearch 2.13<br>kNN lucene] --- OLM[Ollama bge-m3] --- VLM[ornith-vllm] --- KEV[kev-9b] --- PG[PG18] --- TES[Tesseract]
end
subgraph APP["🟦 앱 컴포넌트"]
BATCH[배치·추출] --- SEL[LLM 선별] --- T24[T24 검사기] --- T25[T25 탐색] --- T26[T26 실행기] --- T27[T27 소비자]
end
EMUL -.보완.-> LOC
IMPO -.대체.-> LOC
LOC --> APP
6 코드·상태값·식별자 사전
분류 값 의미 LLM decision accept / reject / needs_review 허용값 밖 응답은 needs_review로 강등 kev choice supported / contradicted / insufficient_evidence 게시 조건: supported + conf≥0.5 T24 status pass / hold / fail fail=E코드, hold=H201만 원장 status applied / duplicate / stale / blocked / failed blocked=보류(reject 아님) entity_state active / deleted operation(update/delete) 반영 manifest complete / partial failed=0 여부 인덱스 seachdog_units_v{N} / _current 판·별칭 인덱스 seachdog_relations_pub 승인 관계 공개판 인덱스 seachdog_event_ledger / seachdog_entity_state 원장·개체 상태 규칙 버전 t24-rules-v1/v2 · t25-impact-rules-v1 · t25-derive-rules-v1 결과 기록에 항상 병기
7 참조
설계: 01 실행계획(T01~T28) · 02 상세가이드(12절 흐름·17~21절) · 04 보완기술(S01~S10) 실증: 05 에뮬레이터 검증 · 06 로컬 보완환경(§5~9) · 07 충족도 종합판정 전환: 12 D-1 아키텍처(가설 H1~H3·이행 M1~M5) · 14 drawio 6시트 재현: aws-emulator/local/test-*.sh(전 스크립트 표는 10_README)
건설도면프로젝트 문서 뷰어 · 원본 markdown은 output/ 폴더 양식: 17 템플릿(kikum.xyz/physical-ai-motion 팔레트 준수)