配置 Python 环境

Managed Service for Apache Spark 上的 PySpark 作业由集群上的 Python 解释器运行。作业代码在运行时必须与 Python 解释器版本和依赖项兼容。

检查解释器版本和模块

以下 check_python_env.py 示例程序检查运行作业的 Linux 用户、Python 解释器和可用模块。

import getpass
import importlib.util
import sys

print(f'This job is running as "{getpass.getuser()}".')
print(sys.executable, sys.version_info)
for package in sys.argv[1:]:
  print(importlib.util.find_spec(package))

运行程序：

REGION=region
gcloud dataproc jobs submit pyspark check_python_env.py \
    --cluster=my-cluster \
    --region=${REGION} \
    -- pandas scipy

示例输出： 

This job is running as "root".
/opt/conda/default/bin/python sys.version_info(major=3, minor=11, micro=8, releaselevel='final', serial=0)
ModuleSpec(name='pandas', loader=<_frozen_importlibexternal.SourceFileLoader object at 0x7f8b9c0a3d90>, origin='/opt/conda/default/lib/python3.11/site-packages/pandas/init_.py', submodule_search_locations=['/opt/conda/default/lib/python3.11/site-packages/pandas'])
ModuleSpec(name='scipy', loader=<_frozen_importlibexternal.SourceFileLoader object at 0x7f8b9c0a3e50>, origin='/opt/conda/default/lib/python3.11/site-packages/scipy/init_.py', submodule_search_locations=['/opt/conda/default/lib/python3.11/site-packages/scipy'])

Managed Service for Apache Spark 映像 Python 环境

以下部分介绍了受支持的 Managed Service for Apache Spark 映像版本集群的 Python 环境。

Managed Service for Apache Spark 映像版本 2.x

Conda（或 2.3 版映像中的 micromamba）已安装在 Managed Service for Apache Spark 2.x 集群上。默认的 Python 3 解释器位于虚拟机实例上的 /opt/conda/default/bin 下。以下页面列出了受支持的 Managed Service for Apache Spark 2.x 映像版本中包含的 Python 版本：

操作系统中的非默认 Python 解释器位于 /usr/bin/ 下。

您可以在 base 环境中安装 conda 和 pip 软件包，也可以使用与 conda 相关的集群属性在集群上设置您自己的 conda 环境。

Conda 渠道注意事项：默认的 Managed Service for Apache Spark 2.1、2.2 和 2.3 映像版本在 .condarc 中不包含预配置的 Conda 软件包渠道（例如 defaults 或 conda-forge）（请参阅 2026 年 9 月 4 日的版本说明）。将不带前缀的软件包名称传递给 dataproc:conda.packages 或在未指定渠道的情况下运行 conda install PACKAGE 会失败，并显示 CondaValueError: No channels available to install from 或 PackagesNotFoundError。

如需安装 Conda 软件包，您必须明确指定渠道：

  • 使用 dataproc:conda.packages 属性时，请使用 CHANNEL::PACKAGE==VERSION 格式（例如 dataproc:conda.packages=conda-forge::pip==24.0）。
  • 在命令行中运行 conda install 时，传递 -c（或 --channel）标志（例如 conda install PACKAGES -c conda-forge）。

示例：

REGION=region
gcloud dataproc clusters create my-cluster \
    --image-version=2.3 \
    --region=${REGION} \
    --properties=^#^dataproc:conda.packages='conda-forge::pytorch==2.1.0,conda-forge::coverage==6.5.0'#dataproc:pip.packages='tokenizers==0.15.0,datasets==2.16.1'

Managed Service for Apache Spark 映像版本 3.0

Managed Service for Apache Spark 3.0 集群上安装了 Python 3。在 3.0 映像中，Pixi 作为 Python 安装的一部分进行安装，用于安装 Python 软件包，而不是 Conda。

避免软件包下载问题

在安装自定义 conda 和 pip 软件包时，Managed Service for Apache Spark 集群节点会从外部公共 Python 仓库下载软件包（请参阅与 conda 相关的集群属性）。 为避免因公共 Python 代码库不可用而导致集群创建失败，请考虑创建 Managed Service for Apache Spark 自定义映像或将依赖项上传到 Cloud Storage 存储桶（请参阅下载包含仅限内部 IP 的集群的依赖项）。

为作业选择 Python 解释器

如果您的集群上安装了多个 Python 解释器，则系统会运行 /etc/profile.d/effective-python.sh，导出 PYSPARK_PYTHON 环境变量以为 PySpark 作业选择默认 Python 解释器。如果您需要为 PySpark 作业选择非默认的 Python 解释器，请在将作业提交到集群时，将 spark.pyspark.python 和 spark.pyspark.driver.python 属性设置为所需的 Python 路径或版本（例如“/usr/bin/python3”或“python3.11”）。

示例：

REGION=region
gcloud dataproc jobs submit pyspark check_python_env.py \
    --cluster=my-cluster \
    --region=${REGION} \
    --properties="spark.pyspark.python=/usr/bin/python3,spark.pyspark.driver.python=/usr/bin/python3"

使用 sudo 运行 Python

如果您使用 SSH 连接到集群节点，则在运行 sudo python --version 时，显示的 Python 版本可能与 python --version 显示的版本不同。由于 sudo 使用默认的系统 Python /usr/bin/python，并且不执行 /etc/profile.d/effective-python.sh 来初始化 Python 环境，因此可能会发生此版本差异。为了在使用 sudo 时获得一致的体验，请找到 /etc/profile.d/effective-python.sh 中设置的 Python 路径，然后运行 env 命令将 PATH 设置为此 Python 路径。例如：

sudo env PATH=/opt/conda/default/bin:${PATH} python --version

使用与 conda 相关的集群属性

您可以在创建集群期间使用与 conda 相关的集群属性自定义 conda 环境。

创建 Managed Service for Apache Spark 集群时，可通过两种互斥的方式自定义 conda 环境：

  1. 使用 dataproc:conda.env.config.uri 集群属性在集群上创建并激活新的 conda 环境。或者

  2. 使用 dataproc:conda.packages 和 dataproc:pip.packages 集群属性分别将 conda 和 pip 软件包添加到集群上的 conda base 环境中。

与 conda 相关的集群属性

  • dataproc:conda.env.config.uri：位于 Cloud Storage 中的 conda 环境 YAML 配置文件的绝对路径。此文件用于在集群上创建并激活新的 conda 环境。由于默认映像不包含预配置的 Conda 渠道，请确保您的 environment.yaml 文件在 channels 下明确列出所需的软件包渠道（例如 conda-forge）。

    示例：

    1. 获取或创建 conda environment.yaml 配置文件。您可以手动创建该文件、使用现有文件，或使用以下命令导出现有 conda 环境至 environment.yaml 文件中： 

      conda env export --name=env-name > environment.yaml

    2. 将配置文件复制到您的 Cloud Storage 存储分区：

      gcloud storage cp environment.yaml gs://bucket-name/environment.yaml

    3. 创建集群并将其指向 Cloud Storage 中的环境配置文件。

      REGION=region
gcloud dataproc clusters create cluster-name \
    --region=${REGION} \
    --properties='dataproc:conda.env.config.uri=gs://bucket-name/environment.yaml' \
    ... other flags ...

  • dataproc:conda.packages：包含要在基础环境中安装的特定渠道和版本的 conda 软件包列表，格式为 CHANNEL::PACKAGE==VERSION（例如 conda-forge::pkg1==v1,conda-forge::pkg2==v2...）。如果 conda 未能解决与基础环境中的现有软件包之间的冲突，则系统不会安装有冲突的软件包。

    注意：

    • 由于默认的 Managed Service for Apache Spark 2.1、2.2 和 2.3 映像版本在 .condarc 中不包含预配置的 Conda 渠道，因此您必须为每个软件包名称添加相应渠道作为前缀（例如 conda-forge::）。如果传递未添加前缀的软件包名称，系统会返回 CondaValueError: No channels available to install from 或 PackagesNotFoundError 错误。

    • dataproc:conda.packages 和 dataproc:pip.packages 集群属性不能与 dataproc:conda.env.config.uri 集群属性搭配使用。

    • 指定多个软件包（以英文逗号分隔）时，您必须指定备用分隔符（请参阅集群属性格式）。以下示例指定“#”作为分隔符，以便将多个以英文逗号分隔的软件包名称传递给 dataproc:conda.packages 属性。

    示例：

    REGION=region
gcloud dataproc clusters create cluster-name \
    --region=${REGION} \
    --properties='^#^dataproc:conda.packages=conda-forge::pytorch==2.1.0,conda-forge::coverage==6.5.0' \
    ... other flags ...

  • dataproc:pip.packages：包含要在基础环境中安装的特定版本的 pip 软件包列表，格式为 pkg1==v1,pkg2==v2...。pip 仅在必要时升级现有依赖项。冲突可能会导致环境不一致。

    注意：

    • dataproc:pip.packages 和 dataproc:conda.packages 集群属性不能与 dataproc:conda.env.config.uri 集群属性搭配使用。

    • 指定多个软件包（以英文逗号分隔）时，您必须指定备用分隔符（请参阅集群属性格式）。以下示例指定“#”作为分隔符，以便将多个以英文逗号分隔的软件包名称传递给 dataproc:pip.packages 属性。

    示例：

    REGION=region
gcloud dataproc clusters create cluster-name \
    --region=${REGION} \
    --properties='^#^dataproc:pip.packages=tokenizers==0.15.0,datasets==2.16.1' \
    ... other flags ...

  • 您可以在创建集群时同时使用 dataproc:conda.packages 和 dataproc:pip.packages。

    示例：

    REGION=region
gcloud dataproc clusters create cluster-name \
    --region=${REGION} \
    --image-version=2.3 \
    --properties=^#^dataproc:conda.packages='conda-forge::pytorch==2.1.0,conda-forge::coverage==6.5.0'#dataproc:pip.packages='tokenizers==0.15.0,datasets==2.16.1' \
    ... other flags ...