設定 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 解譯器位於 VM 執行個體的 /opt/conda/default/bin 目錄下。以下頁面列出支援的 Managed Service for Apache Spark 2.x 映像檔版本內建的 Python 版本：

OS 的非預設 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

Python 3 已安裝在 Managed Service for Apache Spark 3.0 叢集上。在 3.0 版映像檔中，Pixi 會隨 Python 一併安裝，並用於安裝 Python 套件，而非 Conda。

避免發生套件下載問題

安裝自訂 conda 和 pip 套件時，Managed Service for Apache Spark 叢集節點會從外部公開 Python 存放區下載套件 (請參閱「conda 相關叢集屬性」)。為避免因公開 Python 存放區無法使用而導致叢集建立失敗，請考慮建立 Managed Service for Apache Spark 自訂映像檔，或將依附元件上傳至 Cloud Storage bucket (請參閱「只透過內部 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 bucket。

      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...。`pippip 僅在需要時才會升級既有的依附元件。若發生衝突，可能會導致環境不一致。

    注意：

    • 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 ...