spk2path 가이드 — 학습 list 생성 운영

harness xdata export --format spk2path 가 registry 의 variant/PV 를 학습 측이 read 하는 양식 (<alias> <path>\n) 으로 generate 한다. design v7 (2026-05-27) 정본.

관련 결정:

• ADR 0004 — speaker_key 불변
• ADR 0012 — natural_key 5축 + variation paradigm (supersedes ADR 0007)
• ADR 0008 — inclusion_policy / EXPERIMENTAL_AXES
• ADR 0011 — phoneme_encoding enum
• 경로 규약: fs-path-convention.md

1. v1 책임 범위

2. CLI 사용법

PYTHONPATH=/HDD1/raymond/xvoice3 XDATA_SCHEMAS_MODULES=xdata_plugin \
python -m tools.xdata.cli export \
  --project xvoice3 \
  --registry /HDD1/raymond/xvoice3/data_list/registry.v3.json \
  --format spk2path \
  --pv-priority "reduce_brth_trimIP,vanilla" \
  --server nfs_train \
  --skip-report /tmp/spk2path_skip.json \
  --out data_list/spk2path_v2_$(date +%Y%m%d)

3. alias 해결 흐름

speaker_key (디렉토리 정본, ADR-0004 불변) → alias (spk2path 첫 컬럼) 변환:

1. yaml 룩업 (tools/xdata/spk2path_alias.yaml) — speaker_key entry 있으면 룩업값. 현재 1 entry: kh → khj (character ADD).
2. algorithm fallback — re.sub(r'_(\d+h|\d{4})$', '', speaker_key). 시간단축 (_5h/10h/20h) + 연도 vintage (_2023) suffix strip.
3. identity — 위 둘 다 적용 후 변경 없는 화자 (대다수).

예시:

• kh → khj (룩업)
• kjy_20h → kjy (algorithm)
• bom_2023 → bom (algorithm)
• ace → ace (identity)

운영자 PR 로 yaml entry 추가 시 row 구조:

aliases:
  - speaker_key: <디렉토리명>
    alias: <학습 측 alias>
    source: default

row 구조는 future NocoDB speakers row 와 isomorphic — v2 manifest 진입 시 1 entry INSERT 로 NocoDB 이관 가능.

4. inclusion_policy 운영 정책

dataset_variants.inclusion_policy (ADR-0008) 가 학습 진입 여부 결정:

• default — 학습 진입 (spk2path emit 대상)
• excluded — 학습 제외 (spk2path 자동 skip)

시간단축 분기 패턴 (kjy_5h, kjy_10h, kjy_12h, yrk_5h, yrk_10h, ysh_10h 등): 같은 화자의 데이터 양 단축 실험 variant. 운영자가 inclusion_policy=excluded 박아서 학습 제외. spk2path 의 _20h 정본 variant 만 emit → alias 충돌 0건.

새 시간단축 분기 등록 시 운영자 액션:

1. fs-sync 가 새 디렉토리 발견 → inclusion_policy=default 자동 부여 (기본값).
2. 운영자가 NocoDB 에서 inclusion_policy=excluded 명시 박아야 함 — 안 박으면 spk2path 가 새 분기까지 emit → alias 충돌.
3. 확인 = spk2path 재생성 + 행수 + stderr 경고 검수.

5. alias 충돌 진단

같은 alias 가 2+ speaker_key 에 매핑되면 stderr 경고:

warning: alias collision — 'kjy' maps to speaker_keys ['kjy_5h', 'kjy_20h']

기본 동작 (--alias-strict off):

• stderr 경고 + duplicate line emit (운영자가 출력 검수 시 발견)
• 출력 파일에 같은 alias 가 다른 path 로 2+ 라인 → spot-check 가능

--alias-strict 활용 시점:

• 운영자가 inclusion_policy 정확히 박았다는 확신 검증 시
• CI 게이트 (학습 진입 전 자동 검수)
• 예시: harness xdata export --format spk2path --alias-strict ...

진단 케이스:

1. 새 시간단축 분기 inclusion_policy 누락 — 운영자가 NocoDB patch.
2. character ADD 변종 발견 — 운영자가 alias yaml entry 추가.
3. --include-excluded 와 spk2path 조합 — §7 참조.

6. AI_HUB 자동 제외

v1 default = data_source ∈ {internal, internal_processed} 한정 (_XVOICE3_DS, tools/xdata/exporters/manifest.py:170).

AI_HUB emotion PV (data_source=ai_hub_emotion) 는 자동 skip. skip-report 의 no_xvoice3_pv reason 으로 보고됨.

운영자가 명시 포함 시:

--filter data_source=ai_hub_emotion

7. --include-excluded 조합 위험

--include-excluded 사용 시 inclusion_policy=excluded variant 도 export pipeline 재진입. spk2path 와 조합 시:

• 시간단축 분기 (kjy_5h/10h/12h) 가 다시 emit → alias kjy 가 4 speaker_key 로 collapse
• alias 충돌 다수 발생 → stderr 경고 폭증 또는 --alias-strict 시 fail

권장: --include-excluded 는 spk2path 와 조합 금지. 검수/감사 용도에서만 사용 (--format csv 등). 의도적 사용 시 --alias-strict 같이 박지 말 것.

8. skip-report 구조

{
  "skipped": [
    {
      "variant_natural_key": "kea/KOR/common/ip_info/vanilla",
      "reason": "server_path_missing",
      "attempted_priorities": ["reduce_brth_trimIP", "vanilla"],
      "phoneme_source": "ip_info"
    }
  ],
  "summary": {
    "by_reason": {
      "no_xvoice3_pv": 439,
      "server_path_missing": 0,
      "no_priority_match": 0
    }
  }
}

reason 목록:

9. 검증 시퀀스

운영 spk2path 생성 후 검수:

# 1. 행수 + 화자 수
wc -l data_list/spk2path_v2_<date>
awk '{print $1}' data_list/spk2path_v2_<date> | sort -u | wc -l

# 2. path 유효성 (별 명령, design v7 권장)
harness xdata verify-paths --input data_list/spk2path_v2_<date>   # v2 도입 예정

# 3. skip-report reason 분포
jq '.summary.by_reason' /tmp/spk2path_skip.json

# 4. alias unique 확인
awk '{print $1}' data_list/spk2path_v2_<date> | sort | uniq -d   # 중복 alias 출력

10. v2 로 가는 길

v1 의 한계 + v2 manifest 도입 시점:

• --source manifest:<path> mode 도입 — variant-level 큐레이션 override
• csv_exports.yaml 통합 (format: spk2path entry) — manifest.py 의 format-based dispatch refactoring 별 라운드
• spk2path_ip_info2, patx2, kby_single, manual_lyj 같은 변종 다수 흡수

v2 도입 결정 = 운영자 큐레이션 패턴이 manifest yaml 로 자동화 가능해질 때.