使用Python UDF
概述
AI DataLake的Flink引擎支持在Flink JAR作业和Flink SQL作业中加载并使用Python依赖与离线模型,通过Python UDF在作业中调用,实现实时推理、个性化计算等业务逻辑。
- Flink SQL作业:通过CREATE FUNCTION ... LANGUAGE PYTHON在SQL脚本中注册UDF。
- Flink JAR作业:由客户JAR代码自行使用Table API或SQL注册UDF。
JAR、SQL作业的job_config中均支持配置python_parameter子对象,包含python_libraries与python_archives两个字段,分别用于投递Python代码与虚拟环境归档。
前提条件
- 使用预置镜像即可。预置镜像中已内置PyFlink运行时及常用Python包,使用Python UDF时无需单独制作镜像。如果作业需要额外使用镜像未内置的第三方库,可通过以下两种方式准备:
- 将虚拟环境打成归档随作业投递(配合python_archives使用)。
- 预置进自定义镜像。
具体制作步骤、解释器配置与选择建议,请参见使用自定义Python环境。
- 已创建Flink端点且状态为运行中,并在端点上选择镜像,或在作业的image_config中指定。
- 已上传下列文件到OBS:Python UDF模块、离线模型或其他数据文件、需要额外补充的第三方库虚拟环境包、SQL脚本或JAR包。
- 已获取工作空间ID、端点名称,并已创建用于作业访问OBS的用户自定义委托。Python UDF场景中,作业需通过该委托读取OBS上的UDF模块与模型文件;系统管理委托不可用于提交作业。提交作业时,在job_agency参数中填写该委托名称;不指定时默认使用端点作业委托。委托的创建方法请参见创建自定义委托。
确定Python依赖的投递字段
- 投递字段及机制
提交作业前,需要根据文件类型确定其投递字段。作业支持三个投递字段,机制如下:
表1 投递字段及机制 字段
机制
python_libraries
投递Python代码。支持单文件.py、代码包.zip、.whl、.egg。所列文件会加入作业客户端与Python UDF Worker两侧的PYTHONPATH:.py加入其所在目录,.zip解压后加入解压根目录,.whl与.egg加入文件路径本身。
python_archives
投递Python虚拟环境归档。提交后解压到Python UDF Worker工作目录下的python-archives/<归档名>/,作业按<归档名>/...的相对路径访问。
使用归档内的解释器时,python.executable与python.client.executable均指向<归档名>.zip/venv/bin/python。
dependency_files
投递数据文件。文件落到/opt/flink/usrlib/<文件名>,供代码按绝对路径读取。
- 文件与字段的对应关系
表2 文件与字段的对应关系 要交付的内容
投递字段
程序中的使用方式
UDF单文件.py
python_libraries
SQL里写AS '文件名去后缀.函数名'
UDF代码包.zip(包内是扁平模块)
python_libraries
按扁平模块名导入
UDF代码包.zip(包内含包目录)
python_libraries
按包层级导入,如AS 'mypkg.udf.predict'
第三方wheel、egg
python_libraries
直接import
模型、数据文件
dependency_files
按绝对路径读/opt/flink/usrlib/<文件名>
镜像未内置的第三方库(虚拟环境包)
python_archives
解释器写<存档名>.zip/venv/bin/python
步骤一:准备Python UDF模块与作业文件
- SQL内注册Python UDF
新建my_udf.py,按绝对路径读取模型:
import logging import pickle from pyflink.table import DataTypes from pyflink.table.udf import udf MODEL_PATH = "/opt/flink/usrlib/model.pkl" logging.basicConfig(level=logging.INFO) @udf(result_type=DataTypes.INT()) def predict(features_str): try: with open(MODEL_PATH, "rb") as fh: bundle = pickle.load(fh) values = [float(v) for v in str(features_str).split(",") if v.strip() != ""] score = int(bundle["model"].predict([values])[0]) logging.info("UDF_OK features=%s score=%s", values, score) return score except Exception as exc: logging.error("UDF_FAILED err=%s: %s", type(exc).__name__, exc) return -1新建my_udf.sql,注册并调用该函数:
CREATE TEMPORARY FUNCTION py_predict AS 'my_udf.predict' LANGUAGE PYTHON; CREATE TABLE my_sink ( features STRING, score INT ) WITH ('connector' = 'print'); INSERT INTO my_sink SELECT features, py_predict(features) FROM (VALUES ('0.0'), ('3.0'), ('5.0')) AS my_src(features); - JAR内注册Python UDF
JAR作业需要准备两类文件,缺一不可:
表3 文件投递方式 文件
内容
投递方式
客户JAR包
在Java代码使用Table API或SQL注册Python UDF
通过main_jar指定JAR在OBS的路径。
Python UDF模块
Python代码,包含被JAR注册的函数(函数用@udf装饰)
以下两种放置方式任选其一。
客户JAR包在请求中通过main_jar、main_class、main_args指定JAR包与主类。Python UDF模块的放置方式如下:
表4 放置方式说明 放置方式
说明
上传到OBS(.py / .zip)
随作业通过python_libraries投递,模块在作业运行时可被加载。
预置进自定义镜像
构建镜像时把模块放入Python运行时site-packages目录,作业运行时直接从镜像加载,无需投递文件(函数仍须用@udf装饰)。
步骤二:上传文件到OBS
把UDF模块、SQL脚本或JAR、模型文件、虚拟环境包上传到OBS桶,记录各自的OBS全路径。请求里引用的路径统一写成obs://<bucket>/<prefix>/...。
上传操作详情请参见上传对象。
上传的OBS桶须与工作空间所在区域一致,且作业委托需具备该桶的读取权限(委托的创建方法见前提条件)。
步骤三:提交作业
- 请求体结构
提交作业的请求体按职责分为几个层次,Python UDF相关的配置集中在job_config.python_parameter与flink_config中。整体结构如下:
POST /v2/workspaces/{workspace_id}/flink-jobs { "name": 作业名称 "endpoint_name": 提交到的Flink端点 "job_agency": 作业委托名称(代理读取OBS) "execution_mode": 执行模式(STREAMING/BATCH) "job_config": { 作业配置(按作业类型取用不同字段) "type": 作业类型:FLINK_JAR_JOB / FLINK_SQL_JOB ├─ JAR作业用 → │ "main_jar": 主JAR包的OBS路径 │ "main_class": 主类(注册Python UDF的入口) │ "main_args": 主函数参数 ├─ SQL作业用 → │ "sql_script_file": SQL脚本的OBS路径 └─ 两者共同 → "dependency_files": 数据文件OBS路径列表 → 下载并放置到/opt/flink/usrlib/ "python_parameter": Python UDF依赖 "python_libraries": Python代码OBS路径列表 → 加入PYTHONPATH "python_archives": 虚拟环境归档OBS路径列表 → 解压到Python UDF Worker工作目录 }, "flink_config": { Flink原生配置(可选) "python.executable": Python UDF Worker使用的解释器 "python.client.executable": 客户端(提交作业、编译UDF)使用的解释器 }, "resource_config": { 资源规格 "parallelism": ... "jobmanager_resource_spec": ... "taskmanager_resource_spec": ... } }配置要点
- 使用Python UDF时,须通过job_config.python_parameter声明Python依赖。
- python.executable用于Python UDF Worker执行UDF,python.client.executable用于客户端提交作业、编译UDF。使用镜像内置运行时(/opt/venv)时两个键可省略;改用其他运行时(归档内的解释器,或自定义镜像中/opt/venv以外的解释器)时,两个键须成对配置且取值一致。指向归档时写相对路径(<归档名>.zip/venv/bin/python),指向镜像时写容器内绝对路径,两种写法不可混用。
- python_libraries / python_archives列表最多100个,单个路径1~512个字符且以obs://开头。
- 示例一:JAR作业内注册Python UDF(使用镜像内置运行时)
POST /v2/workspaces/{workspace_id}/flink-jobs { "name": "test-jar-python-udf", "endpoint_name": "flink-endpoint-test", "job_agency": "test-agencys", "execution_mode": "STREAMING", "job_config": { "type": "FLINK_JAR_JOB", "main_jar": "obs://my-flink-bucket/path/to/flink-python-udf.jar", "main_class": "PyFlinkUdfJob", "main_args": [ "--x", "1" ], "dependency_files": [ "obs://my-flink-bucket/path/to/model.pkl" ], "python_parameter": { "python_libraries": [ "obs://my-flink-bucket/path/to/ml_udf.py" ] } }, "resource_config": { "parallelism": 1, "jobmanager_resource_spec": { "cpu": 1000, "memory": 4096 }, "taskmanager_resource_spec": { "cpu": 1000, "memory": 4096 } } }该示例各字段的使用方式:
表5 各字段的使用方式 字段
示例值
作用
name
test-jar-python-udf
作业名称
endpoint_name
flink-endpoint-test
指定提交到哪个Flink端点。
job_agency
test-agencys
作业委托,代理作业读取OBS上的模型与模块。
execution_mode
STREAMING
流式执行。
job_config.type
FLINK_JAR_JOB
声明这是JAR作业,引擎按此解析下方JAR专属字段。
main_jar
obs://.../flink-python-udf.jar
作业JAR包的OBS路径。
main_class
PyFlinkUdfJob
JAR内的主类,是代码里注册Python UDF的入口。
main_args
["--x", "1"]
传给主函数的参数。
dependency_files
obs://.../model.pkl
数据文件:模型。引擎把它放到/opt/flink/usrlib/model.pkl,UDF代码按该绝对路径读取。
python_parameter.python_libraries
obs://.../ml_udf.py
Python代码:UDF模块。引擎把它加入PYTHONPATH,作业客户端与Python UDF Worker两侧才能import到。
resource_config
parallelism=1等
作业并行度及JobManager/TaskManager资源规格。
- 示例二:SQL作业内注册Python UDF(使用镜像内置运行时)
{ "name": "test-sql-python-udf", "endpoint_name": "flink-endpoint-test", "job_agency": "test-agencys", "execution_mode": "STREAMING", "job_config": { "type": "FLINK_SQL_JOB", "sql_script_file": "obs://my-flink-bucket/path/to/my_udf.sql", "dependency_files": [ "obs://my-flink-bucket/path/to/model.pkl" ], "python_parameter": { "python_libraries": [ "obs://my-flink-bucket/path/to/my_udf.py" ] } }, "resource_config": { "parallelism": 1, "jobmanager_resource_spec": { "cpu": 1000, "memory": 4096 }, "taskmanager_resource_spec": { "cpu": 1000, "memory": 4096 } } }该示例各字段的使用方式:
表6 字段使用方式 字段
示例值
作用
job_config.type
FLINK_SQL_JOB
声明这是SQL作业,引擎按此解析SQL脚本。
sql_script_file
obs://.../my_udf.sql
SQL脚本的OBS路径。脚本内含CREATE TEMPORARY FUNCTION ... LANGUAGE PYTHON完成UDF注册,并执行INSERT语句调用。
dependency_files
obs://.../model.pkl
同示例一:投递模型到/opt/flink/usrlib/,供UDF按绝对路径读取。
python_parameter.python_libraries
obs://.../my_udf.py
同示例一:投递UDF模块,SQL脚本中AS 'my_udf.predict'才能命中该模块。
- 示例三:使用归档携带第三方库
在示例一或示例二的基础上,当作业需要镜像未内置的第三方库,且选择"虚拟环境归档随作业投递"方式时(准备工作见前提条件),在请求中补充python_archives,并让两个解释器指向归档内的Python:
{ "flink_config": { "python.executable": "venv.zip/venv/bin/python", "python.client.executable": "venv.zip/venv/bin/python" }, "job_config": { "python_parameter": { "python_libraries": [ "obs://my-flink-bucket/path/to/ml_udf.py" ], "python_archives": [ "obs://my-flink-bucket/path/to/venv.zip" ] } } }该示例各字段的使用方式:
字段
示例值
作用
python_parameter.python_archives
obs://.../venv.zip
虚拟环境归档的OBS路径。引擎将其解压到Worker工作目录,归档内的第三方库随解释器生效。
flink_config.python.executable
venv.zip/venv/bin/python
Worker侧解释器改为使用归档内的Python,使UDF能import归档中的第三方库。
flink_config.python.client.executable
venv.zip/venv/bin/python
客户端解释器同步指向归档内Python,编译和实例化UDF时使用同一套依赖环境。
- 只投递文件不等于模块可见。把.py放进dependency_files或dependency_jars,文件会下载到/opt/flink/usrlib/,但引擎不知道该文件是Python模块,作业仍会报Cannot instantiate user-defined function。
- 镜像内置包直接可用,清单详见预置镜像内置Python包清单(Flink)。只有镜像未内置的库才需要python_archives;一旦使用归档内的解释器,两个解释器配置项都要指向归档路径。
- 提交时校验会拦截不合规的依赖条目:非obs://开头、单个路径超过512字符、条目数超过100个,均返回400。
步骤四:查看状态与排障
作业提交为异步接口,用查询Flink作业状态查询终态,用查看Flink作业详情查看作业配置。日志从平台归档的容器日志中获取。