📖 Ludwig 是什么？

Ludwig 是一个 低代码 框架，用于构建 自定义 的 AI 模型，例如 LLM 和其他深度神经网络。

主要特性：

• 🛠 轻松构建自定义模型： 只需一个声明式的 YAML 配置文件，即可在您的数据上训练出最先进的 LLM。支持多任务和多模态学习。全面的配置验证能够检测无效的参数组合，并防止运行时错误。
• ⚡ 针对规模化与效率优化： 自动批量大小选择、分布式训练（DDP、DeepSpeed）、参数高效的微调（PEFT）、4位量化（QLoRA）、分页及8位优化器，以及超出内存容量的数据集。
• 📐 专家级控制： 您可以完全掌控模型的每一个细节，包括激活函数等。支持超参数优化、可解释性分析以及丰富的指标可视化。
• 🧱 模块化与可扩展性： 仅需在配置中进行少量参数调整，即可尝试不同的模型架构、任务、特征和模态。就像搭建深度学习的积木一样。
• 🚢 专为生产环境设计： 提供预构建的 Docker 容器，原生支持使用 Ray 在 Kubernetes 上运行，可将模型导出为 Torchscript 和 Triton，并可通过一条命令上传至 HuggingFace。

Ludwig 由 Linux 基金会人工智能与数据组织 托管。

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

💾 安装

从 PyPI 安装。请注意，Ludwig 需要 Python 3.12 或更高版本。

pip install ludwig

或者安装包含所有可选依赖项的版本：

pip install ludwig[full]

更多详细的安装说明，请参阅 贡献指南。

🚂 入门

想快速了解 Ludwig 的一些功能吗？请查看这个 Colab 笔记本 🚀

想要微调 LLM 吗？请查看以下笔记本：

1. 微调 Llama-2-7b：
2. 微调 Llama-2-13b：
3. 微调 Mistral-7b：

如需完整教程，请参阅官方的 入门指南 或查看端到端的 示例。

大型语言模型微调

让我们对一个预训练的 LLM 进行微调，使其能够像聊天机器人一样遵循指令（“指令微调”）。

前提条件

• HuggingFace API Token
• 对所选基础模型的访问权限（例如，Llama-3.1-8B）
• 至少配备 12 GiB 显存的 GPU（我们在测试中使用了 Nvidia T4）

运行步骤

我们将使用 Stanford Alpaca 数据集，该数据集将被格式化为类似表格的文件，内容如下：

指令	输入	输出
给出三条保持健康的建议。		1. 保持均衡饮食，并确保摄入...
将下列物品按顺序排列：蛋糕、我、吃	蛋糕、我、吃	我正在吃蛋糕。
写一段关于著名人物的介绍性段落...	米歇尔·奥巴马	米歇尔·奥巴马是一位鼓舞人心的女性，她...
...	...	...

创建一个名为 model.yaml 的 YAML 配置文件，内容如下：

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

quantization:
  bits: 4

adapter:
  type: lora

prompt:
  template: |
    下面是一条描述任务的指令，以及可能提供进一步上下文的输入。
    请撰写一个恰当回应请求的内容。

    ### 指令：
    {instruction}

    ### 输入：
    {input}

    ### 回答：

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

preprocessing:
  sample_ratio: 0.1

backend:
  type: local

现在让我们开始训练模型：

export HUGGING_FACE_HUB_TOKEN = "<api_token>"

ludwig train --config model.yaml --dataset "ludwig://alpaca"

监督学习

让我们构建一个神经网络，用于预测给定的电影评论家在烂番茄上的影评是正面还是负面。

我们的数据集将是一个看起来像这样的CSV文件：

电影标题	内容分级	类型	片长	权威影评人	影评内容	是否推荐
拯救恶灵	R	动作与冒险、恐怖	117.0	TRUE	导演斯科特·德里克森和他的联合编剧保罗·哈里斯·博德曼带来了一部平庸的程序化影片，惊悚效果乏善可陈。	0
巴巴拉	PG-13	艺术片与国际片、剧情片	105.0	FALSE	在这个感人至深的故事中，芭芭拉设法坚守自己的原则、人性与勇气，奋力拯救一位正被共产党试图摧毁生命的年轻女异议分子。	1
糟糕老板们	R	喜剧	98.0	FALSE	这些老板既无法为谋杀辩护，也无法留下令人难忘的喜剧记忆，从而彻底破坏了一出本可以很出色的闹剧，最终却只沦为平庸之作。	0
...	...	...	...	...	...	...

从这里下载该数据集的样本。

wget https://ludwig.ai/latest/data/rotten_tomatoes.csv

接下来，创建一个名为model.yaml的YAML配置文件，内容如下：

input_features:
  - name: genres
    type: set
    preprocessing:
      tokenizer: comma
  - name: content_rating
    type: category
  - name: top_critic
    type: binary
  - name: runtime
    type: number
  - name: review_content
    type: text
    encoder:
      type: embed
output_features:
  - name: recommended
    type: binary

就这些！现在让我们训练模型：

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

祝建模愉快

尝试将Ludwig应用于你的数据。如果你有任何问题，请通过Discord联系我们。

❓ 为什么你应该使用Ludwig

• 极简的机器学习样板代码

  Ludwig开箱即用地处理了机器学习中的工程复杂性，使研究科学家能够专注于在最高抽象层次上构建模型。数据预处理、超参数优化、设备管理以及针对torch.nn.Module模型的分布式训练都完全免费提供。

• 轻松构建基准测试

  创建最先进的基线并与新模型进行比较，只需简单的配置更改即可。

• 轻松将新架构应用于多个问题和数据集

  将新模型应用于Ludwig支持的广泛任务和数据集。Ludwig包含一个对任何用户开放的完整基准测试工具包，只需简单配置即可在多个数据集上运行多种模型的实验。

• 高度可配置的数据预处理、建模和指标

  模型架构、训练循环、超参数搜索以及后端基础设施的任何方面都可以作为声明式配置中的附加字段进行修改，以定制流水线来满足你的需求。有关可配置内容的详细信息，请参阅Ludwig配置文档。

• 开箱即用的多模态、多任务学习

  无需编写代码，即可将表格数据、文本、图像甚至音频混合搭配成复杂的模型配置。

• 丰富的模型导出与跟踪功能

  自动使用Tensorboard、Comet ML、Weights & Biases、MLFlow和Aim Stack等工具跟踪所有试验和指标。

• 自动将训练扩展到多GPU、多节点集群

  无需更改代码，即可从本地机器上的训练过渡到云端。

• 低代码接口，适用于最先进的模型，包括预训练的Huggingface Transformers

  Ludwig还原生集成预训练模型，例如Huggingface Transformers中提供的模型。用户可以从大量最先进的预训练PyTorch模型中选择，而无需编写任何代码。例如，使用Ludwig训练基于BERT的情感分析模型非常简单：

  ludwig train --dataset sst5 --config_str "{input_features: [{name: sentence, type: text, encoder: bert}], output_features: [{name: label, type: category}]}"
  

• 低代码接口，用于AutoML

  Ludwig AutoML允许用户仅提供数据集、目标列和时间预算即可获得训练好的模型。

  auto_train_results = ludwig.automl.auto_train(dataset=my_dataset_df, target=target_column_name, time_limit_s=7200)
  

• 易于生产部署

  Ludwig使深度学习模型的部署变得容易，包括在GPU上部署。为你的Ludwig训练好的模型启动一个REST API。

  ludwig serve --model_path=/path/to/model
  

  Ludwig还支持将模型导出为高效的Torchscript捆绑包。

  ludwig export_torchscript -–model_path=/path/to/model
  

📚 教程

• 文本分类
• 表格数据分类
• 图像分类
• 多模态分类

🔬 示例用例

• 命名实体识别标注
• 自然语言理解
• 机器翻译
• 基于序列到序列的闲聊对话建模
• 情感分析
• 使用暹罗网络进行一次学习
• 视觉问答
• 语音数字识别
• 说话人验证
• 二分类（泰坦尼克号）
• 时间序列预测
• 时间序列预测（天气）
• 电影评分预测
• 多标签分类
• 多任务学习
• 简单回归：燃油效率预测
• 欺诈检测

💡 更多信息

阅读我们在 Ludwig、声明式机器学习 以及 Ludwig 的 SOTA 基准测试 方面的论文。

了解更多关于 Ludwig 的工作原理、如何开始使用 的信息，并查看更多 示例。

如果您有兴趣 参与贡献，或有任何问题、意见和想法想要分享，亦或是希望随时了解最新动态，请考虑 加入我们的社区 Discord，并关注我们在 X 上的账号！

🤝 加入社区，与我们一起构建 Ludwig

Ludwig 是一个由社区积极维护的开源项目，其发展离不开像您这样的贡献者。欢迎加入活跃的 Ludwig 贡献者团队，共同让 Ludwig 成为一个更加易用、功能更丰富的框架，惠及每一位用户！

星标历史

👋 如何参与

• Discord
• X（Twitter）
• Medium
• GitHub 问题

Ludwig 快速上手指南

Ludwig 是一个声明式的低代码深度学习框架，专为构建自定义 AI 模型（包括大语言模型 LLM）而设计。通过简单的 YAML 配置文件，即可实现数据预处理、模型训练、超参数优化及分布式训练，无需编写复杂的底层代码。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Linux, macOS 或 Windows (WSL2 推荐)
• Python 版本：必须为 Python 3.12 或更高版本
• 硬件要求：
  • 基础任务：普通 CPU 或任意 GPU
  • LLM 微调：建议配备至少 12GB 显存的 NVIDIA GPU (如 T4, A10G 等)
• 前置依赖：建议预先安装好 CUDA 驱动（如需 GPU 加速）

国内开发者提示：由于 PyPI 源在国外访问较慢，建议使用国内镜像源进行安装。

安装步骤

1. 基础安装

使用 pip 安装核心功能：

pip install ludwig -i https://pypi.tuna.tsinghua.edu.cn/simple

2. 全功能安装（推荐）

若需使用所有可选依赖（包括特定编码器、可视化工具等），请执行：

pip install "ludwig[full]" -i https://pypi.tuna.tsinghua.edu.cn/simple

基本使用

Ludwig 的核心工作流分为三步：准备数据 -> 编写配置 -> 运行训练。

场景一：监督学习（文本分类）

假设我们要根据电影评论预测其是否被推荐（基于 Rotten Tomatoes 数据集）。

1. 准备数据 下载示例数据：

wget https://ludwig.ai/latest/data/rotten_tomatoes.csv

2. 创建配置文件 新建 model.yaml，定义输入特征（类型自动识别）和输出目标：

input_features:
  - name: genres
    type: set
    preprocessing:
      tokenizer: comma
  - name: content_rating
    type: category
  - name: top_critic
    type: binary
  - name: runtime
    type: number
  - name: review_content
    type: text
    encoder:
      type: embed
output_features:
  - name: recommended
    type: binary

3. 启动训练 执行以下命令开始训练：

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

---

场景二：大语言模型微调 (LLM Fine-Tuning)

以微调 Llama-3.1-8B 模型使其遵循指令为例。

1. 前置检查

• 获取 HuggingFace API Token。
• 确保已获准访问基座模型（如 meta-llama/Llama-3.1-8B）。
• 设置环境变量：

  export HUGGING_FACE_HUB_TOKEN="<你的_api_token>"
  

2. 创建配置文件 新建 model.yaml，配置量化（4-bit）、适配器（LoRA）及训练参数：

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

quantization:
  bits: 4

adapter:
  type: lora

prompt:
  template: |
    Below is an instruction that describes a task, paired with an input that may provide further context.
    Write a response that appropriately completes the request.

    ### 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

preprocessing:
  sample_ratio: 0.1

backend:
  type: local

3. 启动训练 使用内置的 Alpaca 数据集进行训练：

ludwig train --config model.yaml --dataset "ludwig://alpaca"

训练完成后，模型将自动保存，并可导出为 TorchScript 或上传至 HuggingFace。