# Fine-tune Llama-3.1 with LoRA in one config file
model_type: llm
base_model: meta-llama/Llama-3.1-8B
adapter:
  type: lora
trainer:
  type: finetune
  epochs: 3
input_features:
  - name: instruction
    type: text
output_features:
  - name: response
    type: text

ludwig train --config model.yaml --dataset my_data.csv

技术栈： Python 3.12 · PyTorch 2.7+ · Pydantic 2 · Transformers 5 · Ray 2.54

Ludwig 由 Linux Foundation AI & Data. 托管。

Ludwig 0.16 新特性

功能	说明
PatchTST 与 N-BEATS 编码器	配备 MASE/sMAPE 指标的最先进时间序列预测编码器
高级 PEFT 适配器	PiSSA、EVA、CorDA/LoftQ 初始化器；TinyLoRA、OFT、HRA、WaveFT、LN-Tuning、VBLoRA、C3A 适配器类型
VLM 微调	通过 `is_multimodal: true`，配合门控交叉注意力训练 LLaVA、Qwen2-VL、InternVL
HyperNetwork 组合器	基于条件的特征融合——由一个特征为其他特征生成权重
Nash-MTL 与 Pareto-MTL	基于博弈论与偏好的多任务损失平衡
LLM 配置生成	`ludwig generate_config "describe your task"` — 由 LLM 为你编写 YAML
ModelInspector	架构分析、权重收集、特征重要性代理
Ray Serve 与 KServe	分布式与 Kubernetes 原生的模型部署适配层
GRPO 对齐	通过 Group Relative Policy Optimization 实现无奖励模型的 RLHF
torchao 量化 + QAT	PyTorch 原生的 `int4/int8/float8`，支持量化感知训练（Quantization-Aware Training）
多适配器 PEFT	多个命名的 LoRA 适配器，支持加权合并（TIES、DARE、SVD）
原生 Optuna 执行器	GPT/TPE/CMA-ES 采样器、剪枝、可恢复的 SQLite/PostgreSQL 存储
时间序列预测	`model.forecast(dataset, horizon=N)` API，配合 `TimeseriesOutputFeature`
Muon 与 ScheduleFreeAdamW	面向大规模预训练与微调的新优化器
图像分割解码器	用于语义分割的 UNet、SegFormer、FPN 解码器

安装

pip install ludwig           # core
pip install ludwig[full]     # all optional dependencies
pip install ludwig[llm]      # LLM fine-tuning only

需要 Python 3.12+。完整依赖矩阵见 contributing。

快速入门

微调 LLM（指令微调）

Ludwig 支持完整的 LLM 微调技术谱系：

技术	配置键
监督微调（SFT）	`trainer.type: finetune`
DPO / KTO / ORPO / GRPO 对齐	`trainer.type: dpo`（或 `kto`、`orpo`、`grpo`）
LoRA / DoRA / VeRA / PiSSA	`adapter.type: lora`（或 `dora`、`vera`、`lora` + `init_weights: pissa`）
4-bit QLoRA（bitsandbytes）	`quantization.bits: 4`
torchao + QAT	`quantization.backend: torchao`
多适配器合并	`adapters:` dict + `merge:` block
VLM（视觉-语言）	`is_multimodal: true`

model_type: llm
base_model: meta-llama/Llama-3.1-8B

quantization:
  bits: 4

adapter:
  type: lora

prompt:
  template: |
    ### Instruction: {instruction}
    ### Input: {input}
    ### Response:

input_features:
  - name: prompt
    type: text

output_features:
  - name: output
    type: text

trainer:
  type: finetune
  learning_rate: 0.0001
  batch_size: 1
  gradient_accumulation_steps: 16
  epochs: 3
  learning_rate_scheduler:
    decay: cosine
    warmup_fraction: 0.01

backend:
  type: local

export HUGGING_FACE_HUB_TOKEN="<your_token>"
ludwig train --config model.yaml --dataset "ludwig://alpaca"

训练多模态分类器

input_features:
  - name: review_text
    type: text
    encoder:
      type: bert
  - name: star_rating
    type: number
  - name: product_image
    type: image
    encoder:
      type: dinov2

output_features:
  - name: recommended
    type: binary

ludwig train --config model.yaml --dataset reviews.csv

从自然语言生成配置

ludwig generate_config "I have a CSV with age, income, education level, and I want to predict loan default"

进行预测

ludwig predict --model_path results/experiment_run/model --dataset new_data.csv

启动 REST API

ludwig serve --model_path results/experiment_run/model
# POST http://localhost:8000/predict

功能

LLM 微调

在指令/回复对上监督微调（SFT）
对齐训练：DPO、KTO、ORPO、GRPO（无奖励模型的 RLHF）
PEFT 适配器：LoRA、DoRA、VeRA、LoRA+、TinyLoRA、OFT、HRA、WaveFT、LN-Tuning、VBLoRA、C3A
LoRA 初始化器：PiSSA、EVA、CorDA、LoftQ，提升收敛效果
多适配器 PEFT：在同一基座模型上配置多个命名适配器，运行时可切换；支持 TIES、DARE、SVD、幅度剪枝合并
量化：4-bit/8-bit QLoRA（bitsandbytes），torchao int4/int8/float8 配合 QAT
VLM 微调：通过 is_multimodal: true 微调 LLaVA、Qwen2-VL、InternVL
序列打包，高效处理变长输入训练
分页与 8-bit 优化器，实现省内存训练

多模态与表格模型（Multimodal & Tabular Models）

输入模态：text、numbers、categories、binary、sets、bags、sequences、images、audio、timeseries、vectors、dates
文本编码器：任意 HuggingFace Transformer（BERT、RoBERTa、ModernBERT、Qwen3、Llama-3.1 等），以及 Mamba-2、Jamba
图像编码器：DINOv2、ConvNeXt、EfficientNet、ViT、CAFormer、ConvFormer、PoolFormer、TIMM（1000+ 模型）
时间序列编码器：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）
图像分割：UNet、SegFormer、FPN decoders

训练基础设施（Training Infrastructure）

分布式训练：HuggingFace Accelerate，支持 DDP、FSDP、DeepSpeed（零代码改动）
Ray 后端：在 Ray 集群上训练，通过 Ray Data 处理超内存数据集
自动批大小选择与学习率范围测试（learning rate range test）
混合精度（fp16/bf16）、梯度检查点（gradient checkpointing）、梯度累积（gradient accumulation）
优化器：AdamW、Adafactor、SGD、Muon、ScheduleFreeAdamW、Lion、paged/8-bit 变体
学习率调度器：cosine、linear、polynomial、reduce-on-plateau、OneCycleLR
Model Soup：均匀与贪心检查点平均，在零推理成本下提升泛化
模态 dropout（Modality dropout），用于构建鲁棒的多模态模型

超参数优化（Hyperparameter Optimization）

执行器：Ray Tune（ASHA、PBT、Bayesian）与原生 Optuna（auto/GP/TPE/CMA-ES）
Optuna 持久化：SQLite 或 PostgreSQL，支持可恢复的 HPO 运行
剪枝（Pruning）：使用 Optuna 的 MedianPruner 与 HyperbandPruner
搜索空间：uniform、log-uniform、choice、randint、quantized
完整 Ludwig 配置可搜索 — 任意嵌套参数均可作为超参数

生产与部署（Production & Deployment）

REST API：FastAPI 服务，含 Prometheus 指标与结构化日志（ludwig serve）
vLLM 服务：OpenAI 兼容 API，支持 PagedAttention 与连续批处理（continuous batching）
Ray Serve：分布式部署，支持自动扩缩容与流量分流
KServe：Kubernetes 原生部署，支持 Open Inference Protocol v2
模型导出：SafeTensors（默认）、torch.export .pt2 bundles、ONNX
HuggingFace Hub：ludwig upload hf_hub — 推送模型并自动生成 model card
Docker：预构建容器位于 ludwigai/ludwig

工具与集成（Tooling & Integrations）

实验跟踪：TensorBoard、Weights & Biases、Comet ML、MLflow、Aim Stack
模型检查：ModelInspector — 权重枚举、架构摘要、特征重要性代理（feature importance proxy）
可视化：学习曲线、混淆矩阵、校准图、ROC 曲线、超参优化分析
AutoML：ludwig.automl.auto_train() — 提供数据集与时间预算；YAML 驱动的搜索空间会采样 encoder/combiner/decoder 组合，并在训练前进行验证
数据集质量检查：from ludwig.utils.dataset_quality import check_dataset_quality — 在训练前验证 DataFrame（缺失值、类别不平衡、近重复列、ID 泄漏等）
OpenML 集成：直接加载任意 OpenML 任务 — OpenMLLoader 按任务 ID 获取并本地缓存为 Parquet
LLM 配置生成：ludwig generate_config "describe your task" — 由 LLM 编写 YAML
K 折交叉验证：ludwig experiment --k_fold N
Dataset Zoo：70+ 内置基准数据集（ludwig://mnist、ludwig://alpaca 等）

示例（Examples）

LLM 与对齐（LLM & Alignment）

用例	链接
LLM 指令微调（LoRA + QLoRA）	examples/llm
DPO / GRPO 对齐	examples/llm/alignment
高级 PEFT（PiSSA、OFT、VBLoRA 等）	examples/llms/peft_advanced
VLM 微调（LLaVA、Qwen2-VL）	examples/vlm

表格与多模态（Tabular & Multimodal）

用例	链接
二分类（Titanic）	examples/titanic
表格分类（census income）	examples/adult_census_income
多模态分类	examples/multimodal_classification
多任务学习	examples/multi_task

时间序列与视觉（Timeseries & Vision）

用例	链接
时间序列预测（PatchTST、N-BEATS）	examples/forecasting
天气预报	examples/weather
图像分类（MNIST）	examples/mnist
语义分割	examples/semantic_segmentation

NLP 与音频（NLP & Audio）

用例	链接
文本分类	examples/text_classification
命名实体识别	examples/ner_tagging
机器翻译	examples/machine_translation
语音识别	examples/speech_recognition
说话人验证	examples/speaker_verification

为什么选择 Ludwig？（Why Ludwig?）

零样板代码 — 无需训练循环、数据流水线或评估代码。YAML 配置即完整程序。
一流的 LLM 支持 — 从 LoRA 到 GRPO 对齐、torchao QAT 与 VLM 微调，全谱系能力均可通过配置实现。
开箱即用的多模态 — 只需修改一项配置，即可混合 text、images、numbers、audio 与 timeseries。
无需改代码即可扩展 — 通过修改 backend.type，从笔记本 → 多 GPU → Ray 集群无缝扩展。
需要时可精细控制 — 每个激活函数、调度器与优化器均可配置。
可复现的研究 — 每次运行都会记录日志并保存完整配置。使用 ludwig visualize 对比实验。

出版物

社区

Discord — 提问、分享你的作品
GitHub Issues — 错误报告与功能请求
X / Twitter — 公告
Medium — 教程与深度文章

项目文件夹

README.md Unescape Escape

什么是 Ludwig？