使用自定义Python环境
预置Flink镜像已集成PyFlink运行环境,默认场景下提交Flink Python作业无需额外配置。但在以下两类场景下,需为作业准备自定义Python环境:
- 作业依赖的第三方库不在内置清单中。
- 需要固定或更换Python运行时的版本。
准备方式有两种,Flink Python作业、Flink JAR作业与Flink SQL作业都适用,区别只在请求字段的位置:
- 随作业投递虚拟环境:把虚拟环境打成zip,通过python_archives投递,解释器指向归档内的解释器。影响范围限于单个作业。
- 制作自定义镜像:在预置镜像基础上安装依赖,注册后在端点或作业上使用。影响范围是端点或复用该镜像的多个作业。
方式一:随作业投递虚拟环境
- 制作虚拟环境包
制作时遵守以下约束:
- 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容器内编译。
- 在请求中引用
三种作业的字段位置不同,解释器配置相同:使用归档运行时必须同时覆盖下面两个配置项,取值一致。
{ "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" } }
- Flink Python作业
方式二:制作自定义镜像并在端点上使用该镜像
在预置镜像基础上安装依赖,构建并推送镜像,注册到平台后,在创建端点时选择该镜像,或在作业的image_config中指定。镜像与端点绑定后,该端点上的Flink Python、JAR、SQL作业都使用镜像内的运行时。制作、注册与选择镜像的完整步骤请参见自定义镜像。
镜像内Python运行时的位置决定作业是否需要配置解释器:
| 镜像内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:
- 示例二:镜像内运行时位于其他路径,作业显式指定解释器
- 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" ] } } }
- Dockerfile:
- 解释器取值为容器内绝对路径。不要填写OBS路径,也不要填写归档相对路径(<归档名>.zip/venv/bin/python)。
- 镜像内容变更后,需更换tag重新推送并注册;端点重新选择镜像版本后,再提交作业。
- 预置镜像已内置的包不需要重复安装,清单见预置镜像内置Python包清单(Flink)。