1. 스펙 검증하기

이 장에서는 EulerStack 의 첫 번째 단계인 YAML 스펙 검증 을 다룹니다. 어떤 모델을 만들기 전에, 작성한 YAML 이 구조적으로 올바르고 서로 모순되지 않는지를 먼저 확인해야 합니다. 이 절차를 건너뛰면 훈련 도중에 조용한 실패가 발생하여 GPU 시간을 낭비하게 됩니다.

왜 검증이 필요한가?

LLM 아키텍처 스펙은 수십 개의 파라미터가 서로 의존하는 복잡한 설정 묶음입니다. 예를 들어 d_model 은 n_heads 로 나누어떨어져야 하며, mixer.type: mamba 를 고른 레이어에는 state.kv_cache: true 를 같이 둘 수 없습니다. 이런 제약은 수십 가지가 존재하고, 사람 눈으로 일일이 확인하기 어렵습니다.

검증되지 않은 스펙을 곧바로 훈련에 넣으면 다음과 같은 문제가 생깁니다.

• 즉시 실패: 모델 생성 단계에서 RuntimeError 와 함께 중단. 원인 메시지가 모호해 디버깅에 시간이 많이 걸립니다.
• 조용한 실패: 모델은 생성되지만 파라미터가 기대와 달라 훈련이 느리거나 수렴하지 않습니다. 수 시간 GPU 를 쓴 뒤에야 발견됩니다.
• 성능 저하: 검증 자체는 통과하지만 head_dim 이 비상식적으로 작거나 크게 잡혀 같은 예산에서 더 나빠질 수 있습니다. 이런 경우는 realism 경고로 드러냅니다.

이 모든 문제를 훈련 전 에 잡아내는 것이 검증의 목적입니다.

검증의 세 가지 계층

EulerStack 의 검증은 다음 세 단계로 이루어집니다. 각 단계는 독립적으로 돌아가며, 앞 단계를 통과해야 다음 단계로 넘어갑니다.

1. 스키마 검증 (structural validation) YAML 이 정해진 키 구조와 타입/열거형을 따르는지 확인합니다. 오타, 필수 필드 누락, 잘못된 값이 여기서 걸립니다. 예: modle.d_model (오타), mixer.type: "transformer" (존재하지 않는 enum).

2. 교차 필드 검증 (cross-field validation) 구조는 맞지만 필드들의 조합 이 모순되는 경우를 잡습니다. 예: n_heads=8 인데 n_kv_heads=3 인 경우, GQA 비율 8÷3 이 정수가 아니므로 불가능합니다.

3. 실사용성 검증 (realism checks) 수학적으로는 가능하지만 경험적으로 나쁜 선택 을 경고합니다. 예: head_dim=16 은 너무 작고 head_dim=512 는 너무 큽니다. 이런 경고는 차단하지 않고 리포트에만 나타납니다.

이 세 계층을 나눈 이유는 책임 분리 입니다. 스키마 위반은 버그이고, 교차 필드 위반은 설계 오류이며, realism 경고는 취향 문제입니다. 각각 다른 수준의 심각도를 가지므로 메시지도 따로 보여줍니다.

기본 사용법

가장 단순한 검증 명령은 다음과 같습니다.

eulerstack validate --preset my_model.yml

검증이 통과되면 한 줄로 결과를 알려줍니다.

OK: my_model.yml 은(는) 유효한 스펙입니다.

실패할 경우에는 세 줄 에러 포맷 으로 원인, 해결 방법, 참고 문서를 한꺼번에 보여줍니다.

ValidationError: model.d_model (65) must be divisible by model.n_heads (8)
Fix: d_model 또는 n_heads 를 조정하여 d_model % n_heads == 0 이 되게 하세요
See: docs/architectures/yaml_v1_spec.md

이 포맷은 EulerStack 전체 CLI 의 공통 에러 포맷이며, 어떤 에러를 만나도 무엇이, 어떻게 고치는지, 어디를 읽을지 가 항상 같이 나옵니다.

언어 변경

모든 CLI 메시지는 5개 언어를 지원합니다. --lang 옵션으로 언어를 바꿀 수 있습니다.

eulerstack --lang en validate --preset my_model.yml   # English
eulerstack --lang zh validate --preset my_model.yml   # Chinese (Simplified)
eulerstack --lang ja validate --preset my_model.yml   # Japanese
eulerstack --lang es validate --preset my_model.yml   # Spanish

기본 언어는 한국어(ko) 입니다. 환경 변수 EULERSTACK_LANG 로도 설정할 수 있습니다.

export EULERSTACK_LANG=en
eulerstack validate --preset my_model.yml   # English 로 출력

언어 우선순위는 --lang 옵션 > EULERSTACK_LANG 환경변수 > 기본값(ko) 입니다.

상세 리포트

--report 플래그를 붙이면 단순 OK/FAIL 이상의 정보를 얻을 수 있습니다. 리포트는 스키마/교차/realism 세 단계의 결과를 모두 포함하며, 추정 파라미터 수 와 레이어 구성 분해 도 같이 출력됩니다.

eulerstack validate --preset configs/presets/arch_advanced_jamba.yml --report

리포트에 포함되는 주요 항목은 다음과 같습니다.

• Schema: OK 또는 구체적인 에러
• 추정 파라미터: 예 2.39B (2,392,301,568)
• 총 레이어 수와 분해: 예 32 (attention:8, mamba:24)
• Realism 경고: head_dim 범위, MoE 비율, seq_len/d_model 비율 등
• INFO: 레이어 템플릿 구성 내역

리포트는 훈련에 들어가기 전에 이 모델이 정말 내가 의도한 대로 구성되었는지 를 시각적으로 확인하는 용도로 유용합니다.

어떤 오류가 걸리는가

아래는 스키마와 교차 필드 검증에서 자주 걸리는 오류들의 예시입니다. 왼쪽 컬럼은 오류 종류, 가운데는 잘못된 YAML 의 예시, 오른쪽은 내부 규칙 번호입니다.

Realism 경고(차단하지 않음)로는 다음이 있습니다.

• head_dim < 32 또는 head_dim > 256
• target_params 가 추정치와 30% 이상 차이
• experts > 64 와 같이 과도한 전문가 수
• max_seq_len / d_model > 64배 인 비현실적 비율
• family_hint 가 실제 믹서 구성과 불일치

다음 단계

검증이 끝나면 모델 구조를 눈으로 확인하는 단계로 넘어갑니다.

• 튜토리얼 2: 프리셋 사용 — 이미 검증된 53 개 프리셋 탐색
• 튜토리얼 4: 컴파일과 설명 — 구조를 자세히 보는 explain
• 믹서 개요 — 각 믹서가 무엇을 하는지