# 건설도면 기술용어집 · 기술요소 총람

| 항목 | 내용 |
| --- | --- |
| 작성일 | 2026년 11월 17일 |
| 지위 | **최초 통합 용어집** — 기존에는 기술요소가 [03 범위분석](<C:/work/서치독_프로젝트/output/03_KIKUM_건설도면_OpenSearch_문제별_해결범위_분석_20261113.md>)·[04 보완기술(S01~S10)](<C:/work/서치독_프로젝트/output/04_KIKUM_건설도면_보완기술_구현방안_20261113.md>)·[10_README 운영메모](<C:/work/서치독_프로젝트/aws-emulator/local/10_README.md>)·[14 drawio](<C:/work/서치독_프로젝트/output/14_KIKUM_건설도면_전체아키텍처_에뮬레이터구분_20261116.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 판](<C:/work/서치독_프로젝트/output/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 안B |
| Textract | 관리형 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_to` | t24-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.4 |
| relations_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 기술 플로우 — 종단 파이프라인

```mermaid
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&#123;N&#125; bulk<br>NDJSON]
    F --> G[하이브리드 검색<br>BM25+kNN·정규화 가중치]
    G --> H[LLM 선별<br>17.5절 검증]
    H --> I[kev grounding<br>choice·conf&#8805;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 데이터 플로우 — 데이터 산출물 계약

```mermaid
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](<C:/work/서치독_프로젝트/output/14_KIKUM_건설도면_전체아키텍처_에뮬레이터구분_20261116.drawio>)와 동일하다.

```mermaid
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)
