Configurar o ambiente Python

Os jobs do PySpark no Serviço Gerenciado para Apache Spark são executados por um interpretador do Python no cluster. O código do job precisa ser compatível no ambiente de execução com a versão e as dependências do interpretador do Python.

Verificar a versão e os módulos do intérprete

O programa de amostra check_python_env.py a seguir verifica o usuário do Linux que executa o job, o interpretador do Python e os módulos disponíveis.

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

Execute o programa:

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

Exemplo de resposta: 

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

Ambientes Python de imagem do Serviço Gerenciado para Apache Spark

As seções a seguir descrevem os ambientes Python para clusters compatíveis com a versão da imagem do Serviço Gerenciado para Apache Spark.

Versão 2.x da imagem do Serviço Gerenciado para Apache Spark

O Conda (ou micromamba em imagens 2.3) está instalado em clusters do Serviço Gerenciado para Apache Spark 2.x. O interpretador padrão do Python 3 está localizado na instância de VM em /opt/conda/default/bin. As páginas a seguir listam a versão do Python incluída nas versões de imagem 2.x compatíveis do Serviço Gerenciado para Apache Spark:

O interpretador Python não padrão do SO está disponível em /usr/bin/.

É possível instalar pacotes conda e pip no ambiente base ou configurar seu próprio ambiente conda no cluster usando propriedades de cluster relacionadas ao conda.

Observação sobre o canal conda: as versões de imagem padrão 2.1, 2.2 e 2.3 do Serviço Gerenciado para Apache Spark não incluem canais de pacotes conda pré-configurados (como defaults ou conda-forge) em .condarc. Consulte a observação da versão de 4 de setembro de 2026. Transmitir nomes de pacotes sem prefixo para dataproc:conda.packages ou executar conda install PACKAGE sem especificar um canal falha com CondaValueError: No channels available to install from ou PackagesNotFoundError.

Para instalar pacotes do Conda, especifique explicitamente o canal:

  • Ao usar a propriedade dataproc:conda.packages, use o formato CHANNEL::PACKAGE==VERSION (por exemplo, dataproc:conda.packages=conda-forge::pip==24.0).
  • Ao executar conda install na linha de comando, transmita a flag -c (ou --channel). Por exemplo, conda install PACKAGES -c conda-forge.

Exemplo:

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'

Versão 3.0 da imagem do Serviço Gerenciado para Apache Spark

O Python 3 está instalado nos clusters do Serviço Gerenciado para Apache Spark 3.0. Nas imagens 3.0, o Pixi é instalado como parte da instalação do Python e é usado para instalar pacotes Python em vez do Conda.

Evitar problemas de download de pacotes

Os nós de cluster do Serviço Gerenciado para Apache Spark fazem o download de pacotes de repositórios públicos externos do Python ao instalar pacotes personalizados conda e pip (consulte propriedades do cluster relacionadas ao conda). Para evitar falhas na criação de clusters devido à indisponibilidade de repositórios públicos do Python, crie uma imagem personalizada do Serviço Gerenciado para Apache Spark ou faça upload das dependências para um bucket do Cloud Storage (consulte Fazer o download de dependências com clusters somente de IP interno).

Escolher um intérprete do Python para um job

Se vários interpretadores do Python estiverem instalados no cluster, o sistema executará /etc/profile.d/effective-python.sh, que exporta a variável de ambiente PYSPARK_PYTHON para escolher o interpretador padrão do Python para os jobs do PySpark. Se você precisar de um interpretador Python não padrão para um job do PySpark, ao enviar o job para o cluster, defina as propriedades spark.pyspark.python e spark.pyspark.driver.python para o caminho ou a versão do Python necessários (por exemplo, "/usr/bin/python3" ou "python3.11").

Exemplo:

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 com sudo

Se você se conectar a um nó de cluster usando SSH, quando executar sudo python --version, a versão do Python exibida poderá ser diferente da versão exibida por python --version. Essa diferença de versão pode ocorrer porque sudo usa o sistema Python padrão /usr/bin/python e não executa /etc/profile.d/effective-python.sh para inicializar o ambiente Python. Para uma experiência consistente ao usar sudo, localize o caminho do Python definido em /etc/profile.d/effective-python.sh e execute o comando env para definir o PATH como esse caminho do Python. Exemplo:

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

Usar propriedades de cluster relacionadas ao Conda

É possível personalizar o ambiente conda durante a criação do cluster usando propriedades de cluster relacionadas ao conda.

Há duas maneiras mutuamente exclusivas de personalizar o ambiente conda ao criar um cluster do Serviço Gerenciado para Apache Spark:

  1. Use a propriedade de cluster dataproc:conda.env.config.uri para criar e ativar um novo ambiente conda no cluster. ou

  2. Use as propriedades de cluster dataproc:conda.packages e dataproc:pip.packages para adicionar pacotes conda e pip, respectivamente, ao ambiente conda base no cluster.

Propriedades de cluster relacionadas ao Conda

  • dataproc:conda.env.config.uri:o caminho absoluto para um arquivo de configuração YAML do ambiente conda localizado no Cloud Storage. Esse arquivo é usado para criar e ativar um novo ambiente conda no cluster. Como as imagens padrão não incluem canais do Conda pré-configurados, verifique se o arquivo environment.yaml lista explicitamente os canais de pacote necessários (como conda-forge) em channels.

    Exemplo:

    1. Receba ou crie um arquivo de configuração environment.yaml do conda. É possível criar manualmente o arquivo, usar um arquivo atual ou exportar um ambiente conda para um arquivo environment.yaml usando o seguinte comando: 

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

    2. Copie o arquivo de configuração para o bucket do Cloud Storage. 

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

    3. Crie o cluster e aponte para o arquivo de configuração do ambiente no 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:uma lista de pacotes conda com canais e versões específicos a serem instalados no ambiente de base, formatados como CHANNEL::PACKAGE==VERSION (por exemplo, conda-forge::pkg1==v1,conda-forge::pkg2==v2...). Se conda não conseguir resolver conflitos com pacotes existentes no ambiente de base, os pacotes conflitantes não serão instalados.

    Observações:

    • Como as versões de imagem padrão do Serviço Gerenciado para Apache Spark 2.1, 2.2 e 2.3 não incluem canais conda pré-configurados em .condarc, é necessário prefixar cada nome de pacote com o canal dele (como conda-forge::). Se você transmitir nomes de pacotes sem prefixo, vai ocorrer uma falha com CondaValueError: No channels available to install from ou PackagesNotFoundError.

    • As propriedades de cluster dataproc:conda.packages e dataproc:pip.packages não podem ser usadas com a propriedade de cluster dataproc:conda.env.config.uri.

    • Ao especificar vários pacotes (separados por vírgula), você precisa especificar um caractere delimitador alternativo. Consulte a propriedade Formatação do cluster. O exemplo a seguir especifica "#" como o caractere delimitador para transmitir vários nomes de pacotes separados por vírgulas à propriedade dataproc:conda.packages.

    Exemplo:

    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:uma lista de pacotes pip com versões específicas a serem instaladas no ambiente de base, formatadas como pkg1==v1,pkg2==v2.... O pip faz upgrade das dependências atuais apenas se necessário. Os conflitos podem tornar o ambiente inconsistente.

    Observações:

    • As propriedades de cluster dataproc:pip.packages e dataproc:conda.packages não podem ser usadas com a propriedade de cluster dataproc:conda.env.config.uri.

    • Ao especificar vários pacotes (separados por vírgula), você precisa especificar um caractere delimitador alternativo. Consulte a propriedade Formatação do cluster. O exemplo a seguir especifica "#" como o caractere delimitador para transmitir vários nomes de pacotes separados por vírgulas para a propriedade dataproc:pip.packages.

    Exemplo:

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

  • É possível usar dataproc:conda.packages e dataproc:pip.packages ao criar um cluster.

    Exemplo:

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