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

使用自定义Python环境

预置Flink镜像已集成PyFlink运行环境,默认场景下提交Flink Python作业无需额外配置。但在以下两类场景下,需为作业准备自定义Python环境:

  • 作业依赖的第三方库不在内置清单中。
  • 需要固定或更换Python运行时的版本。

准备方式有两种,Flink Python作业、Flink JAR作业与Flink SQL作业都适用,区别只在请求字段的位置:

  • 随作业投递虚拟环境:把虚拟环境打成zip,通过python_archives投递,解释器指向归档内的解释器。影响范围限于单个作业。
  • 制作自定义镜像:在预置镜像基础上安装依赖,注册后在端点或作业上使用。影响范围是端点或复用该镜像的多个作业。

方式一:随作业投递虚拟环境

  1. 制作虚拟环境包

    制作时遵守以下约束:

    • Python版本与作业镜像的运行时一致,当前为Python 3.9。
    • 在与作业镜像一致的容器内制作。
    • 归档顶层目录名是venv;打包前删除venv内的JAR文件。
    • 先自检导入,再打包。
    # 在作业镜像内执行
    /usr/bin/python3.9 -m venv venv
    venv/bin/python -m pip install --no-cache-dir \
      apache-flink==1.20.0 pandas pyarrow numpy pytz scikit-learn "setuptools<81"
    venv/bin/python -c 'import sklearn, pandas, numpy; print(sklearn.__version__)'
    # 在 venv 的父目录打包,顶层目录名必须是 venv
    zip -qr venv.zip venv

    上传前用unzip -l venv.zip | head -3确认顶层是venv/。

    需要编译的C扩展建议在与预置镜像glibc兼容的manylinux容器内编译。

  2. 在请求中引用

    三种作业的字段位置不同,解释器配置相同:使用归档运行时必须同时覆盖下面两个配置项,取值一致。

    {
      "python.executable": "venv.zip/venv/bin/python",
      "python.client.executable": "venv.zip/venv/bin/python"
    }
    • Flink Python作业

      虚拟环境归档放在job_config.python_archives。作业的代码依赖仍放在python_libraries,两者的区别是归档提供运行时、python_libraries提供需要import的代码。

      {
        "job_config": {
          "type": "FLINK_PYTHON_JOB",
          "python_job_file": "obs://my-flink-bucket/path/py/word_count.py",
          "python_libraries": [ "obs://my-flink-bucket/path/py/my_udf.py" ],
          "python_archives": [ "obs://my-flink-bucket/path/py/venv.zip" ]
        },
        "flink_config": {
          "python.executable": "venv.zip/venv/bin/python",
          "python.client.executable": "venv.zip/venv/bin/python"
        }
      }
    • Flink JAR作业与Flink SQL作业

      虚拟环境归档放在job_config.python_parameter.python_archives,UDF模块放在job_config.python_parameter.python_libraries。

      {
        "job_config": {
          "type": "FLINK_JAR_JOB",
          "main_jar": "obs://my-flink-bucket/path/to/flink-ai-function.jar",
          "main_class": "PyFlinkAiFunctionJob",
          "python_parameter": {
            "python_libraries": [ "obs://my-flink-bucket/path/to/my_ml_udf.py" ],
            "python_archives": [ "obs://my-flink-bucket/path/to/venv.zip" ]
          }
        },
        "flink_config": {
          "python.executable": "venv.zip/venv/bin/python",
          "python.client.executable": "venv.zip/venv/bin/python"
        }
      }

方式二:制作自定义镜像并在端点上使用该镜像

在预置镜像基础上安装依赖,构建并推送镜像,注册到平台后,在创建端点时选择该镜像,或在作业的image_config中指定。镜像与端点绑定后,该端点上的Flink Python、JAR、SQL作业都使用镜像内的运行时。制作、注册与选择镜像的完整步骤请参见自定义镜像。

镜像内Python运行时的位置决定作业是否需要配置解释器:

表1 解释器说明

镜像内Python运行时

作业侧flink_config配置

说明

/opt/venv(预置镜像自带,自定义镜像在其上安装依赖)

不配置python.executable与python.client.executable

平台默认使用/opt/venv/bin/python。

/opt/venv以外的路径,例如/opt/py39-extra

两个键均填该路径的绝对路径,取值一致

不配置时作业仍使用/opt/venv/bin/python,镜像内新增的运行时不会生效。

不使用镜像运行时,通过python_archives随作业投递

两个键均填<归档名>.zip/venv/bin/python

相对路径写法,见方式一:随作业投递虚拟环境。解释器指向归档时必须用相对路径,不能用绝对路径。

python.executable作用于Python UDF Worker,python.client.executable作用于客户端。两个键只配一个时,两侧会使用不同的解释器,常见表现为编译UDF时报ModuleNotFoundError,或作业提交后UDF加载失败。

  • 示例一:在/opt/venv上补充第三方库,作业使用默认解释器
    • Dockerfile:
      # 1.基础镜像必须是预置Flink镜像,预置镜像已内置/opt/venv运行时
      FROM <预置Flink镜像SWR地址>
      
      # 2.pip源按构建机可访问的源替换,内网HTTP源需要--trusted-host
      ARG PIP_INDEX_URL=<pip源地址>
      ARG PIP_TRUSTED_HOST=<pip源的主机名>
      
      USER root
      
      # 3.在预置运行时上安装镜像未内置的第三方包
      RUN /opt/venv/bin/python -m pip install --no-cache-dir \
            --index-url "${PIP_INDEX_URL}" --trusted-host "${PIP_TRUSTED_HOST}" \
            scikit-learn==1.3.2
      
      # 4.构建期自检,导入失败则构建失败
      RUN /opt/venv/bin/python -c "import sklearn; print(sklearn.__version__)"
      
      # 5.恢复镜像默认运行用户
      USER omm
    • 作业请求:
      {
        "name": "sql-udf-custom-image",
        "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",
          "python_parameter": {
            "python_libraries": [
              "obs://my-flink-bucket/path/to/my_udf.py"
            ]
          }
        }
      }

      请求中没有配置python.executable与python.client.executable,作业使用镜像内/opt/venv/bin/python。示例省略了image_config,端点已绑定该镜像;也可以只对单个作业指定镜像,在请求体中传入image_config的image_id与image_version_id。

  • 示例二:镜像内运行时位于其他路径,作业显式指定解释器
    • Dockerfile:
      FROM <预置Flink镜像SWR地址>
      
      ARG PIP_INDEX_URL=<pip源地址>
      ARG PIP_TRUSTED_HOST=<pip源的主机名>
      
      USER root
      
      # 1.在/opt/venv以外新建运行时,路径示例为/opt/py39-extra
      RUN /usr/bin/python3.9 -m venv /opt/py39-extra \
       && /opt/py39-extra/bin/python -m pip install --no-cache-dir \
            --index-url "${PIP_INDEX_URL}" --trusted-host "${PIP_TRUSTED_HOST}" \
            apache-flink==1.20.0 scikit-learn==1.3.2
      
      # 2.自检,PyFlink与新增依赖都能导入
      RUN /opt/py39-extra/bin/python -c "import pyflink, sklearn; print(pyflink.__version__)"
      
      USER omm
    • 作业请求:
      {
        "name": "jar-udf-custom-runtime",
        "endpoint_name": "flink-endpoint-test",
        "job_agency": "test-agencys",
        "execution_mode": "STREAMING",
        "flink_config": {
          "python.executable": "/opt/py39-extra/bin/python",
          "python.client.executable": "/opt/py39-extra/bin/python"
        },
        "job_config": {
          "type": "FLINK_JAR_JOB",
          "main_jar": "obs://my-flink-bucket/path/to/flink-ai-function.jar",
          "main_class": "PyFlinkAiFunctionJob",
          "python_parameter": {
            "python_libraries": [
              "obs://my-flink-bucket/path/to/my_ml_udf.py"
            ]
          }
        }
      }

  • 解释器取值为容器内绝对路径。不要填写OBS路径,也不要填写归档相对路径(<归档名>.zip/venv/bin/python)。
  • 镜像内容变更后,需更换tag重新推送并注册;端点重新选择镜像版本后,再提交作业。
  • 预置镜像已内置的包不需要重复安装,清单见预置镜像内置Python包清单(Flink)。

相关文档