模型导出

导出 Ludwig 模型¶

在 Ludwig 中有多种方式可以导出模型。

TorchScript 导出¶

一部分 Ludwig 模型可以端到端地导出为 Torchscript。这意味着除了模型本身，预处理和后处理步骤也可以导出到 TorchScript，确保模型可以直接用于生产环境中的推理。

要开始使用，只需运行 export_torchscript 命令

ludwig export_torchscript -m=results/experiment_run/model

只要不指定 --model_only，该命令将输出三个文件。其中最重要的是 inference_preprocessor.pt、inference_predictor_<DEVICE>.pt 和 inference_postprocessor.pt。

inference_preprocessor.pt 文件包含预处理器，它是一个 torch.nn.Module，接受原始数据的字典作为输入，并输出张量字典。inference_predictor_<DEVICE>.pt 文件包含预测器，它是一个 torch.nn.Module，接受张量字典作为输入，并输出张量字典。inference_postprocessor.pt 文件包含后处理器，它是一个 torch.nn.Module，接受张量字典作为输入，并输出包含与 Ludwig predict 命令 DataFrame 输出相同键的后处理数据字典。这些文件可以单独加载（并在不同的设备上），以分阶段运行推理。这对于 NVIDIA Triton 等工具尤其有用，该工具可以独立管理管道的每个阶段。

您可以通过使用 torch.jit.load 加载这些模块来立即开始使用它们

>>> import torch
>>> preprocessor = torch.jit.load("model/inference_preprocessor.pt")
>>> predictor = torch.jit.load("model/inference_predictor_cpu.pt")
>>> postprocessor = torch.jit.load("model/inference_postprocessor.pt")

完成此操作后，您可以以字典形式传入原始数据，并以字典形式获取预测结果

>>> raw_data = {
    'text_feature': ['This is a test.'],
    'category_feature': ['cat1', 'cat2'],
    'numerical_feature': [1.0, 2.0],
    'vector_feature': [[1.0, 2.0], [3.0, 4.0]],
}
>>> preprocessed_data = preprocessor(raw_data)
>>> predictions = predictor(preprocessed_data)
>>> postprocessed_data = postprocessor(predictions)
>>> postprocessed_data
{
    'probabilities': [[0.8, 0.2]],
    'predictions': ['class1', 'class2'],
}

如果您的数据存储在 DataFrame 中，您可以使用 to_inference_module_input_from_dataframe 函数将其转换为正确的格式

>>> import pandas as pd
>>> from ludwig.utils.inference_utils import to_inference_module_input_from_dataframe

>>> df = pd.read_csv('test.csv')
>>> raw_data = to_inference_module_input_from_dataframe(df)
>>> raw_data
{
    'text_feature': ['This is a test.'],
    'category_feature': ['cat1', 'cat2'],
    'numerical_feature': [1.0, 2.0],
    'vector_feature': [[1.0, 2.0], [3.0, 4.0]],
}

使用 InferenceModule 类¶

为方便起见，我们提供了一个名为 InferenceModule 的包装类，可用于加载和使用导出的模型。InferenceModule 类是 torch.nn.Module 的子类，可以以相同的方式使用。InferenceModule 类可以在一个步骤中加载预处理器、预测器和后处理器。

>>> from ludwig.models.inference import InferenceModule
>>> inference_module = InferenceModule.from_directory('model/')
>>> raw_data = {...}
>>> preprocessed_data = inference_module.preprocessor_forward(raw_data)
>>> predictions = inference_module.predictor_forward(preprocessed_data)
>>> postprocessed_data = inference_module.postprocessor_forward(predictions)

您也可以单独调用预处理器、预测器和后处理器。

>>> inference_module.preprocessor_forward(raw_data)
{...}

您还可以使用 InferenceModule.predict 方法输入 DataFrame 并输出 DataFrame，类似于使用 LudwigModel.predict 方法的方式。

>>> input_df = pd.read_csv('test.csv')
>>> output_df = inference_module.predict(input_df)

最后，如果您需要一个用于推理的整体工件，可以将 InferenceModule 转换为 TorchScript。请注意，您仍然可以调用 InferenceModule.preprocessor_forward、InferenceModule.predictor_forward 和 InferenceModule.postprocessor_forward 方法，但在此转换后 InferenceModule.predict 将不再起作用。

>>> scripted_module = torch.jit.script(inference_module)
>>> raw_data = {...}
>>> scripted_module(raw_data)
{...}
>>> input_df = pd.read_csv('test.csv')
>>> scripted_module.predict(input_df)  # Will fail

当前限制¶

TorchScript 仅实现了一部分 Python 库。这意味着 Ludwig 的一些预处理步骤不受支持。

图像和音频特征¶

如果您直接使用预处理器模块或使用 InferenceModule 模块的 forward 方法，则不支持从文件路径加载 image 和 audio 文件。相反，必须先将数据加载为批处理张量或张量列表，然后将其传递给模块。

如果您使用 InferenceModule 模块的 predict 方法，则会自动为您加载文件路径字符串。

日期特征¶

TorchScript 不实现 datetime 模块，这意味着无法从字符串解析 date 特征。

如果您直接使用预处理器模块或使用 InferenceModule 模块的 forward 方法，则必须传入表示日期的整数向量。给定一个 datetime_obj，可以使用以下代码生成向量

def create_vector_from_datetime_obj(datetime_obj):
    yearday = datetime_obj.toordinal() - date(datetime_obj.year, 1, 1).toordinal() + 1

    midnight = datetime_obj.replace(hour=0, minute=0, second=0, microsecond=0)
    second_of_day = (datetime_obj - midnight).seconds

    return [
        datetime_obj.year,
        datetime_obj.month,
        datetime_obj.day,
        datetime_obj.weekday(),
        yearday,
        datetime_obj.hour,
        datetime_obj.minute,
        datetime_obj.second,
        second_of_day,
    ]

为了方便起见，此函数也可在 ludwig.utils.date_utils 模块中找到。

如果您使用 InferenceModule 模块的 predict 方法，则会自动为您提取日期字符串的特征。

GPU 支持¶

作为字符串输入的特征只能在 CPU 上进行预处理。在 Ludwig 中，这些是以下特征

二进制
类别
集合
序列
文本
向量
包
时间序列

如果您直接使用预处理器模块或使用 InferenceModule 模块的 forward 方法，则用户可以将 binary、vector 和 time series 特征作为张量传入，以便在 GPU 上对其进行预处理。

如果您使用 InferenceModule 模块的 predict 方法，则上述所有特征将首先被转换为字符串，然后在 CPU 上进行预处理。

NaN 处理¶

对于大多数特征，NaN 由预处理器以与原始 Ludwig 模型相同的方式处理。例外情况是以下特征

图像
音频
日期
向量

HuggingFace 模型¶

HuggingFace 模型尚不支持 TorchScript 导出，但我们正在努力！

Carton 导出¶

Carton 是一个库，它允许用户从多种编程语言（包括 C、C++、Rust 等）高效地运行机器学习模型。

一部分 Ludwig 模型可以导出到 Carton。除了模型本身，预处理和后处理步骤也包含在导出的模型中，确保模型可以直接用于生产环境中的推理。

要开始使用，只需运行 export_carton 命令

ludwig export_carton -m=results/experiment_run/model

这将生成一个文件，Carton 可以从任何支持的编程语言加载该文件。

例如，在 Python 中，您可以按如下方式加载和运行模型

import cartonml as carton

async def main():
    model = await carton.load("/path/to/model.carton")
    output = await model.infer({
        "x": np.zeros(5)
    })

有关从其他编程语言使用的信息，请参阅 Carton 快速入门指南。