1 기술 스택 한눈에
전 구성요소가 로컬 하이브리드 환경에서 가동 상태로 실측되었다(05·06 보고서).
| 레이어 | 구성요소 | 실증 환경 |
|---|---|---|
| 원본·수집 | 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 체크섬(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 엔진 실증 로컬 보완 |
| lucene engine | k-NN의 Lucene 구현체 | ARM64에선 nmslib 세그폴트 → lucene 필수(실측) 로컬 보완 |
| 하이브리드 검색 | 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) | 클라이언트가 보는 고정 이름(_current) | 판 교체의 접점 |
| 별칭 원자 전환 | 한 요청으로 별칭이 가리키는 인덱스 교체 | 조회 중 일관성(판 고정) 실증 |
| reindex | 기존 문서를 새 인덱스로 복사 | 변경 적용은 항상 새 판 구성 후 전환 |
| 매핑(mapping) | 필드 타입 정의 | 충돌 사례 실측: location string vs object |
| _bulk / NDJSON | 대량 색인 API·개행 구분 JSON | 종결 개행 누락 시 400, 항목별 오류 검사 필수 |
| refresh 지연 | 색인 직후 검색 가능 시점까지 지연(~1s) | 직후 읽기는 GET _doc(실시간) — 실측 교훈 |
| seunjeon | 한국어 형태소 분석기(ko) | 기존 서비스 화면 확인(사진9) |
| OSB | OpenSearch Benchmark — 부하·지연 측정 | osb-runner 컨테이너 구동 로컬 보완 |
2.3 문서 처리·입력 추출
| 용어 | 정의 | 비고·실증 |
|---|---|---|
| OCR | 이미지→텍스트 변환 | 합성 비트맵 오인식 사례 기록(PUMP→PUP) |
| Tesseract | 오픈소스 OCR 5.5(+kor) | 흰목록+패턴+정규화 실증 — conf 요동(0~90)으로 필터 폐기 로컬 보완 |
| 흰목록(whitelist) | 인식 문자 제한 | -c tessedit_char_whitelist=PVTK0123456789.- + 간격 조정 |
| PaddleOCR | 오픈소스 OCR | ARM64 불가(aarch64 휠 부재) 실증 불가 |
| Docling | 문서→구조화(텍스트·표·bbox) 파서 | PDF 텍스트 경로 채택 — 실증은 샘플 수령 후 미검증 |
| ezdxf | DXF 파싱 라이브러리 | TEXT/MTEXT·블록·선분·레이어·좌표 — DWG 직접 판독 불가 미검증 |
| IfcOpenShell | IFC(BIM) 파싱 라이브러리 | 속성·공간/시스템 관계 활용 미검증 |
| bbox | 원문 내 사각 영역(4실수) | T24 v2 위치 계약 필드 |
| 위치 계약 | {coord_system, page, bbox} 구조화 위치 | t24-rules-v2, 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 | 응답 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) |
| 중립 문구 원칙 | 검증기 입력은 질문·주장·근거만 | 게이트 이력 언급 시 supported 편향 실측 |
| 환각 | 근거 없는 생성 | 형식 통과≠사실성 — 검증 단계의 존재 이유 |
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 | 후보 정준 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 개정 순서 위반 ·
E111 위치 계약 위반 ·
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) |
| entity_state | 개체 최신 상태 인덱스(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 틀 목록 | 사전 밖 질의 거부 — 1층 앱 |
| 파라미터 바인딩 | '$2' 위치 표지자에 값 치환 | 전역 치환 구현 |
| 값 검증 | enum·regex 화이트리스트 | 주입 4종·변조 템플릿 차단 실증 — 2층 |
| 이스케이프 | 메타문자 무효화 | 값 치환 시 적용 |
| 3층 방어 | ①템플릿 사전+SELECT 검사 ②값 검증+이스케이프 ③제한 역할 | 12/12 실증 |
| 제한 역할(sd_query) | SELECT 전용 계정 | 직접 INSERT·pg_sleep6 차단 — 3층 PG18 |
| RLS | 행 수준 보안 | 로컬 PG18 실증, 필요 시 재사용 |
| 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 기술 플로우 — 종단 파이프라인
4 데이터 플로우 — 데이터 산출물 계약
5 아키텍처 색 구분 요약
에뮬 가능 — 실동작부분 지원 — 제한·스텝에뮬 불가앱 컴포넌트로컬 보완 엔진실환경·미검증
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 — 전 스크립트 표는 aws-emulator/local/10_README.md |