> [!NOTE]
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
> [English](./README.en.md) · [原始项目](https://github.com/ludwig-ai/ludwig) · [上游 README](https://github.com/ludwig-ai/ludwig/blob/HEAD/README.md)
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
**面向 LLM、多模态模型与表格 AI 的声明式深度学习框架。**
[](https://badge.fury.io/py/ludwig)
[](https://discord.gg/CBgdrGnZjy)
[](https://hub.docker.com/r/ludwigai)
[](https://pepy.tech/project/ludwig)
[](https://github.com/ludwig-ai/ludwig/blob/main/LICENSE)
[](https://twitter.com/ludwig_ai)
[**文档**](https://ludwig.ai) · [**快速入门**](https://ludwig.ai/latest/getting_started/) · [**示例**](https://ludwig.ai/latest/examples) · [**Discord**](https://discord.gg/CBgdrGnZjy)
______________________________________________________________________
## 什么是 Ludwig？
Ludwig 是一个**声明式深度学习框架**，让你通过 YAML 配置文件和零样板 Python 代码来训练、微调并部署 AI 模型——从 LLM 微调到表格分类均可覆盖。
```yaml
# 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
```
```bash
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](https://lfaidata.foundation/). 托管。
______________________________________________________________________
## 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 解码器 |
______________________________________________________________________
## 安装
```bash
pip install ludwig # core
pip install ludwig[full] # all optional dependencies
pip install ludwig[llm] # LLM fine-tuning only
```
需要 Python 3.12+。完整依赖矩阵见 [contributing](https://github.com/ludwig-ai/ludwig/blob/main/CONTRIBUTING.md)。
______________________________________________________________________
## 快速入门
### 微调 LLM（指令微调）
[](https://colab.research.google.com/drive/1c3AO8l_H6V_x37RwQ8V7M6A-RmcBf2tG?usp=sharing)
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` |
```yaml
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
```
```bash
export HUGGING_FACE_HUB_TOKEN=""
ludwig train --config model.yaml --dataset "ludwig://alpaca"
```
### 训练多模态分类器
```yaml
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
```
```bash
ludwig train --config model.yaml --dataset reviews.csv
```
### 从自然语言生成配置
```bash
ludwig generate_config "I have a CSV with age, income, education level, and I want to predict loan default"
```
### 进行预测
```bash
ludwig predict --model_path results/experiment_run/model --dataset new_data.csv
```
### 启动 REST API
```bash
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](https://hub.docker.com/u/ludwigai)
工具与集成（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](https://ludwig.ai/latest/examples/llm/llm_finetuning) |
| DPO / GRPO 对齐 | [examples/llm/alignment](https://ludwig.ai/latest/examples/llm/alignment) |
| 高级 PEFT（PiSSA、OFT、VBLoRA 等） | [examples/llms/peft_advanced](https://ludwig.ai/latest/examples/llms/peft_advanced) |
| VLM 微调（LLaVA、Qwen2-VL） | [examples/vlm](https://github.com/ludwig-ai/ludwig/tree/main/examples/vlm) |
### 表格与多模态（Tabular & Multimodal）
| 用例 | 链接 |
| -------------------------------------- | ------------------------------------------------------------------------------------------------- |
| 二分类（Titanic） | [examples/titanic](https://ludwig.ai/latest/examples/titanic) |
| 表格分类（census income） | [examples/adult_census_income](https://ludwig.ai/latest/examples/adult_census_income) |
| 多模态分类 | [examples/multimodal_classification](https://ludwig.ai/latest/examples/multimodal_classification) |
| 多任务学习 | [examples/multi_task](https://ludwig.ai/latest/examples/multi_task) |
### 时间序列与视觉（Timeseries & Vision）
| 用例 | 链接 |
| ------------------------------------------ | ----------------------------------------------------------------------------------------- |
| 时间序列预测（PatchTST、N-BEATS） | [examples/forecasting](https://ludwig.ai/latest/examples/forecasting) |
| 天气预报 | [examples/weather](https://ludwig.ai/latest/examples/weather) |
| 图像分类（MNIST） | [examples/mnist](https://ludwig.ai/latest/examples/mnist) |
| 语义分割 | [examples/semantic_segmentation](https://ludwig.ai/latest/examples/semantic_segmentation) |
### NLP 与音频（NLP & Audio）
| 用例 | 链接 |
| ------------------------ | --------------------------------------------------------------------------------------- |
| 文本分类 | [examples/text_classification](https://ludwig.ai/latest/examples/text_classification) |
| 命名实体识别 | [examples/ner_tagging](https://ludwig.ai/latest/examples/ner_tagging) |
| 机器翻译 | [examples/machine_translation](https://ludwig.ai/latest/examples/machine_translation) |
| 语音识别 | [examples/speech_recognition](https://ludwig.ai/latest/examples/speech_recognition) |
| 说话人验证 | [examples/speaker_verification](https://ludwig.ai/latest/examples/speaker_verification) |
______________________________________________________________________
## 为什么选择 Ludwig？（Why Ludwig?）
- **零样板代码** — 无需训练循环、数据流水线或评估代码。YAML 配置即完整程序。
- **一流的 LLM 支持** — 从 LoRA 到 GRPO 对齐、torchao QAT 与 VLM 微调，全谱系能力均可通过配置实现。
- **开箱即用的多模态** — 只需修改一项配置，即可混合 text、images、numbers、audio 与 timeseries。
- **无需改代码即可扩展** — 通过修改 `backend.type`，从笔记本 → 多 GPU → Ray 集群无缝扩展。
- **需要时可精细控制** — 每个激活函数、调度器与优化器均可配置。
- **可复现的研究** — 每次运行都会记录日志并保存完整配置。使用 `ludwig visualize` 对比实验。
______________________________________________________________________
## 出版物
- [Ludwig：基于类型的声明式深度学习工具箱](https://arxiv.org/pdf/1909.07930.pdf) (2019)
- [声明式机器学习系统](https://arxiv.org/pdf/2107.08148.pdf) (2021)
- [Ludwig 的最先进（State-of-the-Art）基准测试](https://openreview.net/pdf?id=hwjnu6qW7E4)
______________________________________________________________________
## 社区
[](https://discord.gg/CBgdrGnZjy)
- [Discord](https://discord.gg/CBgdrGnZjy) — 提问、分享你的作品
- [GitHub Issues](https://github.com/ludwig-ai/ludwig/issues) — 错误报告与功能请求
- [X / Twitter](https://twitter.com/ludwig_ai) — 公告
- [Medium](https://medium.com/ludwig-ai) — 教程与深度文章
[](https://star-history.com/#ludwig-ai/ludwig&Date)