시작 가이드

EulerForge로 LLM을 파인튜닝하는 빠른 시작 안내서입니다. 각 인젝션 전략의 상세한 설명은 전략별 튜토리얼을 참조하세요.

1. 설치 및 환경

사전 요구 사항

• Python >= 3.9
• PyTorch >= 2.1
• CUDA 지원 GPU (권장, CPU에서도 테스트 가능)

설치

# 저장소 클론
git clone <repo_url>
cd eulerforge

# editable 모드로 설치
pip install -e .

# 개발용 (테스트 포함)
pip install -e ".[dev]" pytest

설치 확인

python -c "import eulerforge; print('OK')"
eulerforge train --help

2. 데이터 준비

먼저 데이터 전처리 가이드를 실행하세요. data/ 원본 데이터를 EulerForge 표준 raw JSONL로 변환합니다.

제공 데이터 및 용도

raw 데이터 사용법

data.format=raw를 지정하면 훈련 시 자동 토큰화됩니다:

eulerforge train --preset configs/presets/<프리셋>.yml \
    --set data.format=raw \
    --set data.task=sft \
    --set data.path=data/sft_10k_raw.jsonl \
    --set data.max_length=512

상세: 데이터 전처리 가이드

3. 핵심 개념: Where / What / When

EulerForge는 세 가지 관점으로 파인튜닝을 구성합니다:

각 전략 튜토리얼은 이 세 관점에서 단계별로 설명합니다.

4. 백본 어댑터

backbone 설정 키에 따라 올바른 어댑터가 자동 선택됩니다:

5. 인젝션 전략 선택

전략 비교표

전략별 튜토리얼

• Plain LoRA 튜토리얼 — 가장 기본적인 LoRA 파인튜닝
• LoRA MoE 튜토리얼 — 라우터 + 다중 LoRA 전문가
• FFN MoE Expert LoRA 튜토리얼 — Dense 모델을 MoE로 변환
• Native MoE Expert LoRA 튜토리얼 — Mixtral 전용 파인튜닝

훈련 방식 튜토리얼

• DPO 훈련 가이드 — 선호 기반 정렬 훈련 (reference model)
• ORPO 훈련 가이드 — 선호 기반 정렬 (reference model 불필요)
• RM 훈련 가이드 — 리워드 모델 훈련 (Bradley-Terry)
• PPO/RLHF 가이드 — PPO 기반 RLHF 파이프라인

모델별 튜토리얼

• LLaMA 파인튜닝 가이드 — Llama-3.2-1B SFT + TinyLlama DPO

훈련 방식 선택표

어떤 전략을 선택해야 하나?

모델이 이미 MoE 구조인가? (Mixtral 등)
  ├── 예 → native_moe_expert_lora
  └── 아니오 (Dense 모델)
        ├── 단순 파인튜닝? → dense_lora
        ├── 멀티태스크/적응형? → mixture_lora
        └── MoE 구조로 변환? → moe_expert_lora

6. 페이즈 스케줄 개요

페이즈 스케줄은 언제 어떤 파라미터 그룹을 훈련할지를 제어합니다. training.phases에 선언적으로 정의합니다.

파라미터 그룹

전략별 페이즈 패턴

상세한 페이즈 설정과 타임라인은 각 전략 튜토리얼의 "When" 섹션을 참조하세요.

7. CLI 빠른 시작

기본 훈련 (raw 데이터)

eulerforge train --preset configs/presets/<프리셋>.yml \
    --set data.format=raw \
    --set data.task=sft \
    --set data.path=data/sft_10k_raw.jsonl \
    --set data.max_length=512

사용 가능한 프리셋

설정 오버라이드

도트 경로 표기법으로 모든 설정 값을 오버라이드합니다:

eulerforge train --preset configs/presets/qwen3.5_0.8b_dense_lora_sft.yml \
    --set data.format=raw \
    --set data.task=sft \
    --set data.path=data/sft_10k_raw.jsonl \
    --set data.max_length=512 \
    --set training.lr=2e-5 \
    --set injection.lora_r=32

유용한 CLI 옵션

CLI 상세 레퍼런스는 CLI 문서를 참조하세요.

8. 벤치마크 실행

eulerforge bench --target-dir /path/to/checkpoint \
    --ref-model Qwen/Qwen3.5-0.8B-Base \
    --test-data /path/to/test.jsonl \
    --output-file results.jsonl

9. 일반적인 문제 해결

전략별 상세 트러블슈팅은 각 튜토리얼의 "디버깅 및 트러블슈팅" 섹션을 참조하세요.

10. 스크래치 사전훈련 (pretrain)

기존 HF 모델이 아닌, EulerStack 등으로 새로 조립한 모델을 처음부터 훈련하려면 eulerforge pretrain 명령어를 사용하세요.

eulerforge pretrain --preset configs/presets/pretrain/eulerstack_hybrid_moe.yml

pretrain은 train과 완전히 분리된 파이프라인으로, 전체 파라미터 causal LM 훈련을 수행합니다. LoRA 인젝션이나 페이즈 스케줄은 사용하지 않습니다.

상세: 17_pretrain.md

11. 훈련 파이프라인 — SFT부터 PPO까지

EulerForge는 5가지 훈련 타입을 지원합니다. SFT를 반드시 먼저 진행하세요:

SFT → DPO (또는 ORPO) → 배포       # 가장 일반적 (2단계)
SFT → RM → PPO → 배포              # 풀 RLHF (3단계)
SFT → ORPO → RM → PPO → 배포       # ORPO 기반 풀 RLHF

주의: DPO/ORPO/RM/PPO를 base 모델에 직접 적용하면 성능이 하락합니다. 반드시 SFT로 instruction-following 능력을 먼저 부여한 후 선호 학습을 진행하세요.

각 단계의 체크포인트가 다음 단계의 모델 입력이 됩니다.

상세: 18_training_pipeline.md