튜토리얼 8: 메트릭 블록 사용하기

eulerweave의 metrics 슬롯을 사용하면 파이프라인 실행 중 데이터셋 품질 통계를 자동으로 수집할 수 있습니다. 메트릭 블록은 레코드를 변경하지 않으며(pass-through), 결과를 아티팩트 디렉터리에 JSON 파일로 저장합니다.

사전 요구 사항: 튜토리얼 1: 빠른 시작을 완료했어야 합니다.

사용 가능한 메트릭 블록

블록 타입	설명
`metrics_text_basic`	텍스트 길이 분포, 빈 텍스트 비율, 문자셋 통계
`metrics_quality_heuristic`	URL/반복/알파벳숫자/한글 비율 분석
`metrics_dedup_report`	중복 감지율, 제거율, 상위 클러스터 리포트
`metrics_task_format_validate`	SFT/DPO 메시지 형식 유효성 검사
`metrics_text_distribution`	텍스트 분포 상세 분석
`metrics_language_heuristic`	언어별 비율 분석
`metrics_text_repetition`	n-gram 반복률 (char 3-gram, word 5-gram, line dup)
`metrics_text_gibberish`	기호/숫자/공백 이상, unicode 엔트로피, gibberish 감지
`metrics_text_boilerplate`	웹 보일러플레이트 패턴 감지 (쿠키, 네비, CTA)
`metrics_perplexity`	HuggingFace Transformers 기반 perplexity/loss 점수 (Qwen3-0.6B, gpt2 등)
`metrics_token_stats`	토큰 수 통계 (평균, 중앙값, p95, TTR 어휘 다양성)
`metrics_pii_detect`	PII 패턴 탐지 (이메일, 전화번호, SSN, 신용카드, IP)
`metrics_record_schema_validate`	레코드 스키마 일관성 검증 (빈 텍스트, null 필드 감지)

1단계: 매니페스트에 메트릭 추가

메트릭 블록은 metrics 슬롯에 속하며, enrich 이후 build_task 이전에 배치합니다:

version: 1
track: sft
inputs:
  - type: jsonl
    uri: data/train.jsonl

pipeline:
  - id: norm1
    type: normalize_text
    slot: normalize
    input_type: TextDocument
    output_type: TextDocument

  - id: filter1
    type: heuristic_filter
    slot: filter
    input_type: TextDocument
    output_type: TextDocument

  - id: m1
    type: metrics_text_basic
    slot: metrics
    input_type: TextDocument
    output_type: TextDocument

  - id: m2
    type: metrics_quality_heuristic
    slot: metrics
    input_type: TextDocument
    output_type: TextDocument

  - id: sft1
    type: build_sft_messages
    slot: build_task
    input_type: TextDocument
    output_type: SFTMessages

  - id: exp1
    type: export_jsonl
    slot: export
    input_type: SFTMessages
    output_type: ExportedDataset

exports:
  - type: jsonl
    path: out/result.jsonl

핵심 사항:

input_type과 output_type이 동일해야 합니다 (pass-through).
같은 metrics 슬롯에 여러 블록을 배치할 수 있습니다.
블록 id는 고유해야 합니다.

2단계: 실행 및 결과 확인

eulerweave run manifest.yaml --input data/train.jsonl

실행 완료 후, 아티팩트 디렉터리에 메트릭 결과가 저장됩니다:

artifacts/{run_id}/
  metrics/
    metrics_text_basic.json
    metrics_quality_heuristic.json
  report.json

3단계: 메트릭 결과 해석

metrics_text_basic.json

{
  "metric_name": "metrics_text_basic",
  "version": "1.0",
  "computed_at": "2026-02-26T12:00:00Z",
  "summary": {
    "record_count": 1000,
    "empty_text_count": 5,
    "avg_length": 245.3,
    "p50_length": 200,
    "p95_length": 580,
    "max_length": 1500,
    "ascii_ratio": 0.92
  },
  "warnings": [],
  "params": {}
}

해석 가이드:

empty_text_count > 0 → 빈 텍스트 레코드 있음, 필터링 고려
p95_length 너무 큼 → heuristic_filter의 max_length 조정
ascii_ratio 낮음 → 다국어 데이터 포함

metrics_quality_heuristic.json

{
  "metric_name": "metrics_quality_heuristic",
  "summary": {
    "avg_url_ratio": 0.02,
    "avg_repeat_ratio": 0.05,
    "avg_alnum_ratio": 0.85,
    "avg_hangul_ratio": 0.0
  }
}

해석 가이드:

avg_url_ratio > 0.1 → URL이 많음, 정제 필요
avg_repeat_ratio > 0.3 → 반복 텍스트가 많음, 중복 제거 필요
avg_hangul_ratio > 0 → 한글 데이터 포함

metrics_text_repetition.json

{
  "metric_name": "metrics_text_repetition",
  "summary": {
    "record_count": 1000,
    "analyzed_count": 1000,
    "avg_char_3gram_dup_ratio": 0.12,
    "avg_word_5gram_dup_ratio": 0.05,
    "avg_line_dup_ratio": 0.03
  }
}

해석 가이드:

avg_char_3gram_dup_ratio > 0.3 → 문자 수준 반복이 높음, RefinedWeb MDR 신호
avg_word_5gram_dup_ratio > 0.3 → 구문 반복, 복사-붙여넣기 텍스트 의심
avg_line_dup_ratio > 0.5 → 동일 라인 반복, 로그/자동생성 데이터 의심

metrics_text_gibberish.json

{
  "metric_name": "metrics_text_gibberish",
  "summary": {
    "record_count": 1000,
    "analyzed_count": 1000,
    "avg_symbol_ratio": 0.05,
    "avg_digit_ratio": 0.03,
    "avg_whitespace_anomaly": 0.01,
    "unicode_category_entropy": 2.8,
    "gibberish_suspect_count": 12
  }
}

해석 가이드:

gibberish_suspect_count > 0 → 해당 레코드 수만큼 품질 불량 의심
avg_symbol_ratio > 0.3 → 기호 텍스트(코드/장식문자) 비율 높음
avg_digit_ratio > 0.5 → 숫자 데이터가 많음 (전화번호, 식별자 등)

metrics_text_boilerplate.json

{
  "metric_name": "metrics_text_boilerplate",
  "summary": {
    "record_count": 1000,
    "analyzed_count": 1000,
    "avg_boilerplate_line_ratio": 0.08,
    "nav_pattern_count": 15,
    "cookie_pattern_count": 8,
    "cta_pattern_count": 12
  }
}

해석 가이드:

avg_boilerplate_line_ratio > 0.3 → 웹 크롤 데이터의 정제가 부족
cookie_pattern_count 높음 → 쿠키/개인정보 고지 텍스트 포함
nav_pattern_count 높음 → 네비게이션 메뉴 텍스트 포함

metrics_perplexity.json

{
  "metric_name": "metrics_perplexity",
  "summary": {
    "record_count": 1000,
    "analyzed_count": 1000,
    "avg_perplexity": 45.2,
    "p50_perplexity": 38.1,
    "p95_perplexity": 120.5,
    "max_perplexity": 350.0,
    "avg_loss": 3.81,
    "model_used": "Qwen/Qwen3-0.6B"
  }
}

해석 가이드:

avg_perplexity < 100 → 자연스러운 텍스트 (C4/FineWeb 기준)
avg_perplexity 100~500 → 도메인 특수 텍스트 또는 노이즈 혼재
avg_perplexity > 500 → gibberish/노이즈 데이터 의심
p95_perplexity ≫ p50_perplexity → 꼬리 분포에 이상 데이터 존재

참고: Perplexity 블록은 HuggingFace Transformers (torch + transformers)가 필요합니다. CI에서는 FakeScorer가 자동으로 사용됩니다. 자세한 설정은 튜토리얼 10: Perplexity 메트릭을 참조하세요.

metrics_token_stats.json

{
  "metric_name": "metrics_token_stats",
  "summary": {
    "record_count": 1000,
    "analyzed_count": 1000,
    "total_tokens": 245000,
    "avg_tokens_per_record": 245.0,
    "median_tokens": 200,
    "p95_tokens": 580,
    "min_tokens": 3,
    "max_tokens": 1500,
    "type_token_ratio": 0.42,
    "tokenizer_used": "whitespace"
  }
}

해석 가이드:

avg_tokens_per_record < 10 → 매우 짧은 문서, 필터링 기준 검토
type_token_ratio (TTR) > 0.8 → 어휘 다양성 높음 (다양한 주제)
type_token_ratio < 0.2 → 어휘 다양성 낮음 (반복적/제한적 텍스트)
p95_tokens ≫ median_tokens → 긴 꼬리 분포, 일부 매우 긴 문서 존재

참고: 기본 tokenizer는 whitespace입니다. params.tokenizer에 HuggingFace 모델 이름을 지정하면 서브워드 토크나이저를 사용할 수 있습니다.

metrics_pii_detect.json

{
  "metric_name": "metrics_pii_detect",
  "summary": {
    "record_count": 1000,
    "analyzed_count": 1000,
    "records_with_pii": 45,
    "total_pii_instances": 78,
    "email_count": 30,
    "phone_count": 20,
    "ssn_count": 5,
    "credit_card_count": 8,
    "ip_count": 15
  },
  "warnings": [{"code": "pii_detected", "message": "45 records contain PII patterns"}]
}

해석 가이드:

records_with_pii > 0 → PII가 포함된 데이터, filter_pii_redact로 마스킹 권장
ssn_count 또는 credit_card_count > 0 → 민감 금융/개인 정보, 즉시 처리 필요
email_count 높음 → 웹 크롤 데이터에서 흔함, 이메일 마스킹 적용

참고: PII 마스킹이 필요하면 튜토리얼 11: PII 안전을 참조하세요.

metrics_record_schema_validate.json

{
  "metric_name": "metrics_record_schema_validate",
  "summary": {
    "record_count": 1000,
    "valid_count": 985,
    "invalid_count": 15,
    "valid_ratio": 0.985,
    "invalid_sample_count": 15
  },
  "warnings": []
}

해석 가이드:

invalid_count > 0 → 빈 텍스트 또는 null 필드가 있는 레코드 존재
valid_ratio < 0.8 → 데이터 품질 심각, fail_threshold_ratio 경고 발생
debug/invalid_records.jsonl 아티팩트에서 불량 레코드 샘플 확인 가능

참고: 불량 레코드 디버깅은 튜토리얼 12: 불량 레코드 디버깅을 참조하세요.

4단계: 샘플링으로 대규모 데이터셋 최적화

대규모 데이터셋에서는 전체 레코드를 분석하면 시간이 오래 걸립니다. sample_rate와 sample_max_records로 샘플링합니다:

  - id: m1
    type: metrics_text_basic
    slot: metrics
    input_type: TextDocument
    output_type: TextDocument
    params:
      sample_rate: 0.1          # 10% 샘플링
      sample_max_records: 5000  # 최대 5000개
      seed: 42                  # 재현 가능한 샘플링
    cost_model:
      per_record_ms: 0.5

eulerweave plan이 이 파라미터를 인식하여 비용 추정에 반영합니다:

eulerweave plan manifest.yaml --records 100000
# [m1] metrics_text_basic
#   → Text length distribution, emptiness, charset stats
#   Time: ~2500ms           # 5000 * 0.5ms (샘플링 적용)

PDF 파이프라인에서 메트릭 활용

PDF → QnA 파이프라인에 메트릭을 추가하면 데이터 품질을 모니터링할 수 있습니다:

version: 1
track: sft

inputs:
  - type: pdf
    uri: data/paper.pdf
    options:
      strategy: auto

pipeline:
  - id: norm1
    type: normalize_text
    slot: normalize
    input_type: TextDocument
    output_type: TextDocument

  - id: filter1
    type: heuristic_filter
    slot: filter
    input_type: TextDocument
    output_type: TextDocument
    params:
      min_length: 100

  - id: dedup1
    type: dedup_exact
    slot: dedup
    input_type: TextDocument
    output_type: TextDocument

  - id: m1
    type: metrics_text_basic
    slot: metrics
    input_type: TextDocument
    output_type: TextDocument

  - id: m2
    type: metrics_quality_heuristic
    slot: metrics
    input_type: TextDocument
    output_type: TextDocument

  - id: qna1
    type: build_langextract_qna
    slot: build_task
    input_type: TextDocument
    output_type: SFTQnA
    params:
      model: "gpt-oss:20b"

  - id: exp1
    type: export_jsonl
    slot: export
    input_type: SFTQnA
    output_type: ExportedDataset

exports:
  - type: jsonl
    path: out/training_data.jsonl

profile:
  cpu_only: false
  allow_external_llm: true

report.json의 메트릭 요약

실행 보고서에도 각 메트릭의 요약이 포함됩니다:

{
  "run_id": "a1b2c3d4",
  "status": "completed",
  "records_input": 10000,
  "records_output": 9500,
  "metrics": {
    "metrics_text_basic": {
      "record_count": 10000,
      "avg_length": 245.3
    },
    "metrics_quality_heuristic": {
      "avg_url_ratio": 0.02,
      "avg_alnum_ratio": 0.85
    }
  }
}

다음 단계

튜토리얼 10: Perplexity 메트릭 — Transformers 설정 및 Perplexity 블록 심화
튜토리얼 11: PII 안전 — PII 탐지 및 마스킹 워크플로
튜토리얼 12: 불량 레코드 디버깅 — 데이터 스키마 검증 및 불량 행 추적
튜토리얼 2: PDF → 훈련 데이터 — PDF 파이프라인
튜토리얼 4: SFT 트랙 심화 — 빌더 블록 비교
아키텍처: 엔진 — 메트릭 블록의 내부 동작
아키텍처: 스펙 — MetricsResult 스키마