# 使用自定义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作业都使用镜像内的运行时。制作、注册与选择镜像的完整步骤请参见[自定义镜像](https://support.huaweicloud.com/usermanual-aidatalake/aidatalake_01_0059.html)。
镜像内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"
          ]
        }
      }
    }
    ```
    
    
   
![](https://support.huaweicloud.com/usermanual-aidatalake/public_sys-resources/note_3.0-zh-cn.png)
- 解释器取值为容器内绝对路径。不要填写OBS路径，也不要填写归档相对路径（\<归档名\>.zip/venv/bin/python）。
- 镜像内容变更后，需更换tag重新推送并注册；端点重新选择镜像版本后，再提交作业。
- 预置镜像已内置的包不需要重复安装，清单见[预置镜像内置Python包清单（Flink）](https://support.huaweicloud.com/usermanual-aidatalake/aidatalake_01_0162.html)。
 
