Apache Beam Python SDK Dataflow无法加载extra_package指定的私有依赖模块

问题 #

使用Apache Beam Python SDK创建批处理Dataflow管道时，引入私有依赖包uplight-telemetry，通过extra_package参数指定了本地的tar包路径，但管道加载失败，报错No module named 'uplight_telemetry'。创建pipeline_options的代码如下：

def __create_pipeline_options_dataflow(job_name):
    # Set up the Dataflow runner options
    gcp_project_id = os.environ.get(GCP_PROJECT_ID)
    current_dir = os.path.dirname(os.path.abspath(__file__))
    print("current_dir=", current_dir)
    setup_file_path = os.path.join(current_dir, '..', '..', 'setup.py')
    print("Set-up file path=", setup_file_path)
    #TODO:Move file to proper location
    uplight_telemetry_tar_file_path=os.path.join(current_dir, '..', '..','..','non-public-dependencies', 'uplight-telemetry-1.0.0.tar.gz')
    # TODO:Move to environmental variables
    pipeline_options = {
        'project': gcp_project_id,
        'region': "us-east1",
        'job_name': job_name,  # Provide a unique job name
        'temp_location': f'gs://{TAS_GCS_BUCKET_NAME_PREFIX}{os.getenv("UP_PLATFORM_ENV")}/temp',
        'staging_location': f'gs://{TAS_GCS_BUCKET_NAME_PREFIX}{os.getenv("UP_PLATFORM_ENV")}/staging',
        'runner': 'DataflowRunner',
        'save_main_session': True,
        'service_account_email': os.environ.get(SERVICE_ACCOUNT),
        # 'network': f'projects/{gcp_project_id}/global/networks/default',
        'subnetwork': os.environ.get(SUBNETWORK_URL),
        'setup_file': setup_file_path,
        'extra_package': uplight_telemetry_tar_file_path
        # 'template_location': 'gcr.io/dataflow-templates-base/python310-template-launcher-base'
    }
    print("Pipeline created for job-name", job_name)
    logger.debug(f"pipeline_options created as {pipeline_options}")
    return pipeline_options

请问为何Dataflow没有尝试从extra_package安装该依赖包？

可能的原因及解决方法 #

1. extra_package参数格式错误 #

Apache Beam的Dataflow配置中，extra_package要求接收列表类型的值，而非单个字符串。当前传入单个路径字符串，Dataflow无法正确识别该参数，导致依赖被忽略。

修改代码，将参数改为列表格式：

'extra_package': [uplight_telemetry_tar_file_path]

2. setup.py的优先级干扰 #

同时指定setup_file和extra_package时，若setup.py的配置存在冲突，会覆盖extra_package的依赖加载逻辑：

• 若setup.py的install_requires已声明uplight-telemetry，但该包是私有源，Dataflow无法从公共PyPI拉取，需确保extra_package的tar包被正确上传至staging目录；
• 若setup.py的package_data或include_package_data配置不当，会干扰额外依赖的安装流程。

3. 本地tar包路径无效 #

当前使用相对路径计算tar包位置，若路径层级计算错误，会导致Dataflow客户端找不到本地文件，无法上传至staging目录。

验证路径有效性：

print("uplight_telemetry_tar_file_path=", uplight_telemetry_tar_file_path)
print("File exists:", os.path.exists(uplight_telemetry_tar_file_path))

若文件不存在，修正路径计算逻辑，确保指向正确的tar包位置。

4. 包名称与导入名称不匹配 #

报错提示No module named 'uplight_telemetry'，需确认tar包内的实际模块名称是否与导入名一致（注意短横线与下划线的区别）。部分包的PyPI名称用短横线（如uplight-telemetry），但内部模块名用下划线，反之亦然。

检查方法：解压uplight-telemetry-1.0.0.tar.gz，查看内部模块目录名称，确保与代码中的导入名完全匹配。

内容的提问来源于stack exchange，提问作者Sumit Desai