Lightwood

Lightwood 是一个 AutoML 框架，它允许你使用称为 JSON-AI 的声明式语法来生成和定制机器学习流水线。

我们的目标是通过让用户专注于他们希望对数据完成的 什么 任务，而无需编写围绕机器学习和数据准备的重复性样板代码，从而使数据科学/机器学习（DS/ML）生命周期更加简便。相反，我们让你能够专注于模型中真正独特且自定义的部分。

Lightwood 支持多种数据类型，如数字、日期、类别、标签、文本、数组以及各种多媒体格式。这些数据类型可以组合在一起以解决复杂问题。我们还支持时间序列模式，适用于存在行间依赖关系的问题。

我们的 JSON-AI 语法允许用户更改 Lightwood 自动生成的模型中的任何部分。该语法详细描述了建模流水线中每一步的具体细节。用户可以覆盖默认值（例如更改某一列的数据类型），或者完全用自定义方法替换某些步骤（例如为预测器使用随机森林模型）。Lightwood 会根据此语法创建一个“JSON-AI”对象，然后可以利用该对象自动生成表示你的流水线的 Python 代码。

有关如何生成 JSON-AI 语法以及 Lightwood 工作原理的详细信息，请参阅 Lightwood 理念。

Lightwood 理念

Lightwood 将 ML 流水线抽象为三个核心步骤：

(1) 预处理与数据清洗
(2) 特征工程
(3) 模型构建与训练

i) 预处理与清洗

对于数据集中的每一列，Lightwood 会通过简短的统计分析识别其疑似数据类型（数值型、类别型等），并据此生成 JSON-AI 语法。

如果用户保持默认行为，Lightwood 将根据识别出的数据类型对每一列进行简要的预处理以清理数据。随后，它会将数据划分为训练集、验证集和测试集。

cleaner 和 splitter 对象分别指代预处理函数和数据划分函数。

ii) 特征工程

数据可以通过“编码器”转换为特征。编码器代表将预处理后的数据转换为模型可使用的数值表示形式的规则。

编码器可以是 基于规则的 或 学习得到的。基于规则的编码器按照特定指令转换数据（例如归一化数值数据），而学习得到的编码器则在训练后生成数据的表示形式（例如语言模型中的“[CLS]”标记）。

编码器会根据数据类型分配给每一列；用户可以在列级别或数据类型级别覆盖这一分配。编码器继承自 BaseEncoder 类。

iii) 模型构建与训练

我们将一种接收 编码后 特征数据并输出目标变量预测结果的预测模型称为 mixer 模型。用户可以选择使用 Lightwood 的默认 mixer，也可以创建自己的实现，这些实现应继承自 BaseMixer 类。

我们主要采用基于 PyTorch 的方法，但也支持其他模型。

使用方法

我们诚邀您查阅我们的 文档 以获取具体的指南和教程！请持续关注更新和变化。

快速用例

Lightwood 可以与 pandas.DataFrame 配合使用。加载 DataFrame 后，通过字典定义一个“ProblemDefinition”。用户唯一需要指定的是待预测列的名称（通过键 target）。

使用命令 json_ai_from_problem 生成 JSON-AI 语法。随后，Lightwood 可以利用该对象通过 code_from_json_ai 自动生成功能完整的 ML 流水线 Python 代码。

你可以创建一个 Predictor 对象，并通过 predictor_from_code 利用该代码实例化。

要从原始数据开始端到端训练一个 Predictor，用户可以使用 predictor.learn() 命令并传入数据。

import pandas as pd
from lightwood.api.high_level import (
    ProblemDefinition,
    json_ai_from_problem,
    code_from_json_ai,
    predictor_from_code,
)

if __name__ == '__main__':
    # 加载一个 pandas 数据集
    df = pd.read_csv("https://raw.githubusercontent.com/mindsdb/benchmarks/main/benchmarks/datasets/hdi/data.csv"
    )

    # 定义预测任务，指定目标列
    pdef = ProblemDefinition.from_dict(
        {
            "target": "Development Index",  # 你想要预测的列
        }
    )

    # 生成用于建模问题的 JSON-AI 代码
    json_ai = json_ai_from_problem(df, problem_definition=pdef)

    # 可选 - 查看 JSON-AI 语法
    # print(json_ai.to_json())

    # 生成 Python 代码
    code = code_from_json_ai(json_ai)

    # 可选 - 查看生成的代码
    # print(code)

    # 从 Python 代码创建预测器
    predictor = predictor_from_code(code)

    # 从原始数据到最终预测器，端到端训练模型
    predictor.learn(df)

    # 划分训练集和测试集，并展示几个示例的预测结果
    test_df = predictor.split(predictor.preprocess(df))["test"]
    preds = predictor.predict(test_df).iloc[:10]
    print(preds)

BYOM：自带模型

只要遵循每个步骤中提供的抽象接口，Lightwood 就支持用户自定义的架构或方法。

我们的 教程 提供了如何在流水线中引入自定义的具体案例。请查看“自定义清洗器”、“自定义分割器”、“自定义解释器”和“自定义 mixer”。敬请期待更多更新。

安装

您可以按照以下方式安装 Lightwood：

pip3 install lightwood

注意：根据您的环境，您可能需要在上述命令中使用 pip 而不是 pip3。

不过，我们建议您创建一个 Python 虚拟环境。

设置开发环境

• Python 版本应在 >=3.8 且 < 3.11 的范围内。
• 克隆 Lightwood 仓库。
• 运行 cd lightwood && pip install -r requirements.txt && pip install -r requirements_image.txt。
• 将其添加到您的 Python 路径中（例如，在您的 ~/.bashrc 文件末尾添加一行：export PYTHONPATH='/where/you/cloned/lightwood':$PYTHONPATH）。
• 进入您克隆 Lightwood 的目录，运行 python -m unittest discover tests，以确保单元测试通过。

如果您的环境中默认使用的是 Python 2.x，请使用 python3 和 pip3 代替。

目前，使用 Lightwood 的首选环境是 Visual Studio Code，这是一个非常流行的 Python IDE。不过，任何 IDE 都应该可以正常工作。虽然我们没有针对其他 IDE 的指南，但您可以将以下内容作为 VSCode 的模板，或者贡献您自己设置其他 IDE 的技巧和经验。

设置 VSCode 环境

• 安装并启用 GitHub 账户同步功能（如果您使用多台机器）。
• 安装 Pylance（用于类型检查），并确保禁用 Pyright。
• 前往 Python > Lint: Enabled，仅保留 flake8，其余全部禁用。
• 将 python.linting.flake8Path 设置为 flake8 的完整路径（即运行 which flake8 找到的路径）。
• 将 Python › Formatting: Provider 设置为 autopep8。
• 在 Python › Formatting: Autopep8 Args 中添加 --global-config=<path_to>/lightwood/.flake8 和 --experimental。
• 安装 Live Share 和 Live Share 白板插件。

参与 Lightwood 的贡献

我们非常欢迎社区的贡献和您的宝贵意见！我们希望让参与 Lightwood 的贡献变得尽可能简单。

只要您有动力并愿意加入这一旅程，任何人都可以成为 Lightwood 核心团队的一员！

如果您有兴趣帮助推动机器学习的民主化，请继续阅读本指南。

您可以如何帮助我们？

• 报告 Bug
• 改进文档
• 解决问题
• 提出新功能
• 讨论功能实现
• 提交 Bug 修复
• 使用您自己的数据测试 Lightwood，并告诉我们结果如何！

代码贡献

一般来说，我们遵循“fork-and-pull”（分叉与拉取）的 Git 工作流程。具体步骤如下：

1. 分叉 Lightwood 仓库。
2. 进行更改并提交。
3. 确保 CI 测试通过。您可以在本地运行测试套件，使用 flake8 . 检查代码风格，使用 python -m unittest discover tests 运行自动化测试。这并不能保证远程测试一定通过，因为我们会在多个环境中运行，但在大多数情况下应该没问题。
4. 将您的本地分支推送到您的分叉仓库。
5. 从您的仓库向 mindsdb/lightwood 的 main 分支提交拉取请求，以便我们审查您的更改。请务必在提交拉取请求之前合并 main 分支的最新代码！

注意：由于 Lightwood 采用 GPL 许可证，您需要签署一份代码许可协议。

功能与 Bug 报告

我们使用 GitHub Issues 来跟踪 Bug 和功能需求。请通过打开 新 Issue 并填写所有必填项来报告问题。

代码评审流程

拉取请求（PR）评审会定期进行。如果您的 PR 没有针对之前的某个问题，请先创建一个 Issue。

如果您的更改可能影响性能，我们将运行我们的私有基准测试套件来验证它。

请务必及时回复我们的反馈或问题。

社区

如果您有任何其他问题，或想与 MindsDB 核心团队交流，欢迎加入我们的社区：MindsDB Community。

要获取 Lightwood 和 MindsDB 的最新公告、发布信息及活动动态，请订阅我们的 每月社区通讯。

加入我们，共同推动机器学习的民主化进程，让开发者也能成为数据科学家！

贡献者行为准则

请注意，本项目遵循 贡献者行为准则。参与本项目即表示您同意遵守其中的各项条款。

当前贡献者

许可证

• Lightwood 许可证

Lightwood 快速上手指南

Lightwood 是一个 AutoML 框架，允许用户通过声明式的 JSON-AI 语法生成和定制机器学习流水线。它旨在简化数据科学流程，让用户专注于业务逻辑而非重复的样板代码，支持数值、日期、类别、文本、数组及多媒体等多种数据类型，并具备时间序列处理能力。

环境准备

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

• 操作系统：Linux, macOS 或 Windows
• Python 版本：>= 3.8 且 < 3.11
• 前置依赖：建议安装 pandas 用于数据处理
• 虚拟环境：强烈建议使用 Python 虚拟环境（如 venv 或 conda）以避免依赖冲突

安装步骤

1. 创建并激活虚拟环境（推荐）

python -m venv lightwood_env
# Linux/macOS
source lightwood_env/bin/activate
# Windows
lightwood_env\Scripts\activate

2. 安装 Lightwood

使用 pip 进行安装。国内用户若遇到下载速度慢的问题，可指定清华或阿里镜像源加速。

通用安装命令：

pip3 install lightwood

使用国内镜像源加速安装（推荐）：

pip3 install lightwood -i https://pypi.tuna.tsinghua.edu.cn/simple

注意：根据您的环境配置，可能需要将 pip3 替换为 pip。

基本使用

Lightwood 的核心工作流基于 pandas.DataFrame。只需定义预测目标，框架即可自动生成预处理、特征工程和模型训练的完整代码。

以下是最简化的端到端使用示例：

import pandas as pd
from lightwood.api.high_level import (
    ProblemDefinition,
    json_ai_from_problem,
    code_from_json_ai,
    predictor_from_code,
)

if __name__ == '__main__':
    # 1. 加载 pandas DataFrame 数据集
    df = pd.read_csv("https://raw.githubusercontent.com/mindsdb/benchmarks/main/benchmarks/datasets/hdi/data.csv")

    # 2. 定义预测任务：指定目标列名称
    pdef = ProblemDefinition.from_dict(
        {
            "target": "Development Index",  # 您想要预测的列名
        }
    )

    # 3. 根据问题定义生成 JSON-AI 对象
    json_ai = json_ai_from_problem(df, problem_definition=pdef)

    # 4. 从 JSON-AI 生成具体的 Python 流水线代码
    code = code_from_json_ai(json_ai)

    # 5. 实例化预测器对象
    predictor = predictor_from_code(code)

    # 6. 端到端训练：从原始数据直接训练出最终模型
    predictor.learn(df)

    # 7. 进行预测
    # 先划分测试集
    test_df = predictor.split(predictor.preprocess(df))["test"]
    # 获取前 10 条预测结果
    preds = predictor.predict(test_df).iloc[:10]
    print(preds)

核心步骤说明：

1. ProblemDefinition: 仅需指定 target（目标列），Lightwood 会自动推断其他列的数据类型。
2. json_ai_from_problem: 分析数据并生成描述流水线结构的 JSON-AI 对象。
3. code_from_json_ai: 将 JSON-AI 对象转换为可执行的 Python 代码。
4. predictor.learn(): 自动执行数据清洗、分割、特征编码及模型训练。

如需自定义流水线（例如更换特定的编码器或模型架构），可修改生成的 json_ai 对象后再转换为代码，具体请参考官方文档中的 "BYOM: Bring your own models" 部分。