本文介绍如何开发 Python 自定义模型,并在 SQL 作业中完成模型注册和推理调用。
前提条件
开始前,请确认已完成以下准备:
已开通实时计算 Flink 版工作空间。具体操作,请参见开通实时计算Flink版。
实时计算引擎 VVR 11.9 及以上版本预装了 Python 3.9、3.10 和 3.11,建议您选择其中之一作为本地开发环境的 Python 版本。
本地环境搭建
创建工作目录。
mkdir custom-model-quickstart cd custom-model-quickstart(可选)本地开发环境配置:由于 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",
) 部署文件上传
自定义模型开发完成后,您需要将模型相关文件注册到平台:
登录实时计算控制台,进入目标工作空间。
在左侧导航栏选择 ,上传
custom_model.py。在左侧导航栏选择 ,上传
linear-weight.txt。
上传文件成功后,您可以参考文件管理查看 oss 侧地址。
编写 SQL 作业
登录实时计算控制台,进入目标工作空间。
创建 SQL 作业草稿,选择 VVR 11.9 及以上版本。
在 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设置批次缓冲的最大等待时间。
启动作业
在页面的下拉列表中,选择流作业或批作业。
在目标作业名称右侧,单击操作列下的启动。
在右侧弹出的窗口中,单击启动。
验证结果
该作业使用Print连接器将结果打印到Task Manager日志。作业结束后,您可以查看日志验证结果:
在页面的下拉列表中,选择流作业或批作业。
单击目标作业的名称。
单击作业日志。
单击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 资源,请先联系售后工程师开通相关能力。