Configura l'ambiente Python

I job PySpark su Managed Service for Apache Spark vengono eseguiti da un interprete Python sul cluster. Il codice del job deve essere compatibile in fase di runtime con la versione e le dipendenze dell'interprete Python.

Controlla la versione e i moduli dell'interprete

Il seguente programma di esempio check_python_env.py controlla l'utente Linux che esegue il job, l'interprete Python e i moduli disponibili.

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))

Esegui il programma:

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

Esempio di output:

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'])

Ambienti Python delle immagini di Managed Service for Apache Spark

Le sezioni seguenti descrivono gli ambienti Python per i cluster di versioni immagine di Managed Service for Apache Spark supportati.

Versione immagine 2.x di Managed Service for Apache Spark

Conda (o micromamba nelle immagini 2.3) è installato sui cluster Managed Service for Apache Spark 2.x. L'interprete Python 3 predefinito si trova nell'istanza VM in /opt/conda/default/bin. Le seguenti pagine elencano la versione di Python inclusa nelle versioni immagine di Managed Service for Apache Spark 2.x supportate:

L'interprete Python non predefinito del sistema operativo è disponibile in /usr/bin/.

Puoi installare i pacchetti conda e pip nell'ambiente base o configurare il tuo ambiente conda sul cluster utilizzando le proprietà del cluster relative a conda.

Nota sul canale Conda: le versioni immagine predefinite di Managed Service for Apache Spark 2.1, 2.2 e 2.3 non includono canali di pacchetti Conda preconfigurati (come defaults o conda-forge) in .condarc (consulta le note di rilascio del 4 settembre 2026). Il passaggio di nomi di pacchetti senza prefisso a dataproc:conda.packages o l'esecuzione di conda install PACKAGE senza specificare un canale non va a buon fine con CondaValueError: No channels available to install from o PackagesNotFoundError.

Per installare i pacchetti Conda, devi specificare esplicitamente il canale:

  • Quando utilizzi la proprietà dataproc:conda.packages, utilizza il formato CHANNEL::PACKAGE==VERSION (ad esempio, dataproc:conda.packages=conda-forge::pip==24.0).
  • Quando esegui conda install dalla riga di comando, passa il flag -c (o --channel) (ad esempio, conda install PACKAGES -c conda-forge).

Esempio:

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'

Versione immagine 3.0 di Managed Service for Apache Spark

Python 3 è installato sui cluster Managed Service for Apache Spark 3.0. Nelle immagini 3.0, Pixi viene installato nell'ambito dell'installazione di Python e viene utilizzato per installare i pacchetti Python anziché Conda.

Evita problemi di download dei pacchetti

I nodi del cluster Managed Service for Apache Spark scaricano i pacchetti da repository Python pubblici esterni quando installano pacchetti conda e pip personalizzati (consulta le proprietà del cluster relative a conda). Per evitare errori di creazione del cluster dovuti alla mancata disponibilità di repository Python pubblici, valuta la possibilità di creare un'immagine personalizzata di Managed Service for Apache Spark o di caricare le dipendenze in un bucket Cloud Storage (consulta Scarica le dipendenze con i cluster solo con IP interno).

Scegli un interprete Python per un job

Se nel cluster sono installati più interpreti Python, il sistema esegue /etc/profile.d/effective-python.sh, che esporta la variabile di ambiente PYSPARK_PYTHON per scegliere l'interprete Python predefinito per i tuoi job PySpark. Se hai bisogno di un interprete Python non predefinito per un job PySpark, quando invii il job al cluster, imposta le proprietà spark.pyspark.python e spark.pyspark.driver.python sul percorso o sulla versione Python richiesti (ad esempio, "/usr/bin/python3" o "python3.11").

Esempio:

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"

Python con sudo

Se ti connetti a un nodo del cluster utilizzando SSH, quando esegui sudo python --version, la versione di Python visualizzata può essere diversa da quella visualizzata da python --version. Questa differenza di versione può verificarsi perché sudo utilizza la versione Python predefinita del sistema /usr/bin/python e non esegue /etc/profile.d/effective-python.sh per inizializzare l'ambiente Python. Per un'esperienza coerente quando utilizzi sudo, individua il percorso Python impostato in /etc/profile.d/effective-python.sh, quindi esegui il comando env per impostare PATH su questo percorso Python. Ad esempio:

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

Utilizza le proprietà del cluster relative a conda

Puoi personalizzare l'ambiente conda durante la creazione del cluster utilizzando le proprietà del cluster relative a conda.

Esistono due modi che si escludono a vicenda per personalizzare l'ambiente conda quando crei un cluster Managed Service for Apache Spark:

  1. Utilizza la proprietà del cluster dataproc:conda.env.config.uri per creare e attivare un nuovo ambiente conda sul cluster. o

  2. Utilizza le proprietà del cluster dataproc:conda.packages e dataproc:pip.packages per aggiungere rispettivamente i pacchetti conda e pip all'ambiente conda base sul cluster.

Proprietà del cluster relative a conda

  • dataproc:conda.env.config.uri: il percorso assoluto di un file di configurazione YAML dell'ambiente conda che si trova in Cloud Storage. Questo file viene utilizzato per creare e attivare un nuovo ambiente conda sul cluster. Poiché le immagini predefinite non includono canali Conda preconfigurati, assicurati che il file environment.yaml elenchi esplicitamente i canali dei pacchetti richiesti (ad esempio conda-forge) in channels.

    Esempio:

    1. Recupera o crea un file di configurazione conda environment.yaml. Puoi creare il file manualmente, utilizzare un file esistente o esportare un ambiente conda esistente in un file environment.yaml utilizzando il seguente comando:

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

    2. Copia il file di configurazione nel bucket Cloud Storage.

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

    3. Crea il cluster e punta al file di configurazione dell'ambiente in 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: un elenco di pacchetti conda con canali e versioni specifici da installare nell'ambiente di base, formattati come CHANNEL::PACKAGE==VERSION (ad esempio, conda-forge::pkg1==v1,conda-forge::pkg2==v2...). Se conda non riesce a risolvere i conflitti con i pacchetti esistenti nell'ambiente di base, i pacchetti in conflitto non verranno installati.

    Note:

    • Poiché le versioni immagine predefinite di Managed Service for Apache Spark 2.1, 2.2 e 2.3 non includono canali Conda preconfigurati in .condarc, devi anteporre a ogni nome di pacchetto il relativo canale (ad esempio conda-forge::). Il passaggio di nomi di pacchetti senza prefisso non va a buon fine con CondaValueError: No channels available to install from o PackagesNotFoundError.

    • Le proprietà del cluster dataproc:conda.packages e dataproc:pip.packages non possono essere utilizzate con la proprietà del cluster dataproc:conda.env.config.uri.

    • Quando specifichi più pacchetti (separati da una virgola), devi specificare un carattere delimitatore alternativo (consulta la proprietà del cluster Formattazione). L'esempio seguente specifica "#" come carattere delimitatore per passare più nomi di pacchetti separati da virgole alla proprietà dataproc:conda.packages.

    Esempio:

    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: un elenco di pacchetti pip con versioni specifiche da installare nell'ambiente di base, formattato come pkg1==v1,pkg2==v2.... pip esegue l'upgrade delle dipendenze esistenti solo se necessario. I conflitti possono rendere l'ambiente incoerente.

    Note:

    • Le proprietà del cluster dataproc:pip.packages e dataproc:conda.packages non possono essere utilizzate con la proprietà del cluster dataproc:conda.env.config.uri.

    • Quando specifichi più pacchetti (separati da una virgola), devi specificare un carattere delimitatore alternativo (consulta la proprietà del cluster Formattazione). L'esempio seguente specifica "#" come carattere delimitatore per passare più nomi di pacchetti separati da virgole alla proprietà dataproc:pip.packages.

    Esempio:

    REGION=region
    gcloud dataproc clusters create cluster-name \
        --region=${REGION} \
        --properties='^#^dataproc:pip.packages=tokenizers==0.15.0,datasets==2.16.1' \
        ... other flags ...
    
  • Puoi utilizzare sia dataproc:conda.packages che dataproc:pip.packages durante la creazione di un cluster.

    Esempio:

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