3. 스펙 레퍼런스

이 장은 EulerStack YAML 의 모든 필드를 한곳에서 설명 하는 레퍼런스 문서입니다. 앞 장에서 프리셋을 훑었다면, 이 장에서는 프리셋 안에 있는 모든 필드가 어떤 의미이고 어떤 제약을 가지며 서로 어떻게 상호작용하는지 하나씩 확인합니다.

EulerStack 의 핵심 가치는 "모델 아키텍처를 조립식으로 설계 할 수 있게 한다" 는 점입니다. 이 조립 과정 전체는 이 한 YAML 파일 안에서 일어납니다. 즉, 이 장의 내용을 정확히 이해하는 것이 EulerStack 으로 새 아키텍처를 만드는 모든 일의 기반이 됩니다.

스펙의 전체 구조

모든 YAML 은 다음 8 개 핵심 블록 + 3 개 선택 블록 (v1 Phase B 확장) 으로 이루어집니다. 순서에 의미는 없지만 관례상 아래 순서로 씁니다.

schema_version: 1

# ── 핵심 8 블록 (모든 YAML 의 기본 골격) ──
let:                  # (선택, Phase B1.2) 수식 변수 — ${let.x} 로 참조
model:                # 1. 모델의 기본 차원과 크기
tokenizer_contract:   # 2. 어떤 토크나이저를 기대하는지
embedding:            # 3. 토큰 임베딩 + 위치 인코딩
layer_templates:      # 4. 각 레이어의 청사진 (재사용 가능한 빌딩 블록)
layer_schedule:       # 5. 레이어를 어떤 순서로 쌓을지 (v1 에서 parallel /
                      #    integrator 도 가능 — §15 참조)
head:                 # 6. 출력 헤드 (causal LM)
training_hints:       # 7. 훈련 시 참고값 (필수 아님)
compatibility:        # 8. 컴파일 타겟

# ── v1 Phase B 확장 블록 (선택) ──
execution_modes:      # (선택, Phase B5) 2-phase 추론 (think/answer) 선언
transition:           # (선택, Phase B5) phase 전환 규칙 (`<think_end>` 등)

검증 (eulerstack validate) 은 이 블록들이 전부 존재하고 서로 모순되지 않는지 확인합니다. 누락 / 오타 / 타입 불일치는 훈련 전 에 전부 걸립니다.

v1 Phase B 신규 primitive (per-layer override, let expressions, MLA latent_dim, branched mixer, ttt_layer, depth_gating / MoD, parallel / integrator schedule, template.memory, template.shape_change, execution_modes) 의 상세 사용법은 09_new_primitives_walkthrough.md 에서 step-by-step 으로 다룹니다. 이 §1–§14 는 핵심 구조 에 집중하고, Phase B 확장은 §15 에서 요약합니다.

1. schema_version

schema_version: 1

스키마 버전 번호. 현재 버전은 1 한 종류입니다. 생략할 수 없으며, 값이 1 이 아니면 검증이 즉시 실패합니다. 이 필드의 존재 이유는 스키마가 미래에 바뀌어도 기존 YAML 이 동작을 보장할 수 있게 하기 위함 입니다. 새 버전이 도입되면 schema_version: 2 등으로 분기됩니다.

2. model 블록

모델의 기본 차원을 정의하는 블록입니다. 이 한 블록이 모델의 "키, 몸무게, 허리둘레" 에 해당합니다. 숫자 몇 개로 전체 크기가 결정됩니다.

model:
  name: "arch-beginner-llama"
  family_hint: "llama-like"
  d_model: 1536
  vocab_size: 32000
  max_seq_len: 4096
  n_heads: 16
  n_kv_heads: 4
  mlp_ratio: 4
  dtype: bfloat16
  target_params: 1_000_000_000

2.1 `name`

사람이 읽는 식별 라벨입니다. 파이썬 변수명이 아니므로 하이픈이나 공백을 써도 됩니다. 실제 식별자는 파일 이름 (arch_beginner_llama.yml) 입니다. 이 필드는 presets show 출력과 로그에 그대로 나타납니다.

2.2 `family_hint`

이 모델이 어떤 계열에 속하는지 알려주는 메타데이터입니다. 예: llama-like, jamba-like, blackmamba-moe. 실사용성 검증 단계에서 "family 가 llama 인데 믹서가 mamba 다" 같은 불일치를 감지하는 데 사용됩니다. 경고를 내지만 검증을 차단하지는 않습니다.

2.3 `d_model` (중요)

모델의 은닉 차원 입니다. 각 토큰이 내부적으로 이 크기의 벡터로 표현됩니다. 모든 선형 변환, attention 투영, FFN 의 중심 차원이 d_model 을 기준으로 계산됩니다.

파라미터 수는 d_model² 에 거의 비례합니다.
Attention 계산량도 d_model² 에 비례합니다.
GPU 메모리 사용량과 정비례 관계입니다.

일반적인 값:

모델 규모	전형적인 d_model
작은 (~100M)	512, 768
소형 (~1B)	1024, 1280, 1536
중형 (~2B)	1536, 2048
대형 (~7B)	4096
초대형 (~70B)	8192

중요한 제약: d_model 은 반드시 n_heads 로 나누어떨어져야 합니다 (d_model % n_heads == 0). 이 조건을 위반하면 검증이 즉시 실패합니다.

2.4 `vocab_size`

토크나이저 어휘 크기입니다. 모델의 임베딩 테이블과 출력 헤드 크기를 결정합니다.

사용처	전형적인 값
영어 전용 (Llama 계열)	32000
GPT-2 토크나이저	50257
다국어 (Qwen 등)	152064
초대형 다국어	~256K

vocab_size 가 실제 토크나이저의 어휘 수보다 작으면 훈련 시 index out of bounds 에러가 발생합니다. 반대로 크면 빈 임베딩 슬롯이 생기지만 동작은 합니다. 안전하게는 토크나이저의 model_max_tokens 과 정확히 일치 시키는 것이 원칙입니다.

2.5 `max_seq_len`

이 모델이 한 번에 처리할 수 있는 최대 토큰 수 입니다. 컨텍스트 길이와 동의어로 쓰입니다.

RoPE 버퍼가 max_seq_len 에 비례해 사전 계산됩니다.
KV 캐시 크기도 이 값에 비례합니다.
메모리와 정확히 선형 관계입니다.

전형적인 값:

용도	max_seq_len
짧은 대화	2048
일반 LLM 기본값	4096
중간 길이 문서	8192, 16384
장문 처리	32768
초장문 (비현실적 아님)	65536, 131072

max_seq_len 이 크면 훈련 중 메모리가 기하급수적으로 늘 수 있습니다. 24 GB GPU 기준으로 1B 모델 + 32K seq 이면 batch_size=1 도 빠듯합니다.

2.6 `n_heads`

Attention 의 헤드 개수입니다. 헤드가 많을수록 토큰 간 관계를 더 세밀하게 분리해 학습할 수 있습니다. head_dim = d_model / n_heads 가 각 헤드의 차원이며, 이 값이 64–128 범위인 것이 일반적입니다.

너무 작으면 (< 32) 표현력 부족 → realism 경고
너무 크면 (> 256) attention 분해 효과 희석 → realism 경고

2.7 `n_kv_heads` (GQA 의 핵심)

Grouped-Query Attention 의 핵심 필드. query 헤드는 n_heads 개 유지하되, key/value 는 n_kv_heads 개만 공유합니다.

설정	의미
`n_kv_heads == n_heads`	MHA (Multi-Head Attention, 고전 Transformer / GPT-2)
`n_kv_heads < n_heads`	GQA (Llama 2/3 표준)
`n_kv_heads == 1`	MQA (Multi-Query Attention, 극단적 공유)

제약: n_heads % n_kv_heads == 0 이어야 합니다. 예: n_heads=16, n_kv_heads=4 는 4:1 GQA. n_heads=8, n_kv_heads=3 은 정수가 아니므로 실패.

실용적 가치: KV 캐시가 n_heads / n_kv_heads 배율만큼 줄어듭니다. 4:1 GQA 라면 추론 시 KV 메모리가 1/4 로 줄어 동시 처리량이 크게 증가합니다. Llama 2 70B 부터 이 기법이 업계 표준이 되었습니다.

2.8 `mlp_ratio`

FFN(피드포워드) 의 중간 차원 배율입니다. d_model * mlp_ratio 가 FFN 내부 차원이 됩니다. 대부분의 현대 LLM 에서 4 가 표준입니다.

SwiGLU 같은 게이팅 MLP 를 쓰면 실제로는 이 값을 2/3 곱한 크기를 쓰는 것이 관례지만 (Llama 가 이 방식), EulerStack 의 기본 구현은 단순히 4 를 그대로 씁니다.

2.9 `dtype`

모델 가중치의 저장 형식입니다.

값	특성
`bfloat16`	현재 표준. 범위는 float32 와 같고 정밀도만 낮음. GPU 훈련 안정적
`float16`	구형. 범위가 좁아 underflow 위험
`float32`	고정밀. 메모리 2 배 사용. 특수 용도

실무적 선택은 거의 항상 bfloat16 입니다. A100 이후 모든 주요 GPU 가 네이티브 지원합니다.

2.10 `target_params`

이 모델의 목표 파라미터 수를 명시합니다. 실제 추정치와 30% 이상 차이나면 realism 경고를 냅니다. 예: target_params: 1_000_000_000 는 "1B 규모" 라는 라벨.

이 값은 검증 로직에만 영향을 줍니다. 실제 모델 크기는 d_model, n_layers 등이 결정합니다. "약속과 실제의 차이" 를 감지하는 도구 로 생각하면 됩니다.

3. tokenizer_contract 블록

모델과 토크나이저 간 "계약" 을 명시합니다. 어떤 토크나이저를 사용하고, 특수 토큰을 어떻게 다룰지.

tokenizer_contract:
  type: hf
  pretrained: gpt2
  add_bos: true
  add_eos: true

3.1 `type`

현재 유일한 값은 hf (HuggingFace) 입니다. 미래에 다른 토크나이저 시스템이 추가될 수 있습니다.

3.2 `pretrained`

HuggingFace 모델 / 토크나이저의 ID 입니다. 실제 토크나이저 로딩 시 AutoTokenizer.from_pretrained(pretrained) 이 호출됩니다.

전형적인 값:

값	용도
`gpt2`	영어 중심, 50257 어휘
`meta-llama/Llama-2-7b-hf`	Llama 계열, 32000 어휘
`Qwen/Qwen2-7B`	다국어, 152064 어휘

3.3 `add_bos` / `add_eos`

문서 경계에 Begin-Of-Sequence / End-Of-Sequence 토큰을 자동으로 붙일지 여부. 훈련 루프가 각 문서의 시작과 끝을 모델에게 알려주는 신호입니다. 대부분의 경우 true.

4. embedding 블록

토큰 임베딩 테이블과 위치 인코딩 설정을 담당합니다.

embedding:
  type: learned
  positional: rope
  rope_theta: 500000.0
  rope_scaling:
    type: linear
    factor: 2.0
  tie_word_embeddings: true

4.1 `type`

learned 가 유일한 현재 옵션입니다. 각 토큰 ID 에 대응하는 임베딩 벡터를 학습으로 획득합니다.

4.2 `positional`

위치 인코딩 방식입니다.

값	설명
`rope`	Rotary Position Embedding. 현재 표준
`none`	위치 인코딩 없음 (Mamba 등 위치를 명시적으로 쓰지 않는 믹서)

RoPE 는 2021 년 RoFormer 논문이 제안했고 Llama 이후 거의 모든 모델이 채택했습니다. 상대 위치를 자연스럽게 표현하며, 훈련 길이 밖 외삽도 제한적으로 가능합니다.

4.3 `rope_theta`

RoPE 의 주기 파라미터. 값이 클수록 긴 문맥에서 위치 분해능이 좋아집니다.

값	적합한 max_seq_len
`10000.0`	~2K (GPT-2 / 초기 Llama)
`500000.0`	~32K (Llama 3)
`1000000.0`	32K 이상 (Qwen longctx)

4.4 `rope_scaling`

RoPE 의 위치 범위를 확장하는 기법. 훈련 때 본 길이보다 긴 시퀀스에서도 안정적으로 동작하게 합니다.

rope_scaling:
  type: linear      # 또는 dynamic, ntk
  factor: 4.0       # 4 배 확장

linear × 4 는 "훈련 때 8K 본 모델을 32K 로 확장" 의미입니다. 기본값은 위치 정보를 압축하는 방식이라 장문 정확도가 약간 떨어질 수 있습니다. Qwen 2 long-context 에서 검증된 패턴입니다.

4.5 `tie_word_embeddings`

입력 임베딩 테이블과 출력 LM head 의 가중치를 공유할지. true 면 vocab_size × d_model 만큼 파라미터 절약. 작은 모델에선 표준, 매우 큰 모델에선 가끔 분리합니다.

이 값은 head.tie_weights 와 일치해야 합니다.

5. layer_templates 블록

EulerStack 의 핵심 조립 단위 입니다. 하나의 레이어가 어떤 구조인지를 "청사진" 으로 정의합니다. 여러 청사진을 이름으로 정의해두고, layer_schedule 에서 조합해 사용합니다.

layer_templates:
  decoder:
    mixer:
      type: attention
      attention:
        qkv_bias: false
        attn_drop: 0.0
    ffn:
      type: gated_mlp
      activation: swiglu
    norm:
      type: rmsnorm
      position: pre
    residual:
      type: sequential
      scaling: 1.0
    state:
      kv_cache: true

각 템플릿은 다섯 개 하위 블록 으로 구성됩니다:

mixer — 토큰 간 정보 섞기 (attention 또는 대안)
ffn — 토큰별 처리 (피드포워드)
norm — 정규화 방식
residual — 잔차 연결 구조
state — 런타임 상태 (추론 캐시)

5.1 mixer

토큰 믹서. 시퀀스 내 토큰들이 서로를 참조하는 방식을 결정합니다. EulerStack 이 지원하는 네 가지 믹서 계열이 있습니다.

attention

표준 multi-head self-attention.

mixer:
  type: attention
  attention:
    qkv_bias: false     # QKV 프로젝션에 bias 붙일지 (Llama: false, GPT-2: true)
    attn_drop: 0.0      # attention dropout (대형 LLM 에선 0)
    window: null        # null: global attention, 숫자: sliding window (예: 4096)

window: null (기본) — 전역 attention, O(N²) 비용
window: 4096 — 슬라이딩 윈도우, 각 토큰이 앞 4096 토큰만 참조

mamba

Mamba2 SSM (State Space Model).

mixer:
  type: mamba
  mamba:
    variant: mamba2    # mamba 또는 mamba2
    d_state: 128       # 상태 차원
    d_conv: 4          # 내부 컨볼루션 커널 크기
    expand: 2          # 내부 확장 비율

Mamba 는 O(N) 시간 복잡도로 전체 시퀀스를 처리합니다. 긴 문맥에서 attention 보다 훨씬 빠릅니다. 대신 정확한 토큰 매칭(exact recall)은 약합니다.

retnet

Retention (RetNet).

mixer:
  type: retnet
  retnet:
    chunkwise: true      # 청크 기반 병렬 계산 활성화
    chunk_size: 128      # 청크 크기
    rope: true           # 내부 RoPE 사용 여부

RetNet 은 훈련 / 추론 모드가 수학적으로 동일한 결과를 내는 점이 특징입니다. 병렬 모드로 훈련하고 순환 모드로 O(1) 추론할 수 있습니다.

hyena

Hyena 장거리 컨볼루션.

mixer:
  type: hyena
  hyena:
    depth: 2              # Hyena 연산자 깊이
    filter_hidden: 64     # 필터 생성 MLP 의 내부 차원
    filter_decay: 0.0     # 필터 감쇠율

Hyena 는 O(N log N) 로 전역 컨볼루션을 수행합니다. 128K 이상의 초장문에서 경쟁력이 있습니다.

5.2 ffn

피드포워드 네트워크. 각 토큰별로 독립적으로 계산됩니다. 세 가지 선택지가 있습니다.

mlp

표준 2-layer MLP.

ffn:
  type: mlp
  activation: gelu       # relu, gelu, silu 등

GPT-2 등 고전 Transformer 스타일.

gated_mlp

게이팅이 있는 MLP (SwiGLU, GeGLU 등).

ffn:
  type: gated_mlp
  activation: swiglu     # 또는 geglu

Llama 이후 현대 LLM 의 표준. 일반 MLP 대비 파라미터가 1.5 배로 늘지만 품질이 확실히 좋아집니다.

moe

Mixture-of-Experts. 여러 FFN 중 일부만 활성화해 "계산량은 그대로 두고 용량만 늘림".

ffn:
  type: moe
  moe:
    experts: 8           # 전문가 수
    top_k: 2             # 각 토큰이 활성화할 전문가 수
    router: softmax      # 또는 sigmoid
    z_loss: 0.001        # router 안정화 보조 손실
    capacity_factor: 1.25 # 각 전문가의 여유 용량 배수

자세한 설명은 이후 튜토리얼 (07_arch_walkthrough.md 의 expert 섹션, 08_expert_mini_walkthrough.md) 을 참조하세요.

5.3 norm

정규화 방식과 배치 위치.

norm:
  type: rmsnorm          # 또는 layernorm
  position: pre          # 또는 post

조합	사용처
`layernorm` + `post`	고전 Transformer (GPT-2)
`rmsnorm` + `pre`	현대 LLM 표준 (Llama 이후)

pre-norm 이 post-norm 보다 훈련이 안정적 입니다. 2019 년 이후 대형 모델은 거의 전부 pre-norm.

RMSNorm 은 LayerNorm 의 간소화 버전 으로 평균 빼기 단계를 생략하고 RMS 만 계산. 파라미터가 절반이고 속도도 빠릅니다.

5.4 residual

잔차 연결 구조.

residual:
  type: sequential       # 또는 parallel
  scaling: 1.0           # 잔차에 곱할 계수

type	수식	사용처
`sequential`	`x = x + F(norm(x))`	표준. 대부분 모델
`parallel`	`x = x + Attn(norm(x)) + FFN(norm(x))` 동시 계산	PaLM 계열

scaling: 1.0 이 기본. 특수 목적 (예: layer scale) 로 작은 값을 줄 수 있습니다.

5.5 state

이 레이어가 런타임에 어떤 상태를 유지해야 하는지.

state:
  kv_cache: true         # attention 의 key/value 캐시
  ssm_state: true        # mamba 의 순환 상태

제약 (매우 중요):

mixer.type: attention 인 레이어는 kv_cache: true 를 쓸 수 있음
mixer.type: mamba 인 레이어는 ssm_state: true 를 씀
동시 사용 불가: mamba + kv_cache: true 는 검증 실패
retnet 은 자체 상태를 관리 (템플릿에 state 블록 생략 가능)
hyena 는 상태가 없음

검증기가 이 제약들을 자동으로 확인합니다.

6. layer_schedule 블록

정의된 템플릿을 어떤 순서로 몇 번 쌓을지 지정합니다. EulerStack 의 가장 표현력 높은 부분입니다.

6.1 기본 문법

layer_schedule:
  - template: decoder
    repeat: 24

decoder 템플릿을 24 번 반복합니다. 총 레이어 수 = 24. 단순한 Llama 스타일.

6.2 여러 템플릿 혼합 (Jamba 스타일)

layer_templates:
  mamba: { ... }
  attn: { ... }

layer_schedule:
  - { template: mamba, repeat: 3 }
  - { template: attn,  repeat: 1 }
  - { template: mamba, repeat: 3 }
  - { template: attn,  repeat: 1 }
  # 8 번 반복 = 총 32 레이어 (24 mamba + 8 attn)

깊이별로 다른 믹서를 배치합니다. 3:1 비율의 Jamba 하이브리드를 이렇게 표현합니다.

6.3 계층적 구조 (Progressive Stack 스타일)

layer_schedule:
  - { template: hyena_dense,  repeat: 8 }    # 초기: 값싼 전역
  - { template: mamba_dense,  repeat: 12 }   # 중기: 선형 순차
  - { template: retnet_dense, repeat: 8 }    # 후기: 청크 정제
  - { template: attn_moe,     repeat: 4 }    # 말단: 정확 recall + MoE

깊이별로 점진적으로 비싼 믹서를 배치. Vision 의 CNN → attention 계층 구조를 시퀀스 축에 적용한 실험.

6.4 피라미드 구조 (Dilated LongNet 스타일)

layer_schedule:
  - { template: mamba_prefix, repeat: 4 }
  - { template: sw_1024,      repeat: 4 }
  - { template: sw_4096,      repeat: 8 }
  - { template: sw_16384,     repeat: 8 }
  - { template: global_moe,   repeat: 8 }

receptive field 가 깊이에 따라 기하급수적으로 확장되는 구조. 32 레이어로 1K → 16K → 전역 의 temporal pyramid 를 만듭니다.

6.5 층 수 계산

총 레이어 수는 자동으로 계산됩니다:

n_layers = sum(entry.repeat for entry in layer_schedule)

validate --report 출력에 표시되며, 이 값이 실제 모델의 n_layers 가 됩니다.

7. head 블록

모델의 출력 헤드를 지정합니다.

head:
  type: causal_lm
  tie_weights: true

7.1 `type`

현재 지원되는 값은 causal_lm (autoregressive next-token 예측) 하나입니다. Classifier 나 encoder-decoder 등 다른 태스크는 아직 스키마에 포함되지 않았습니다.

7.2 `tie_weights`

LM head (출력 projection) 의 가중치를 입력 임베딩과 공유할지. 이 값은 embedding.tie_word_embeddings 와 반드시 일치해야 합니다.

8. training_hints 블록

훈련 시 참고할 힌트들. 아키텍처 자체는 아니지만 "이 모델을 훈련할 땐 이렇게 시작하는 걸 권장한다" 는 메타데이터입니다.

training_hints:
  init: normal_0.02
  dropout: 0.0
  checkpointing: true
  seed: 1234

8.1 `init`

가중치 초기화 방식. normal_0.02 는 표준편차 0.02 의 정규분포 초기화 (GPT-2 부터 현재까지 표준).

8.2 `dropout`

모델 전체에 적용할 dropout 기본값. 대형 LLM (1B+) 에서는 거의 항상 0.0 을 씁니다. 데이터가 충분해서 과적합이 드물기 때문.

8.3 `checkpointing`

Gradient checkpointing 사용 여부. true 면 메모리를 절약하는 대신 약 30% 느려집니다. GPU 메모리가 빠듯하면 켭니다.

8.4 `seed`

훈련 재현용 난수 시드.

9. compatibility 블록

compatibility:
  compile_target: huggingface

현재 유일한 컴파일 타겟은 huggingface 입니다. 미래에 vllm, tensorrt-llm 등이 추가될 가능성이 있습니다.

10. 교차 필드 규칙 (매우 중요)

개별 필드가 각각 유효하더라도 조합이 허용되지 않는 경우가 있습니다. 검증기가 자동으로 확인하는 대표적인 규칙들을 정리합니다.

10.1 차원 나눗셈 규칙

d_model % n_heads == 0       # 헤드가 d_model 을 균등 분할
n_heads % n_kv_heads == 0    # GQA 그룹 크기가 정수

위반 시: ValidationError

10.2 믹서 / 상태 호환성

믹서	허용되는 state
`attention`	`kv_cache: true` 가능
`mamba`	`ssm_state: true` 만 (kv_cache 불가)
`retnet`	자체 관리 (state 블록 생략)
`hyena`	상태 없음 (state 블록 생략)

위반 시: CompatibilityError

10.3 FFN / MoE 호환성

ffn.type 이 moe 가 아닐 때 moe: 하위 블록을 두면 불일치. 반대로 moe 인데 moe: 블록이 없어도 불일치.

10.4 MoE 내부 규칙

top_k <= experts
experts > 0
top_k > 0
z_loss >= 0
capacity_factor >= 1.0

10.5 head / embedding 일관성

head.tie_weights == embedding.tie_word_embeddings

두 값이 다르면 컴파일러가 가중치 공유 여부를 결정 못 해 검증 실패.

10.6 Realism 경고 (차단하지 않음)

검증은 통과하지만 권장되지 않는 조합:

head_dim < 32 또는 head_dim > 256
target_params 가 추정치와 30% 이상 차이
experts > 64 이면서 top_k 가 과소 (router 붕괴 가능성)
max_seq_len / d_model > 64 (불균형한 크기)
family_hint 와 실제 믹서 구성 불일치
RoPE scaling factor 가 8 초과

11. 검증 리포트 읽는 법

eulerstack validate --preset X.yml --report 출력 예시:

==================================================
EulerStack 검증 리포트
==================================================
Schema: OK
추정 파라미터: 1.14B (1,141,927,936)
총 레이어 수: 24
목표 파라미터: 1.00B

경고 (1):
  [realism.target_params] estimate 1.14B is 114% of target 1.00B

결과: 경고 (0 오류, 1 경고)
==================================================

읽는 순서:

Schema: OK — 스키마 검증 통과 여부. 실패 시 이후 내용 없음.
추정 파라미터 — 컴파일 후 실제 모델 크기. target_params 와 대비.
총 레이어 수 — layer_schedule 전개 결과.
오류 목록 — ValidationError 혹은 CompatibilityError 가 있으면 나열.
경고 목록 — realism 체크에서 발견된 권장 위반. 수정 선택사항.
결과 — 오류 개수 / 경고 개수 요약.

오류가 하나라도 있으면 컴파일 단계로 넘어가지 못합니다.

12. 설계 체크리스트

새 YAML 을 작성하기 전에 답변해야 할 5 개 질문:

이 모델이 해결할 태스크는? (요약 / QA / 코드 / 다국어 …)
한 번에 처리할 컨텍스트 길이는? → max_seq_len
훈련 데이터 규모는? → target_params 선택의 기준
추론 GPU 환경은? → d_model, n_kv_heads (GQA 비율) 결정
훈련 예산은? → 레이어 수, 믹서 선택의 기준

커밋하기 전에 확인해야 할 3 가지:

eulerstack validate --preset my_model.yml --report 가 통과
추정 파라미터가 target_params 와 30% 이내로 일치
eulerstack explain 결과가 의도와 일치

13. 자주 하는 실수

증상	원인	해결
`ValidationError: d_model must be divisible by n_heads`	차원 나눗셈 안 됨	`d_model` 을 `n_heads` 의 배수로
`CompatibilityError: mamba + kv_cache`	mamba 레이어에 kv_cache 명시	`state.ssm_state: true` 로 변경
`ValidationError: top_k > experts`	MoE 설정 오류	`top_k <= experts` 유지
추정 파라미터가 목표의 2 배	MoE 전문가를 모두 총 파라미터에 포함해서 계산됨	`target_params` 를 실제 총량으로 조정
훈련 중 `index out of bounds`	vocab_size < 실제 토크나이저 어휘	`TokenizedDataset(vocab_size=ir.model.vocab_size)` 래퍼 사용
RoPE 외삽 시 품질 하락	`rope_theta` 가 작음	`500000.0` 또는 `1000000.0` 로 상향

14. 참고용 전체 예시

가장 기본적인 Llama-style 1B 모델의 완전한 YAML 입니다. 모든 필드가 포함되어 있습니다.

schema_version: 1

model:
  name: "my-llama-1b"
  family_hint: "llama-like"
  d_model: 1536
  vocab_size: 32000
  max_seq_len: 4096
  n_heads: 16
  n_kv_heads: 4
  mlp_ratio: 4
  dtype: bfloat16
  target_params: 1_000_000_000

tokenizer_contract:
  type: hf
  pretrained: gpt2
  add_bos: true
  add_eos: true

embedding:
  type: learned
  positional: rope
  rope_theta: 500000.0
  tie_word_embeddings: true

layer_templates:
  decoder:
    mixer:
      type: attention
      attention:
        qkv_bias: false
        attn_drop: 0.0
    ffn:
      type: gated_mlp
      activation: swiglu
    norm:
      type: rmsnorm
      position: pre
    residual:
      type: sequential
      scaling: 1.0
    state:
      kv_cache: true

layer_schedule:
  - { template: decoder, repeat: 24 }

head:
  type: causal_lm
  tie_weights: true

training_hints:
  init: normal_0.02
  dropout: 0.0
  checkpointing: true
  seed: 1234

compatibility:
  compile_target: huggingface

이 파일을 복사하고 세 필드만 바꾸어도 완전히 다른 모델이 됩니다. 예:

d_model: 1536 → d_model: 2048 → 2B 스케일
mixer.type: attention → mixer.type: mamba → Pure Mamba 모델
ffn.type: gated_mlp → ffn.type: moe + moe: { experts: 8, top_k: 2 } → MoE

YAML 을 "조립식 설계도" 로 쓰는 감각은, 위 파일을 10 번 복제하고 매번 다른 필드를 바꿔보는 과정에서 빠르게 익숙해집니다.

15. v1 Phase B 확장 요약 (신규 primitive)

v1 은 Phase B 에서 14 개 primitive 가 추가됐습니다. 각 primitive 의 YAML 문법과 사용 사례는 09_new_primitives_walkthrough.md 에서 step-by-step 으로 다룹니다. 이 §15 는 위치와 간단한 용도 만 인덱스로 제시합니다.

15.1 `layer_templates[*]` 수준

필드	설명	§번호 (이 문서 내)
`mixer.attention.latent_dim`	MLA — KV 캐시를 latent 로 압축 (DeepSeek-V3)	§5.1 attention 확장
`mixer.type: branched` + `branched: {...}`	입력별 하위 mixer 선택 (Jamba × per-token)	§5.1 mixer.type 확장
`mixer.type: ttt_layer` + `ttt: {...}`	Test-Time Training (Sun 2024)	§5.1 mixer.type 확장
`memory: {type, update_at_inference, ...}`	Titans 파라미터형 메모리	새 하위 블록
`shape_change: {d_out, projection}`	Hourglass 식 shape-change	새 하위 블록

15.2 `layer_schedule[*]` 수준

필드	설명
`override: {...}`	스케줄 entry 단위의 부분 override (residual.scaling, attention.window 등)
`depth_gating: {enabled, capacity, router}`	Mixture-of-Depths — per-token layer skip
`parallel: [...]` + `merge: {...}`	Monoidal 병렬 스트림 (Mamba ∥ Attention)
`integrator: {type, steps, body, output}`	Universal Transformer / Diffusion-LM / Coconut 통합

15.3 최상위 수준

필드	설명
`let: {...}`	수식 변수 — 본문에서 `${let.x * let.y}` 로 참조 (Level-1 산술)
`execution_modes: [...]`	R1 식 2-phase (think/answer) 선언
`transition: {type, token}`	phase 전환 규칙 (`special_token` / `budget_exhausted`)

15.4 Reserved namespace

experimental.* / future.* / vendor.<name>.* prefix 로 시작하는 키는 경고만 발생 하고 에러가 아닙니다. 플러그인 / 연구 진행 중 확장을 위한 예약 공간입니다.

다음 단계

튜토리얼 4: 컴파일과 설명 — 이 YAML 을 실제 HF 모델로 바꾸는 과정
튜토리얼 7: arch 워크스루 — arch_ 프리셋이 이 필드들을 어떻게 조합했는지 케이스 스터디 (beginner 2 · intermediate 3 · advanced 5 · expert 12)
튜토리얼 9: v1 신규 primitive 워크스루 — §15 에서 인덱스한 각 primitive 의 상세 step-by-step
믹서 개요 — attention / mamba / retnet / hyena / branched / ttt_layer 의 내부 원리
튜토리얼 1: 검증 — 검증 시스템의 3 계층 구조 복습

← 이전 2. 프리셋 사용하기 4. Compile & Explain 다음 →