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 al runtime con la versione e le dipendenze dell'interprete Python.

Controllare 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 Managed Service for Apache Spark

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

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 sull'istanza VM in /opt/conda/default/bin. Le seguenti pagine elencano la versione di Python inclusa nelle versioni delle immagini di Managed Service for Apache Spark 2.x supportate:

• 2.1
• 2.2
• 2.3

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 correlate a conda.

Nota sul canale Conda: le versioni delle immagini 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 (vedi le note di rilascio del 4 settembre 2026). Il passaggio di nomi di pacchetto senza prefisso a dataproc:conda.packages o l'esecuzione di conda install PACKAGE senza specificare un canale non va a buon fine e viene visualizzato l'errore CondaValueError: No channels available to install from o PackagesNotFoundError.

Per installare i pacchetti Conda, devi specificare in modo esplicito 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 come parte dell'installazione di Python e viene utilizzato per installare i pacchetti Python anziché Conda.

Evitare 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 (vedi proprietà del cluster correlate 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 (vedi Scaricare le dipendenze con cluster solo con IP interno).

Scegliere un interprete Python per un job

Se sul 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 di 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 Python di sistema predefinito /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

Utilizzare le proprietà del cluster correlate a conda

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

Esistono due modi reciprocamente esclusivi 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 i pacchetti conda e pip, rispettivamente, all'ambiente conda base sul cluster.

   Avviso: la creazione del cluster può scadere a seconda del tempo necessario per installare i nuovi pacchetti o l'ambiente specificato dalle proprietà. Il timeout è impostato su 10 minuti.

Proprietà cluster correlate 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.

  Nota: la proprietà del cluster dataproc:conda.env.config.uri non può essere utilizzata con le proprietà del cluster dataproc:conda.packages o dataproc:pip.packages.

  Esempio:

  1. Recupera o crea un file di configurazione conda environment.yaml. Puoi creare manualmente il file, 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 indica il 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, formattato 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 predefinite delle immagini 2.1, 2.2 e 2.3 di Managed Service for Apache Spark non includono canali Conda preconfigurati in .condarc, devi aggiungere il prefisso di ogni nome del pacchetto con il relativo canale (ad esempio conda-forge::). Il passaggio di nomi di pacchetti senza prefisso non riesce 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 (vedi 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 causare l'incoerenza dell'ambiente.

  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 (vedi 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 quando crei 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 ...