更新时间:2026-11-16 GMT+08:00
分享

使用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作业详情查看作业配置。日志从平台归档的容器日志中获取。

相关文档