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 인터프리터는 /opt/conda/default/bin 아래의 VM 인스턴스에 있습니다. 다음 페이지에서는 지원되는 Managed Service for Apache Spark 2.x 이미지 버전에 포함된 Python 버전을 보여줍니다.

• 2.1
• 2.2
• 2.3

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 설치의 일부로 설치되며 Conda 대신 Python 패키지를 설치하는 데 사용됩니다.

패키지 다운로드 문제 방지

Managed Service for Apache Spark 클러스터 노드는 커스텀 conda 및 pip 패키지를 설치할 때 외부 공개 Python 저장소에서 패키지를 다운로드합니다(conda 관련 클러스터 속성 참고). 공개 Python 저장소를 사용할 수 없어 클러스터 생성에 실패하는 것을 방지하려면 Managed Service for Apache Spark 커스텀 이미지를 만들거나 종속 항목을 Cloud Storage 버킷에 업로드하는 것이 좋습니다 (내부 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 환경에 추가합니다.

   경고: 속성에 의해 지정된 새 패키지 또는 환경을 설치하는 데 걸리는 시간에 따라 클러스터 생성 시간이 초과될 수 있습니다. 제한 시간은 10분으로 설정됩니다.

conda 관련 클러스터 속성

• dataproc:conda.env.config.uri: Cloud Storage에 있는 conda 환경 YAML 구성 파일의 절대 경로입니다. 이 파일은 클러스터에 새 conda 환경을 만들고 활성화하는 데 사용됩니다. 기본 이미지에는 사전 구성된 Conda 채널이 포함되지 않으므로 environment.yaml 파일에 channels 아래에 필요한 패키지 채널 (예: conda-forge)이 명시적으로 나열되어 있는지 확인하세요.

  참고: dataproc:conda.env.config.uri 클러스터 속성은 dataproc:conda.packages 또는 dataproc:pip.packages 클러스터 속성과 함께 사용할 수 없습니다.

  예:

  1. conda environment.yaml 구성 파일을 가져오거나 만듭니다. 다음 명령어를 사용하여 수동으로 파일을 생성하거나, 기존 파일을 사용하거나, environment.yaml 파일에 기존 conda 환경을 내보낼 수 있습니다.

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

  2. 구성 파일을 Cloud Storage 버킷에 복사합니다.

     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... 형식입니다. pip는 필요한 경우에만 기존 종속 항목을 업그레이드합니다. 충돌로 인해 환경이 일관되지 않을 수 있습니다.

  참고:

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