<p align="center">
<a href="https://ludwig.ai">
<img src="https://github.com/ludwig-ai/ludwig-docs/raw/main/docs/images/ludwig_hero_smaller.jpg" height="150">
</a>
</p>
<div align="center">
LLM, 멀티모달 모델 및 테이블형 AI를 위한 선언적 딥러닝 프레임워크.
PyPI version
Discord
DockerHub
Downloads
License
X
문서 (Docs) · 시작하기 (Getting Started) · 예제 (Examples) · Discord
</div>
Ludwig란 무엇인가?
Ludwig은 **선언적 딥러닝 프레임워크 (declarative deep learning framework)**로, YAML 설정 파일과 보일러플레이트(boilerplate)가 없는 Python 코드만으로 LLM 파인튜닝부터 테이블형 분류까지 AI 모델을 학습하고, 미세 조정하며, 배포할 수 있게 해줍니다.
model_type: llm
base_model: meta-llama/Llama-3.1-8B
...
ludwig train --config model.yaml --dataset my_data.csv
기술 스택 (Tech stack): Python 3.12 · PyTorch 2.7+ · Pydantic 2 · Transformers 5 · Ray 2.54
Ludwig은 Linux Foundation AI & Data에서 호스팅합니다.
Ludwig 0.16의 새로운 기능
| 기능 (Feature) | 설명 (Description) |
|---|
| PatchTST & N-BEATS 인코더 | MASE/sMAPE 지표를 사용하는 최첨단 시계열 예측 인코더 |
| ... | |
설치 (Installation)
pip install ludwig
pip install ludwig[full]
pip install ludwig[llm]
Python 3.12 이상이 필요합니다. 전체 의존성 매트릭스는 contributing를 참조하십시오.
빠른 시작 (Quick Start)
LLM 미세 조정하기 (지침 튜닝, instruction tuning)
Open In Colab
Ludwig은 전체 LLM 미세 조정 스펙트럼을 지원합니다:
| 기술 (Technique) | 설정 키 (Config key) |
|---|
| 지도 학습 기반 미세 조정 (Supervised fine-tuning, SFT) | trainer.type: finetune |
| ... | |
model_type: llm
base_model: meta-llama/Llama-3.1-8B
...
export HUGGING_FACE_HUB_TOKEN="<your_token>"
ludwig train --config model.yaml --dataset "ludwig://alpaca"
멀티모달 분류기 훈련하기 (Train a multimodal classifier)
input_features:
- name: review_text
type: text
...
ludwig train --config model.yaml --dataset reviews.csv
자연 언어에서 설정 생성하기 (Generate a config from natural language)
ludwig generate_config "age, income, education level이 포함된 CSV 파일이 있고, 대출 부도 예측을 하고 싶습니다"
예측 수행하기 (Make predictions)
ludwig predict --model_path results/experiment_run/model --dataset new_data.csv
REST API 배포하기
ludwig serve --model_path results/experiment_run/model
기능 (Capabilities)
<details>
<summary><strong id="llm-fine-tuning">LLM 미세 조정 (Fine-Tuning)</strong></summary>
- 지시어/응답 쌍을 이용한 지도 학습 미세 조정 (Supervised fine-tuning, SFT)
- 정렬 훈련 (Alignment training): DPO, KTO, ORPO, GRPO (보상 모델 없는 강화학습, reward-model-free RLHF)
- PEFT 어댑터: LoRA, DoRA, VeRA, LoRA+, TinyLoRA, OFT, HRA, WaveFT, LN-Tuning, VBLoRA, C3A
- LoRA 초기화기 (initializers): 개선된 수렴을 위한 PiSSA, EVA, CorDA, LoftQ
- 다중 어댑터 PEFT: 하나의 기본 모델에 여러 개의 이름 지정된 어댑터를 적용하고 런타임 시 전환 가능; TIES, DARE, SVD, 크기 가지치기(magnitude pruning)와 병합
- 양자화 (Quantization): 4비트/8비트 QLoRA (bitsandbytes), QAT를 사용한 torchao int4/int8/float8
- VLM 미세 조정:
is_multimodal: true을 통해 LLaVA, Qwen2-VL, InternVL 지원
- 가변 길이 입력에 대한 효율적인 훈련을 위한 시퀀스 패킹 (Sequence packing)
- 메모리 효율적인 훈련을 위한 페이지드 및 8비트 옵티마이저
</details>
<details>
<summary><strong id="multimodal-tabular">멀티모달 및 테이블형 모델</strong></summary>
- 입력 모달리티 (Input modalities): 텍스트, 숫자, 범주, 이진(binary), 집합(sets), 가방(bags), 시퀀스, 이미지, 오디오, 시계열(timeseries), 벡터, 날짜
- 텍스트 인코더 (Text encoders): 모든 HuggingFace Transformer (BERT, RoBERTa, ModernBERT, Qwen3, Llama-3.1 등), 그리고 Mamba-2, Jamba
- 이미지 인코더 (Image encoders): DINOv2, ConvNeXt, EfficientNet, ViT, CAFormer, ConvFormer, PoolFormer, TIMM (1000개 이상의 모델)
- 시계열 인코더 (Timeseries encoders): PatchTST, N-BEATS, CNN, RNN, Transformer; MASE 및 sMAPE 지표;
model.forecast() API
- 결합기 (Combiners): concat, transformer, tab_transformer, FT-Transformer, TabNet, TabPFN v2, HyperNetwork, ProjectAggregate, GatedFusion, Perceiver
- 다중 작업 학습 (Multi-task learning): 단일 모델 내 여러 출력 특징; Nash-MTL, Pareto-MTL, FAMO, GradNorm, 불확실성 손실 균형 맞추기(uncertainty loss balancing)
- 이미지 분할 (Image segmentation): UNet, SegFormer, FPN 디코더
</details>
<details>
<summary><strong>훈련 인프라 (Training Infrastructure)</strong></summary>
- 분산 훈련 (Distributed training): DDP, FSDP, DeepSpeed를 사용한 HuggingFace Accelerate (코드 변경 없음)
- Ray 백엔드: Ray 클러스터 전반에 걸친 훈련, Ray Data를 통한 메모리 초과 데이터셋 처리
- 자동 배치 크기 선택 및 학습률 범위 테스트
- 혼합 정밀도 (Mixed precision) (fp16/bf16), 그래디언트 체크포인팅(gradient checkpointing), 그래디언트 누적(gradient accumulation)
- 옵티마이저 (Optimizers): AdamW, Adafactor, SGD, Muon, ScheduleFreeAdamW, Lion, paged/8-bit 변형
- 학습률 스케줄러 (Learning rate schedulers): 코사인(cosine), 선형(linear), 다항식(polynomial), reduce-on-plateau, OneCycleLR
- 모델 수프 (Model Soup): 추론 비용 0에서 더 나은 일반화를 위한 균일 및 탐욕적 체크포인트 평균화
- **모달리티 드롭아웃 (Modality dropout)**을 통한 강력한 멀티모달 모델 구현
</details>
<details>
<summary><strong>하이퍼파라미터 최적화 (Hyperparameter Optimization)</strong></summary>
Executors: Ray Tune (ASHA, PBT, Bayesian) 및 네이티브 Optuna (auto/GP/TPE/CMA-ES)
- Optuna 지속성(persistence): 재개 가능한 하이퍼파라미터 최적화(HPO) 실행을 위한 SQLite 또는 PostgreSQL
- 가지치기(Pruning): Optuna의 MedianPruner 및 HyperbandPruner 사용
- 탐색 공간(Search spaces): uniform, log-uniform, choice, randint, quantized
- 전체 Ludwig 설정은 검색 가능합니다 — 모든 중첩된 매개변수가 하이퍼파라미터가 될 수 있습니다.
</details>
<details>
<summary><strong>프로덕션 및 배포(Production & Deployment)</strong></summary>
- REST API: Prometheus 메트릭 및 구조화된 로깅을 갖춘 FastAPI 서버 (
ludwig serve)
- vLLM 서빙: PagedAttention 및 연속 배치 처리(continuous batching)를 지원하는 OpenAI 호환 API
- Ray Serve: 자동 확장 및 트래픽 분할 기능을 갖춘 분산 배포
- KServe: Open Inference Protocol v2를 사용한 Kubernetes 네이티브 배포
- 모델 내보내기(Model export): SafeTensors (기본값),
torch.export .pt2 번들, ONNX
- HuggingFace Hub:
ludwig upload hf_hub — 모델 및 자동 생성된 모델 카드 푸시
- Docker: ludwigai/ludwig에서 사전 구축된 컨테이너
</details>
<details>
<summary><strong>도구 및 통합(Tooling & Integrations)</strong></summary>
- 실험 추적(Experiment tracking): TensorBoard, Weights & Biases, Comet ML, MLflow, Aim Stack
- 모델 검사(Model inspection):
ModelInspector — 가중치 열거(weight enumeration), 아키텍처 요약(architecture summary), 특징 중요도 프록시(feature importance proxy)
- 시각화(Visualizations): 학습 곡선(learning curves), 혼동 행렬(confusion matrices), 보정 플롯(calibration plots), ROC 곡선(ROC curves), hyperopt 분석
- AutoML:
ludwig.automl.auto_train() — 데이터셋과 시간 예산만 제공하면 됩니다; YAML 기반 검색 공간이 인코더/결합기/디코더 조합을 샘플링하고 훈련 전에 검증합니다.
- 데이터셋 품질 검사(Dataset quality checks):
from ludwig.utils.dataset_quality import check_dataset_quality — 훈련 전에 DataFrame을 검증합니다 (누락된 값, 클래스 불균형, 거의 중복되는 열, ID 누출 등)
- OpenML 통합: 모든 OpenML 태스크를 직접 로드할 수 있습니다 —
OpenMLLoader는 태스크 ID로 가져와 Parquet으로 로컬 캐시합니다.
- LLM 설정 생성(LLM config generation): `ludwig generate_config
시간 계열 및 비전 (Timeseries & Vision)
자연어 처리 및 오디오 (NLP & Audio)
Ludwig를 사용해야 하는 이유? (Why Ludwig?)
- 보일러플레이트 코드 제로(Zero boilerplate) — 학습 루프, 데이터 파이프라인, 평가 코드가 필요 없습니다. YAML 설정 파일 자체가 전체 프로그램입니다.
- 최고 수준의 LLM 지원 — LoRA부터 GRPO 정렬, torchao QAT, VLM 미세 조정까지 전 범위가 설정 파일 내에서 가능합니다.
- 즉시 사용 가능한 멀티모달 기능(Multimodal out of the box) — 텍스트, 이미지, 숫자, 오디오, 시계열 데이터를 하나의 설정 변경만으로 혼합할 수 있습니다.
- 코드 변경 없이 확장성 확보 —
backend.type을 변경하는 것만으로 노트북 → 다중 GPU → Ray 클러스터로 확장할 수 있습니다.
- 필요할 때 전문가 수준의 제어 가능 — 모든 활성화 함수(activation function), 스케줄러(scheduler), 최적화기(optimizer)가 설정 가능합니다.
- 재현 가능한 연구(Reproducible research) — 모든 실행 기록이 남고 전체 설정 파일이 저장됩니다.
ludwig visualize를 사용하여 실험을 비교할 수 있습니다.
논문 (Publications)
Discord
