C.E.L_Slide_test2/tests/PIPELINE.md

PIPELINE — V1 ~ V4 매칭 시스템 통합 정리

이 문서는 MDX ↔ Figma Frame 매칭 시스템의 V1 ~ V4 단계를 한 곳에 정리한다. 새 작업자 (또는 새 Claude 세션) 가 이 문서만 읽어도 시스템 전체를 파악할 수 있도록 작성.

---

사전 작업 (V1 이전)

S.1 입력 수집

출처	입력 문서	수집 문장
Figma 프레임 텍스트	32 개	586
BEPS 마스터 텍스트	1 개	1,410
MDX 검증 구간	4 개	129
합계	37	2,125

• 코드 : pipeline_01_extract_nodes.py
• 결과 : actual_text_nodes.yaml

S.2 키워드 추출 + 정리

2,125 문장 → 형태소 분석 (Kiwi) → 13,913 등장 / 1,738 고유
                                  ↓ 표기 통합 + 보존 규칙
                             전처리 후 14,161 등장 / 1,713 고유
                                  ↓ 등장 범위 분류
                             핵심 451 + 연관 1,238 + 광범위 24 = 1,713
                             추가: 키워드 세트 524 (frame-level 시그니처)

적용 규칙

• 중요 표기 보존 13개: DX, BIM, S/W, H/W, 2D, 3D, AS-IS, TO-BE 등
• 표기 통합: "디지털 전환" / "디지털전환" → 대표 표기 DX
• 제외: 1글자 단어, 순수 숫자, 공백/기호만 있는 토큰
• 품사: 일반명사 / 고유명사 / 외국어 / 숫자만

코드 : pipeline_02_tokenize.py, pipeline_04_normalize.py, pipeline_05_anchor_candidates.py, pipeline_07_auto_anchor_candidates.py 결과 : auto_anchor_candidates.yaml, keyword_base.yaml, domain_terms.yaml

S.3 Frame 구조 라벨링 (templates_v2 ontology)

32 개 Figma 프레임 각각에 다음 정보 라벨링:

• visual_pattern.layout (compare-rows / table-2col / cards-3col 등)
• visual_pattern.family (table / card / diagram / list)
• visual_pattern.relation_type (compare / parallel / sequence)
• visual_pattern.cardinality (ideal / min / max)
• content_affinity.primary + secondary (12 카테고리)
• structure_intent_v2.primary + secondary (9 카테고리)
• slots (146 고유 slot id — title, col_a_label, col_b_label, rows 등)
• alternative_patterns (대안 layout)

도출 과정 : r1 → r2 → r3 → final → final_r2 (수동 오버라이드 3건) 코드 : pipeline_12_generate_templates_v2.py, pipeline_12_r3_generate_templates_v2.py, pipeline_12_finalize_v2.py 결과 : structure_ontology_v2_final_r2.yaml

---

V1 — 키워드 매칭

무엇을 보는가

MDX 본문 단어와 frame 의 3 계층 키워드 (핵심 / 세트 / 연관) 의 일치 비율.

산식

matching_score = 0.414 × 핵심 점수 + 0.320 × 세트 점수 + 0.265 × 연관 점수

• 핵심 점수 = (frame 핵심 키워드 중 MDX 본문에 등장한 비율)
• 세트 점수 = (frame 세트들의 MDX 매칭 coverage 평균)
• 연관 점수 = (frame 연관 키워드 중 MDX 본문에 등장한 비율)

가중치 도출 과정

1. 초기 (수동) : 0.30 / 0.50 / 0.20 — 도메인 판단
2. Logistic Regression 학습 (L2, C=1.0, scikit-learn)
   • 데이터: TARGET 4 × 32 frame = 128 샘플 (정답 4 / 오답 124)
   • Feature: (standalone_score, group_score, related_score)
   • Label: 1 (정답) / 0 (오답)
   • 학습 결과: 0.414 / 0.320 / 0.265
3. 검증 — LOOCV (Leave-One-Out Cross-Validation)
   • 4 TARGET 각각 hold-out → 나머지 3 개로 학습 → hold-out 정답 판별
   • 결과: 4 / 4 모두 정답
   • 가중치 변동: 0.40 ± 0.02 / 0.32 ± 0.02 / 0.27 ± 0.01 (안정적)

결과 정확도

방식	TARGET 정답
현재 (수동 0.30/0.50/0.20)	4 / 4
Logistic Regression (0.414/0.320/0.265)	4 / 4
OLS Linear (1.0/0.05/-0.05)	3 / 4
BM25 (개별 토큰)	3 / 4
BM25 (세트 포함)	3 / 4
IDF-weighted	3 / 4

발견된 약점

• 02-2.2 (TARGET) : 정답 Frame 14 의 anchor 키워드가 MDX 본문과 거의 안 겹침 → V1 점수 낮음 (V4 까지 가도 reject)

코드 + 결과

• 매칭 코드 : pipeline_06_2_mdx_matching.py
• 가중치 학습 : pipeline_15_logistic_regression.py
• 결과 비교 : pipeline_15_bm25_with_sets.py, pipeline_15_idf_comparison.py
• 결과 파일 : mdx_matching_result.yaml
• 검증 보고서 : ATTACH_07_WEIGHT_VALIDATION.html

---

V2 — 의미 매칭 (semantic rerank)

무엇을 보는가

"키워드는 다르지만 의미가 같은가?" — MDX summary 와 frame.content 의 의미적 유사도.

산식

similarity = cosine(embed(MDX summary), embed(frame.content))

• 모델: jhgan/ko-sroberta-multitask (한국어 Sentence-BERT)

도출 과정

• 별도 가중치 학습 없음. cosine 유사도 그대로 사용.
• V1 Top-K 후보 안에서 의미 유사도로 재정렬.

결과 정확도

• V1 후보 재정렬 단계라 단독 정확도는 별도 측정 X
• V3, V4 의 출발점 (V2 Top-K 후보 → V3 평가)

발견된 약점

• 의미 임베딩 단독으로는 frame 식별력 부족 (도메인 키워드 신호가 더 강함)
• V1 Top-K 가 부정확하면 V2 도 그 한계 안에서 작동

코드 + 결과

• 매칭 코드 : pipeline_08_v2_semantic_rerank.py
• 임베딩 모듈 : embeddings.py
• 결과 파일 : v2_semantic_rerank_result.yaml
• 진단 : pipeline_09_v2_diagnosis.py, V2_DIAGNOSIS.md

---

V3 — 구조 매칭 (structure rerank)

무엇을 보는가

"이 콘텐츠를 담을 수 있는 레이아웃인가?" — MDX 글 구조와 frame 의 구조 속성 비교.

산식

구조 점수 = 0.40 × 레이아웃 일치 + 0.35 × 콘텐츠 성격 일치 + 0.25 × 시각 의도 일치

구성 요소

• 레이아웃 일치 : MDX layout family (table/card/diagram/list) ↔ frame family
• 콘텐츠 성격 : 12 카테고리 키워드 사전 매칭 (concept_definition / comparative_matrix / policy_requirements 등)
• 시각 의도 : 9 카테고리 키워드 사전 매칭 (matrix_coverage / cycle_interrelation / state_transition 등)

MDX 본문 분석 방법

• 레이아웃 자동 감지 : detect_mdx_layout_v2(text) — 표 / 불릿 / 헤딩 패턴 → layout enum → family
• 콘텐츠 성격 : AFFINITY_KEYWORDS 사전 매칭 → 등장 횟수 1위 카테고리 = primary
• 시각 의도 : INTENT_KEYWORDS 사전 매칭 + STRONG 구절 패턴 검증 (예: state_transition 은 "AS-IS / TO-BE" 1개 이상 필요)

도출 과정 (5회 튜닝 r1 → r5)

라운드	변경 내용	결과
r1	초기 키워드 사전 (12 + 9 카테고리)	TARGET 2/4
r2	layout_compat 가중치 조정	TARGET 2/4
r3	STRONG 패턴 검증 도입 (before_after_change, state_transition)	TARGET 3/4
r4	concept_definition 에서 "개념" 제거, hierarchy 단일 키워드 금지	TARGET 3/4
r5	ontology final_r2 (Frame 13 review_queue 해제)	TARGET 4/4

결과 정확도

• TARGET : 4/4 (V2 Top-5 후보 안에서)
• 단, V2 후보가 부정확하면 V3 도 부정확

발견된 약점

• 콘텐츠 성격 / 시각 의도 분류 부정확 : 키워드 사전 매칭이라 단순 카운트
  • 예: MDX 01-2 (DX 와 BIM 의 구분) → 본문에 "국내, 도입, 사례" 가 많아 policy_requirements 1위 (실제 comparative_matrix)
  • 한계: 도메인 키워드 사전 의존, 일반 표현 못 잡음

코드 + 결과

• 매칭 코드 : pipeline_08_v3_r5_structure_rerank.py (최종)
• 의존 모듈 : pipeline_08_v3_r4_structure_rerank.py, pipeline_08_v3_r2_structure_rerank.py, structure_v3.py, phase_common.py
• MDX 분석 : detect_mdx.py
• 결과 파일 : v3_structure_rerank_r5_result.yaml

---

V4 — 종합 판정 (template-fit-v1)

무엇을 보는가

"실제로 쓸 수 있나? 어느 정도 수정해야 하나?" — V1/V2/V3 신호를 합쳐 frame 적용 가능성 판정.

산식

base = 0.25 × anchor + 0.20 × cardinality + 0.20 × relation
     + 0.15 × slot + 0.20 × content

confidence = max(0, base − penalty)

5 축 의미

• anchor (0.25) : MDX detected_terms ↔ frame anchor_sets 매칭 (V1 핵심 키워드 매칭과 유사)
• cardinality (0.20) : MDX 항목 수가 frame cardinality [min, max] 범위 안인가
• relation (0.20) : MDX relation_type (compare/parallel/sequence) ↔ frame relation_type 일치
• slot (0.15) : 휴리스틱 — within(0.5) + has_labels(0.3) + has_bodies(0.2)
• content (0.20) : V2 의미 임베딩 cosine

penalty

• cardinality mismatch 시 adaptation_cost 부과 (split / merge / infer_missing)
• not_suits 패턴 매치 시 not_suits_penalty
• 합계 capped at CAP_TOTAL

임계값 라우팅

라벨	confidence	의미	후속 작업
use_as_is	≥ 0.90	그대로 사용	슬롯에 텍스트만 매핑 (자동)
light_edit	≥ 0.75	가벼운 편집	AI 1 호출 (텍스트 다듬기)
restructure	≥ 0.60	구조 재배치	사람 + AI 여러 호출
reject	< 0.60	사용 불가	신규 디자인

도출 과정

1. r1 (V3 Top-K 평가만) : V3 Top-5 안에서 confidence 산출 → 5개 중 선택
2. r2 (안정화) : V2 후보 재선정 + adaptation_allowed 검증 추가
3. full32 (최종) : 32 frame 전체 평가 → 진정한 reject 식별 가능

결과 정확도

• TARGET : 3/4 (use_as_is 매칭 성공)
  • 01-2 ✓ (Frame 18, conf 0.946)
  • 02-2.2 ✗ (정답 Frame 14, V4 순위 7, reject)
  • 03-1 ✓ (Frame 13, conf 0.927)
  • 03-2 ✓ (Frame 29, conf 0.920)
• Holdout : 사람 검수자 합리적 수준

발견된 약점

slot 축 ablation 결과

• W_SLOT=0 으로 두고 4축 재정규화 → V4 재계산
• Top-1 매칭 7/7 동일 (모든 섹션)
• TARGET Top-1 정답률: Baseline 3/4 → Ablated 3/4 (동일)
• → slot 축은 frame 선별에 영향 없음. 라벨 게이트 역할만 (use_as_is ↔ light_edit 임계 통과 여부)

cardinality 중복 가중

• cardinality 축 (0.20) 과 slot.within (0.075) 이 같은 신호를 두 번 평가
• item_count = len(slot_candidates) 로 동일

슬롯 의미 매핑 부재

• frame 의 146 개 의미 slot id (title, col_a_label, col_b_label, rows 등) 가 V4 점수 계산에 활용 안 됨
• "BIM → col_a_label" 같은 의미 매핑은 코드에 없음 — 후속 단계 책임

표 첫 행만 추출

• MDX 가 4 행 표여도 첫 행만 본문으로 추출. 나머지 행 (S/W·프로세스·성과품) 무시

코드 + 결과

• 매칭 코드 : pipeline_17_v4_full32.py (최종, 32 frame 전체)
• 의존 모듈 : template_fit.py
• Ablation : pipeline_18_slot_axis_ablation.py
• 결과 파일 : v4_full32_result.yaml
• Ablation 보고서 : V4_SLOT_ABLATION.md

---

새 pipeline 통합 시 frame 단위 — 명확화

주의 : 이 매칭 시스템 (V1~V4) 은 frame 32 개를 슬라이드 1장 단위로 검증 함 (예: Frame 18 = BIM/DX 비교 슬라이드 통째로).

새 pipeline 의 위계는 슬라이드 ⊃ slide-base ⊃ slide-body ⊃ 레이아웃 ⊃ Zone ⊃ 프레임 이며, 여기서 프레임 = zone 안 디자인 단위 임.

→ frame DB 의 사이즈 라벨링 재검토 필요:

• 어떤 frame = 슬라이드 전체 (= 레이아웃 그 자체)
• 어떤 frame = zone 1 개 단위 (= 부분 디자인)
• 작은 박스 단위도 가능

새 pipeline 통합 작업의 사전 준비 항목 (../IMPROVEMENT-REDESIGN.md 의 7.1 참조)

---

사후 작업 (V4 이후)

보고서 (DECK 1 ~ 7)

파일	내용
DECK_01_TARGET_01_2.html	TARGET 01-2 × V1~V4 Top-3 매칭 결과
DECK_02_HOLDOUT_02_2_1.html	Holdout 02-2.1 × V1~V4 Top-3
DECK_03_METHODS.html	V1~V4 방법 설명
DECK_04_DB_STRUCTURE.html	MDX 1 vs Top-3 frame 5 컬럼 비교표
DECK_05_STRUCTURE_KEYWORD.html	구조 매칭 4 항목 상세 (콘텐츠 성격 / 시각 의도 / 편집 슬롯 / 항목수·관계)
DECK_06_FIGMA_TO_DB.html	Frame 18 의 DB 저장 형태 샘플 (YAML)
DECK_07_KEYWORD_PIPELINE.html	키워드집 정리 과정 + Frame 18 샘플

생성 코드 : pipeline_16_deck_4pages.py

보조 보고서

파일	내용
KEYWORD_INVENTORY.html	키워드집 생성 보고서 (1,713 고유 + 13 중요 표기)
ATTACH_07_WEIGHT_VALIDATION.html	V1 가중치 Logistic Regression 검증
V4_SLOT_ABLATION.md	V4 slot 축 ablation 결과
FIGMA_KEYWORDS_REPORT.html	Frame 별 키워드 인벤토리
FRAME_KEYWORD_REVIEW.html	Frame 별 키워드 검토

---

발견된 약점 종합 (8 가지)

#	약점	발견 시점	우선순위
1	02-2.2 매칭 실패 (정답 Frame 14 reject)	V4 결과	🥇 1순위
2	MDX 콘텐츠 성격 분류 부정확 (키워드 사전 한계)	V3 r5 검토	🥈 2순위
3	MDX 시각 의도 분류 부정확 (동일 한계)	V3 r5 검토	🥈 2순위
4	편집 슬롯 의미 매핑 부재	V4 코드 검토	🥉 3순위
5	V4 cardinality 중복 가중	ablation	🥉 3순위
6	V4 slot 축 frame 선별 무영향	ablation	🥉 3순위 (4 + 5 와 함께)
7	표 첫 행만 추출 (다행 무시)	DECK 04 정직성 점검	4순위
8	그림/이미지 frame 매칭 약함	V3 r5 검토	4순위

다음 단계 (개선 방향)

작업	내용	공수
02-2.2 교정	Frame 14 anchor_sets 재라벨링 + 도메인 키워드 보강 → TARGET 4/4	1~2 일
MDX 분석 LLM 화	콘텐츠 성격 / 시각 의도를 키워드 사전 → Anthropic API 호출	3~5 일
슬롯 의미 매핑 모듈	"BIM → col_a_label" 매핑 + V4 slot 축 진짜 역할 부여	5~7 일
표 다행 처리	rows 슬롯 채우기용 다행 추출	2~3 일
그림 매칭 강화	본문 이미지 + 텍스트 결합 분석	2~3 일

---

핵심 메시지 (3 줄 요약)

1. TARGET 75% (3/4) — V1 가중치는 Logistic Regression 으로 검증 (LOOCV 4/4), BM25 / IDF 보다 우위
2. 약점: V3 의 콘텐츠 성격 / 시각 의도가 키워드 사전 기반이라 부정확. V4 의 slot 축은 ablation 으로 frame 선별 무영향 확인
3. 다음 단계: 02-2.2 교정 (12일) → MDX 분석 LLM 화 (35일) → 슬롯 의미 매핑 모듈 (5~7일)