自定义模型

更新时间:
复制 MD 格式

本文介绍如何开发 Python 自定义模型,并在 SQL 作业中完成模型注册和推理调用。

前提条件

开始前,请确认已完成以下准备:

  • 已开通实时计算 Flink 版工作空间。具体操作,请参见开通实时计算Flink版。

  • 实时计算引擎 VVR 11.9 及以上版本预装了 Python 3.9、3.10 和 3.11,建议您选择其中之一作为本地开发环境的 Python 版本。

本地环境搭建

  1. 创建工作目录。

    mkdir custom-model-quickstart
    cd custom-model-quickstart
  2. (可选)本地开发环境配置:由于 Flink Python API 为 VVR 11.9 及以上的专属功能,暂未在开源版 Flink 中提供,因此您需要使用下面的命令安装 VVR 版 PyFlink 依赖包:

    pip install "pyarrow>=5.0.0" "ververica-flink==11.9.0"
    说明
    • ververica-flink是API-Only包,仅提供类型定义和接口声明,用于本地开发,作业仍需在实时计算Flink版平台提交。

    • 自定义模型强依赖 pyarrow,建议也安装对应版本的 pyarrow

开发自定义模型

本示例实现一个线性预测模型,计算公式为:

创建模型资源文件

在当前目录下创建 linear-weight.txt,写入以下内容。

5

创建模型实现文件

在当前目录下创建 custom_model.py 文件,并写入以下内容。

import os

from pyflink.table import DataTypes
from pyflink.table.udf import PredictFunction, udpf

class LinearPredictFunction(PredictFunction):
    def load_model(self, model_options, weight_path, device):
        """加载模型资源并初始化推理参数。

        框架在模型初始化阶段调用此方法。将加载后的模型或参数保存在
        self 中,供 predict() 复用,避免每个批次重复加载。

        Args:
            model_options (dict): CREATE MODEL 的 WITH 配置参数。
                本示例读取 factor,默认值为 10。
            weight_path (str | None): 框架解析后的本地模型资源路径,
                可以是文件或目录;未绑定模型资源时为 None。
            device: 框架选择的计算设备。
        """
        self.factor = int(model_options.get("factor", "10"))

        if weight_path is None:
            raise ValueError("请通过 model-path 配置模型资源")

        if os.path.isdir(weight_path):
            weight_path = os.path.join(weight_path, "linear-weight.txt")

        with open(weight_path, "r", encoding="utf-8") as weight_file:
            self.bias = int(weight_file.read().strip())

    def predict(self, batch):
        """对一个 Arrow 输入批次执行线性预测。

        每条记录按 value * factor + bias 计算,空值返回空值。

        Args:
            batch (pa.RecordBatch): 本次推理的输入数据批次。
                列顺序与 SQL DESCRIPTOR(...) 指定的顺序一致,
                类型与模型 INPUT 声明匹配。
                本示例读取第一列,类型为 BIGINT。

        Returns:
            pa.RecordBatch: 仅包含预测列 score 的数据批次,
                列类型为 pa.int64(),对应 SQL BIGINT。
                输出行数与输入一致,且保持逐行对应的顺序。
        """
        import pyarrow as pa
        values = batch.column(0).to_pylist()

        scores = [
            value * self.factor + self.bias
            for value in values
        ]

        return pa.RecordBatch.from_arrays(
            [pa.array(scores, type=pa.int64())],
            names=["score"],
        )

linear_predict = udpf(
    LinearPredictFunction(),
    input_types=[DataTypes.BIGINT()],
    result_type=DataTypes.ROW([
        DataTypes.FIELD("score", DataTypes.BIGINT()),
    ]).not_null(),
    name="linear_predict",
)   

部署文件上传

自定义模型开发完成后,您需要将模型相关文件注册到平台:

  1. 登录实时计算控制台,进入目标工作空间。

  2. 在左侧导航栏选择 文件管理,上传 custom_model.py。

  3. 在左侧导航栏选择 文件管理,上传 linear-weight.txt。

上传文件成功后,您可以参考文件管理查看 oss 侧地址。

编写 SQL 作业

  1. 登录实时计算控制台,进入目标工作空间。

  2. 创建 SQL 作业草稿,选择 VVR 11.9 及以上版本。

  3. 在 SQL 编辑器中写入以下内容,将 model-path 替换为模型资源的实际地址,即部署文件上传的 oss 地址。

    SET 'python.files' = '<custom_model.py 的资源地址>';
    
    CREATE TEMPORARY MODEL linear_model
    INPUT (`value` BIGINT)
    OUTPUT (score BIGINT)
    WITH (
        'model-path' = '<linear-weight.txt 的资源地址>',
        'factor' = '10'
    )
    AS 'custom_model.linear_predict'
    LANGUAGE PYTHON;
    
    CREATE TEMPORARY VIEW source_t AS
    SELECT *
    FROM (
        VALUES
            (CAST(1 AS BIGINT)),
            (CAST(2 AS BIGINT)),
            (CAST(3 AS BIGINT))
    ) AS T(id);
    
    CREATE TEMPORARY TABLE result_t (
        id BIGINT,
        score BIGINT
    ) WITH (
        'connector' = 'print',
        'logger' = 'true'
    );
    
    INSERT INTO result_t
    SELECT id, score
    FROM ML_PREDICT(
        TABLE source_t,
        MODEL linear_model,
        DESCRIPTOR(id),
        MAP[
            'bundle-size', '2',
            'bundle-allow-latency', '1s'
        ]
    );
    说明
    • AS 'custom_model.linear_predict' 指向 Python 模块中通过 udpf 导出的对象。

    • INPUT 和 OUTPUT 应与 Python 中声明的输入输出类型一致。

    • DESCRIPTOR(id) 指定传入模型的输入列。

    • bundle-size 设置推理批次的最大记录数,bundle-allow-latency 设置批次缓冲的最大等待时间。

启动作业

  1. 在运维中心 > 作业运维页面的下拉列表中,选择流作业或批作业。

  2. 在目标作业名称右侧,单击操作列下的启动。

  3. 在右侧弹出的窗口中,单击启动。

验证结果

该作业使用Print连接器将结果打印到Task Manager日志。作业结束后,您可以查看日志验证结果:

  1. 在运维中心 > 作业运维页面的下拉列表中,选择流作业或批作业。

  2. 单击目标作业的名称。

  3. 单击作业日志。

  4. 单击Task Managers页签,在当前 TaskManager下拉列表中,选择 task manager。

日志中包含以下数据时,表示作业已经运行成功:

+I[1, 15]
+I[2, 25]
+I[3, 35]

进阶用法

批量执行

支持将多条输入记录组成一个批次,再调用 predict() 执行推理,减少调用开销,提升模型处理吞吐。可以通过 ML_PREDICT 的参数配置批次大小和最大等待时间:

SELECT *
FROM ML_PREDICT(
    TABLE source_t,
    MODEL linear_model,
    DESCRIPTOR(id),
    MAP[
        'bundle-size', '32',
        'bundle-allow-latency', '1s'
    ]
);
  • bundle-size:每批最多缓冲的记录数。

  • bundle-allow-latency:攒批的最大等待时间。

达到批次大小或等待时间后,框架触发推理,因此实际批次可能小于配置值。可根据模型吞吐、内存占用和延迟要求调整参数。

基于 Arrow 的数据传输

Flink 与 Python 模型之间使用 Apache Arrow 进行批量数据传输。Arrow 采用列式数据格式,有助于减少逐条传输和转换的开销,适合批量推理场景。

predict() 接收 pyarrow.RecordBatch,可以直接获取输入列并进行批量计算:

def predict(self, batch):
    import pyarrow as pa
    import pyarrow.compute as pc
    values = batch.column(0)
    # 执行批量推理,并返回 Arrow 格式的预测结果。
    scores = pc.add(values, pa.scalar(1, type=pa.int64()))

    return pa.RecordBatch.from_arrays(
        [scores],
        names=["score"],
    )

输出支持 pyarrow.RecordBatch,或由 Arrow 数组组成的列序列。输出行数应与输入一致,并保持逐行对应关系。

权重管理

支持通过 CREATE MODEL 的 model-path 参数指定模型资源,由框架准备本地资源路径,再传入 load_model()。

支持以下资源形式:

  • 本地文件或目录:直接使用对应路径。

  • 远程文件或目录:复制到本地后使用,需具备相应文件系统支持和访问权限。

  • 压缩包:支持 zip、tar、tar.gz 和 tgz,解压后提供本地路径。

GPU 调用

在 CREATE MODEL 的 WITH 参数中,可以指定执行的GPU设备以及数量:

WITH (
    'model-path' = '<模型资源地址>',
    'gpu-type' = 'A10',
    'gpu-number' = '1'
)
  • gpu-type:请求的 GPU 类型,需与集群提供的资源类型一致。

  • gpu-number:请求的 GPU 数量,需同时配置 gpu-type。

在模型实现中,可通过 device 指定推理设备,并将模型与输入数据迁移到该设备上执行推理。例如,使用 PyTorch 时可调用 model.to(device) 和 input_tensor.to(device)。注意,device参数仅在load_model调用中传入,请将该值保存为实例属性。

说明

若您想使用 GPU 资源,请先联系售后工程师开通相关能力。