# 使用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环境](https://support.huaweicloud.com/usermanual-aidatalake/aidatalake_01_0159.html)。
  
- 已创建Flink端点且状态为运行中**，**并在端点上选择镜像，或在作业的image_config中指定。
- 已上传下列文件到OBS：Python UDF模块、离线模型或其他数据文件、需要额外补充的第三方库虚拟环境包、SQL脚本或JAR包。
- 已获取工作空间ID、端点名称，并已创建用于作业访问OBS的用户自定义委托。Python UDF场景中，作业需通过该委托读取OBS上的UDF模块与模型文件；系统管理委托不可用于提交作业。提交作业时，在job_agency参数中填写该委托名称；不指定时默认使用端点作业委托。委托的创建方法请参见[创建自定义委托](https://support.huaweicloud.com/usermanual-aidatalake/aidatalake_01_0078.html)。
 
#### 确定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\>/...。
上传操作详情请参见[上传对象](https://support.huaweicloud.com/qs-obs/obs_qs_0001.html#section3)。
![](https://support.huaweicloud.com/usermanual-aidatalake/public_sys-resources/caution_3.0-zh-cn.png)
上传的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时使用同一套依赖环境。         |
     
  ![](https://support.huaweicloud.com/usermanual-aidatalake/public_sys-resources/note_3.0-zh-cn.png)
  - 只投递文件不等于模块可见。把.py放进dependency_files或dependency_jars，文件会下载到/opt/flink/usrlib/，但引擎不知道该文件是Python模块，作业仍会报Cannot instantiate user-defined function。
  
  - 镜像内置包直接可用，清单详见[预置镜像内置Python包清单（Flink）](https://support.huaweicloud.com/usermanual-aidatalake/aidatalake_01_0162.html)。只有镜像未内置的库才需要python_archives；一旦使用归档内的解释器，两个解释器配置项都要指向归档路径。
  
  - 提交时校验会拦截不合规的依赖条目：非obs://开头、单个路径超过512字符、条目数超过100个，均返回400。
    
#### 步骤四：查看状态与排障
作业提交为异步接口，用[查询Flink作业状态](https://support.huaweicloud.com/api-aidatalake/ShowFlinkJobState.html)查询终态，用[查看Flink作业详情](https://support.huaweicloud.com/api-aidatalake/ShowFlinkJob.html)查看作业配置。日志从平台归档的容器日志中获取。
