EulerForge CLI 레퍼런스

# 영어로 출력
eulerforge --lang en train --preset configs/presets/qwen3.5_0.8b_dense_lora_sft.yml

# ��본어로 출력
eulerforge --lang ja bench --preset configs/bench/sft_target_only.yml

export EULERFORGE_LANG=en
eulerforge train --preset ...    # 영어로 출력

eulerforge train [OPTIONS]

# SFT → DPO 파이프라인 예시
eulerforge train --preset configs/presets/qwen3.5_0.8b_dense_lora_sft.yml \
    --output-dir outputs/sft

# SFT 체크포인트를 model_name으로 지정 → base 모델 자동 탐지
eulerforge train --preset configs/presets/qwen3.5_0.8b_dense_lora_dpo.yml \
    --set model_name=outputs/sft/final \
    --output-dir outputs/dpo

# 필드 확인 (입력 파일 구조 탐색)
eulerforge convert --task sft --input data/sft_10k.jsonl --print-sample-flat

# Map 모드 (flat 필드)
eulerforge convert --task sft --input data/custom.jsonl --output data/out.jsonl \
    --map prompt=instruction --map response=output

# Map 모드 (중첩 필드 — dot-path 자동 flatten)
eulerforge convert --task prompted_preference --input data/dpo_10k.jsonl --output data/dpo_10k_raw.jsonl \
    --map prompt=instruction.value --map chosen=chosen.value --map rejected=rejected.value

# Recipe 모드 (messages 배열)
eulerforge convert --task sft --input data/sft_10k.jsonl --output data/sft_10k_raw.jsonl \
    --recipe sft_messages --messages-expr json_record.messages

# Validate 모드 (변환 없이 스키마 검증)
eulerforge convert --task sft --input data/sft_10k_raw.jsonl --validate

eulerforge preprocess --task TASK --input RAW.jsonl --output PROCESSED.jsonl --model-name MODEL

eulerforge bench [OPTIONS]

Phase 1: target 로드 → 전체 샘플 추론 → 언로드
Phase 2: baseline 로드 → 전체 샘플 추론 → 언로드 (enabled일 때)
Phase 3: judge 로드 → 전체 샘플 평가 → 언로드 (enabled일 때)
Phase 4: 결과 통합 → 기존과 동일한 출력 포맷

bench:
  task: sft                                  # sft | preference
  data_path: data/sft_1k_bench_raw.jsonl
  sample:
    k: 10
    seed: 42
    shuffle: true
  generation:
    max_new_tokens: 256
    temperature: 0.7
    top_p: 0.95
  models:
    target:
      # 방법 A: API 모델 (Ollama/OpenAI/Gemini)
      provider: ollama                       # ollama | openai | gemini
      model: "qwen3:0.6b"
      base_url: "http://localhost:11434/v1"

      # 방법 B: 학습 출력 디렉토리 (자동 체크포인트 해석)
      # output_dir: "outputs/run_20260301_120000"
      # checkpoint: "final"                  # final | latest | best (기본: final)
      # device: "auto"                       # 기본: auto
      # dtype: "auto"                        # 기본: auto

      # 방법 C: HF 모델 디렉토리 직접 지정
      # provider: local_hf                   # 생략 가능 (자동 설정)
      # model_dir: "outputs/run_20260301_120000/final"
    baseline:
      enabled: false
      # API 방식 (Ollama/OpenAI/Gemini):
      provider: ollama
      model: "qwen3:4b"
      # 또는 HF 모델 직접 로드 (provider 불필요):
      # model_dir: "Qwen/Qwen2.5-0.5B"     # HF Hub 이름 또는 로컬 경로 모두 가능
      # device: "cuda:0"
      # dtype: "float16"
      # 참고: 파이프라인 스크립트에서 --set bench.models.baseline.enabled=false로
      # 덮어쓰면 preset의 baseline 설정이 무시됩니다.
    judge:
      enabled: false
      provider: ollama
      model: "gemma3:27b"
      mode: pointwise                        # pointwise | pairwise
      mitigate_position_bias: true           # pairwise A/B 스왑 2회
  output:
    out_dir: outputs/bench
    save_jsonl: true
    print_examples: true
    print_max_chars: 1500

# API 모델 사용
eulerforge bench --preset configs/bench/sft_target_only.yml

# 학습 출력 디렉토리에서 final 체크포인트 로드
eulerforge bench --preset configs/bench/sft_local.yml \
  --target-output-dir outputs/run_20260301_120000

# latest 체크포인트 사용
eulerforge bench --preset configs/bench/sft_local.yml \
  --target-output-dir outputs/run_20260301_120000 --checkpoint latest

# 모델 디렉토리 직접 지정
eulerforge bench --preset configs/bench/sft_local.yml \
  --target-model-dir outputs/run_20260301_120000/final

# GPU 지정 (judge가 GPU 0을 사용할 때, target을 GPU 1에 로드)
eulerforge bench --preset configs/bench/sft_local.yml \
  --target-output-dir outputs/run_20260301_120000 --target-device cuda:1

# 설정 오버라이드
eulerforge bench --preset configs/bench/sft_target_only.yml --set bench.sample.k=20

# 검증만
eulerforge bench --preset configs/bench/sft_target_only.yml --validate-only

# 샘플 확인 (모델 호출 없음)
eulerforge bench --preset configs/bench/sft_target_only.yml --dry-run

training:
  type: orpo
  orpo_lambda: 1.0  # ORPO 항 가중치 (필수, 양수)

training:
  type: rm
  # RewardHead가 자동 생성됨 (hidden_size → 1)

training:
  type: ppo
  ppo:
    clip_range: 0.2     # PPO 클리핑 범위
    kl_coef: 0.1        # KL 페널티 계수
    epochs: 4           # 배치당 PPO 업데이트 에폭 수
    max_gen_len: 64     # 최대 생성 길이
    temperature: 1.0    # 샘플링 온도
  reward_model:
    model_name: "path/to/model"  # 리워드 모델 경로
    checkpoint_path: ""          # 체크포인트 (선택)

model:
  load_precision:
    mode: int4               # fp32 | fp16 | bf16 | int8 | int4
    compute_dtype: bf16      # int8/int4 연산 dtype (fp16 | bf16)
    quant_type: nf4           # int4 전용: nf4 | fp4
    double_quant: true        # int4 전용
    dequantize_on_train: true # base_ffn trainable 시 자동 dequantize

# 방법 1: 이미 토큰화된 processed JSONL
data:
  format: processed
  path: data/sft_processed.jsonl

# 방법 2: raw JSONL (훈련 시 자동 전처리 → 캐시)
data:
  format: raw
  task: prompted_preference
  path: data/dpo_10k_raw.jsonl
  max_length: 512
  # num_proc: 기본값 = CPU 코어 50% (자동)
  # cache_dir: 기본값 = outputs/.cache (run 간 공유 캐시)
  #
  # 캐시 파일명 규칙: {입력파일명}_{task}_{모델명}_len{max_length}.jsonl
  # 예: dpo_10k_raw_prompted_preference_qwen3.5-0.8b-base_len512.jsonl
  # 동일 파라미터면 자동 재사용 (재전처리 없음)

# 방법 3 (레거시): processed_data_path 직접 지정
processed_data_path: data/sft_processed.jsonl

Data: processed dataset row 0 missing 'input_ids'
Fix: Run `eulerforge preprocess ...` or set data.format=raw with schema mapping
See: docs/tutorials/ko/00_data_preprocessing.md

Data Config: data.task='sft' is incompatible with training.type='dpo'. Task 'sft' produces data for sft, ppo training
Fix: Set --set training.type=sft or change data.task to match
See: docs/tutorials/ko/00_data_preprocessing.md

--set training.lr=2e-5
--set injection.lora_r=32
--set training.phases.1.step=100   # list 내 특정 인덱스 필드 업데이트 (sparse)
--set training.phases.0.trainable=[lora,attn_lora]  # list 요소의 list 값

CLI --set 오버라이드 > YAML 프리셋 값

outputs/run_YYYYMMDD_HHMMSS/
├── resolved_config.json    # 전체 해석된 설정 (재현성)
├── checkpoint-latest/      # 최신 체크포인트
│   ├── model files...
│   ├── tokenizer files...
│   └── training_state.pt   # 옵티마이저, 스케줄러, 스텝, best_val_loss
├── checkpoint-best/        # 최적 검증 손실 체크포인트
│   └── ...
└── final/                  # 훈련 완료 후 최종 모델
    └── ...

MoE Config: moe.router_z_loss_coef is required for MoE strategies.
Fix: Set moe.router_z_loss_coef: 0.001 (ST-MoE recommended)
See: docs/tutorials/ko/09_moe_stability_and_validation.md

eulerforge train --preset PRESET.yml --preflight

[Phase2] Step 400/600 (micro 4500/6000) | Loss: 0.1234 | LR: 1.00e-05 | ... | Handoff[expert_lora=0.75, attn_lora=0.80, ffn_lr_mult=2.50]

pip install eulerforge[tb]

logging:
  metrics_level: advanced      # "minimal" | "advanced"
  tensorboard:
    enabled: true              # TensorBoard 기록 (기본: false)
    log_dir: "outputs/tb"      # 로그 디렉토리
  log_interval: 50             # N 스텝마다 TensorBoard 기록
  max_experts_log: 16          # advanced에서 상위 N 전문가 상세 로그

eulerforge train --preset PRESET.yml --metrics-level advanced

# spec 검증만 (dry-run)
eulerforge grid configs/grid/sft_random_search.yml --dry-run

# 실제 실행
eulerforge grid configs/grid/sft_random_search.yml

# project root 명시
eulerforge grid configs/grid/sft_random_search.yml --project-root /path/to/project

pip install eulerforge[hpo]

<output_root>/
├── trial_0000/
│   ├── metrics.jsonl       # 스텝별 지표 (train/total_loss 등)
│   └── checkpoint-latest/
├── trial_0001/
│   └── ...
├── summary.json            # 전체 결과 (best_trial + all_trials)
└── summary.csv

from eulerforge import load_model

@dataclass
class LoadedModel:
    model: nn.Module           # eval 모드
    tokenizer: PreTrainedTokenizer
    metadata: ModelMetadata

@dataclass
class ModelMetadata:
    strategy: str              # "dense_lora" | "moe_expert_lora" | "mixture_lora" | "none"
    backbone: str              # "qwen3" | "llama" | "gemma3" | ""
    path_type: str             # "run_dir" | "checkpoint_dir"
    checkpoint_dir: str        # 실제 체크포인트 디렉토리 경로
    lora_config: dict | None   # {"lora_r": int, "lora_alpha": float}
    structure_preserved: bool  # MoE/MixtureLoRA 구조 보존 여부
    load_precision: str | None # "fp32" | "fp16" | "bf16" | "int8" | "int4" | None

from eulerforge import load_model

# 1. 학습 출력 디렉토리에서 로드 (final 체크포인트)
result = load_model("outputs/run_20260311_163425")
print(result.metadata.strategy)     # "moe_expert_lora"
print(result.metadata.backbone)     # "qwen3"

# 2. best 체크포인트 로드
result = load_model("outputs/run_20260311_163425", checkpoint="best")

# 3. 체크포인트 디렉토리 직접 지정
result = load_model("outputs/run_20260311_163425/final", device="cuda:0")

# 4. 양자화 로딩 (int4/int8)
result = load_model("outputs/run_20260311_163425", load_precision="int4")
result = load_model("outputs/run_20260311_163425", load_precision="bf16")

# 5. 추론
messages = [{"role": "user", "content": "안녕하세요"}]
text = result.tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
inputs = result.tokenizer(text, return_tensors="pt").to(result.model.device)
with torch.no_grad():
    out = result.model.generate(**inputs, max_new_tokens=128)
print(result.tokenizer.decode(out[0], skip_special_tokens=True))

# 6. 메타데이터 활용
if result.metadata.structure_preserved:
    print("MoE 구조가 보존된 체크포인트입니다")
if result.metadata.lora_config:
    print(f"LoRA r={result.metadata.lora_config['lora_r']}")

# dense_lora → merged HF 모델
eulerforge export-hf --checkpoint outputs/run_20260311_163425 --output ./exported

# MoE → custom_moe HF 모델 (trust_remote_code=True로 로드)
eulerforge export-hf --checkpoint outputs/run_moe --output ./exported_moe

# dry-run (계획만 출력)
eulerforge export-hf --checkpoint outputs/run --output ./out --dry-run

# validate-only (검증만)
eulerforge export-hf --checkpoint outputs/run --output ./out --validate-only

eulerforge pretrain [OPTIONS]

# 디바이스
device: "cuda:0"             # cuda:0, cuda:1, cpu

# 모델 (EulerStack export 디렉토리)
model_dir: "outputs/full_hybrid_moe"
trust_remote_code: true

# 토크나이저 (model_dir에 없으면 별도 지정)
tokenizer: "gpt2"

# 데이터
data:
  path: "data/dolma_10k.jsonl"
  text_column: "text"        # JSONL의 텍스트 키
  max_length: 1024
  packing: true              # packed chunking (텍스트 연결 → 고정 길이 분할)

# 훈련
training:
  max_steps: 500
  batch_size: 2
  grad_accum_steps: 4
  lr: 3.0e-4
  weight_decay: 0.1
  warmup_steps: 50
  max_grad_norm: 1.0
  log_steps: 10
  save_steps: 250
  dtype: "float32"           # Hybrid 모델(Hyena/RetNet)은 float32 필수
  amp: false                 # FFT 연산 bf16 미지원 → 비활성화
  seed: 42

# 기본 실행
eulerforge pretrain --preset configs/presets/pretrain/eulerstack_hybrid_moe.yml

# 설정 오버라이드
eulerforge pretrain --preset ... --set training.max_steps=1000 --set training.lr=1e-4

# 검증만
eulerforge pretrain --preset ... --validate-only

# 출력 디렉토리 지정
eulerforge pretrain --preset ... --output-dir outputs/my_pretrain

outputs/pretrain_YYYYMMDD_HHMMSS/
├── pretrain_config.json         # 설정 스냅샷
├── metrics.jsonl                # 스텝별 loss, lr 기록
├── checkpoint-250/              # 중간 체크포인트
│   ├── config.json
│   ├── model.safetensors
│   └── tokenizer files...
└── final/                       # 최종 모델
    ├── config.json
    ├── model.safetensors
    └── tokenizer files...