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 interpretador

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 do Python para clusters de versão de imagem do Serviço Gerenciado para Apache Spark compatíveis.

Serviço Gerenciado para Apache Spark: versão de imagem 2.x

O Conda (ou micromamba nas imagens 2.3) é instalado nos 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 do Serviço Gerenciado para Apache Spark 2.x compatíveis:

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 nota de lançamento 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 do 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 de cluster relacionadas ao conda). Para evitar falhas na criação de clusters devido à indisponibilidade de repositórios públicos do Python, considere criar uma imagem personalizada do Serviço Gerenciado para Apache Spark ou fazer 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 interpretador 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 como 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, ao 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 padrão Python /usr/bin/python e não executa /etc/profile.d/effective-python.sh para inicializar o ambiente do 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 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 do cluster relacionadas ao conda.

Há duas maneiras mutuamente exclusivas de personalizar o ambiente do 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 do Conda no cluster. Ou

  2. Use as propriedades de cluster dataproc:conda.packages e dataproc:pip.packages para adicionar os 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 pacotes necessários (como conda-forge) em channels.

    Exemplo:

    1. Acesse ou crie um arquivo de configuração environment.yaml do conda. É possível criar o arquivo manualmente, usar um arquivo atual ou exportar um ambiente conda atual 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 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 2.1, 2.2 e 2.3 do Serviço Gerenciado para Apache Spark não incluem canais Conda pré-configurados em .condarc, é necessário prefixar cada nome de pacote com o canal dele (como conda-forge::). A transmissão de nomes de pacotes sem prefixo 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), é necessário especificar um caractere delimitador alternativo (consulte a propriedade de cluster Formatação). O exemplo a seguir especifica "#" como o caractere delimitador para transmitir vários nomes de pacotes separados por vírgulas para a 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.... 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), é necessário especificar um caractere delimitador alternativo (consulte a propriedade de cluster Formatação). 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 ...