Share via

Python용 Databricks 커넥트 설치

  • 아티클

참고 항목

이 문서에서는 Databricks Runtime 13.0 이상용 Databricks 커넥트 대해 설명합니다.

이 문서에서는 Python용 Databricks 커넥트 설치하는 방법을 설명합니다. Databricks 커넥트란?을 참조하세요. 이 문서의 Scala 버전은 Scala용 Databricks 커넥트 설치를 참조하세요.

요구 사항

  • 대상 Azure Databricks 작업 영역 및 클러스터는 Databricks 커넥트 대한 클러스터 구성 요구 사항을 충족해야 합니다.

  • 개발 머신에 Python 3을 설치해야 하며, 클라이언트 Python 설치의 부 버전은 Azure Databricks 클러스터의 부 Python 버전과 동일해야 합니다. 클러스터의 부 Python 버전을 찾으려면 클러스터에 대한 Databricks 런타임 릴리스 정보의 "시스템 환경" 섹션을 참조하세요. Databricks 런타임 릴리스 정보 버전 및 호환성을 참조 하세요.

    참고 항목

    PySpark UDF를 사용하려면 개발 머신의 설치된 부 버전의 Python이 클러스터에 설치된 Databricks Runtime에 포함된 부 버전의 Python과 일치해야 합니다.

  • Databricks 커넥트 주 및 부 패키지 버전은 Databricks 런타임 버전과 일치해야 합니다. Databricks는 항상 Databricks Runtime 버전과 일치하는 Databricks Connect의 최신 패키지를 사용할 것을 권장합니다. 예를 들어 Databricks Runtime 14.0 클러스터를 사용하는 경우 패키지 버전 databricks-connect 도 사용해야 14.0 합니다.

    참고 항목

    사용 가능한 Databricks Connect 릴리스 및 유지 관리 업데이트의 목록은 Databricks Connect 릴리스 정보를 참조하세요.

    Databricks 런타임 버전과 일치하는 최신 Databricks 커넥트 패키지를 사용하는 것은 요구 사항이 아닙니다. Databricks Runtime 13.3 LTS 이상의 경우 Databricks 커넥트 패키지 버전 이상에서 모든 버전의 Databricks 런타임에 대해 Databricks 커넥트 패키지를 사용할 수 있습니다. 그러나 이후 버전의 Databricks 런타임에서 사용할 수 있는 기능을 사용하려면 그에 따라 Databricks 커넥트 패키지를 업그레이드해야 합니다.

  • Databricks는 Databricks 커넥트 사용하는 각 Python 버전에 대해 Python 가상 환경을 활성화하는 것이 좋습니다. Python 가상 환경은 올바른 버전의 Python 및 Databricks 커넥트 함께 사용하고 있는지 확인하는 데 도움이 됩니다. 이렇게 하면 관련 기술 문제를 줄이거나 줄이는 데 도움이 될 수 있습니다. 다음 섹션에서 Python 가상 환경 또는 시를 venv 활성화하는 방법을 참조하세요. 이러한 도구에 대한 자세한 내용은 venv 또는 시를 참조하세요.

venv를 사용하여 Python 가상 환경 활성화

개발 머신에서 사용하고 venv 있고 클러스터에서 Python 3.10을 실행하는 경우 해당 버전으로 venv 환경을 만들어야 합니다. 다음 예제 명령은 Python 3.10을 사용하여 환경을 활성화 venv 하는 스크립트를 생성하고, 이 명령은 해당 스크립트를 현재 작업 디렉터리 내에 명명된 .venv 숨겨진 폴더 내에 배치합니다.

# Linux and macOS
python3.10 -m venv ./.venv

# Windows
python3.10 -m venv .\.venv

이러한 스크립트를 사용하여 이 venv 환경을 활성화하려면 venvs 작동 방법을 참조 하세요.

클라이언트 설정으로 건너뜁니다.

시를 사용하여 Python 가상 환경 활성화

  1. 아직 설치하지 않은 경우 시를 설치합니다.

  2. 개발 머신에서 시를 사용하고 있고 클러스터에서 Python 3.10을 실행하는 경우 해당 버전으로 시 가상 환경을 만들어야 합니다. 기존 Python 코드 프로젝트의 루트 디렉터리에서 다음 명령을 실행하여 시용 Python 코드 프로젝트를 초기화하도록 지시 poetry 합니다.

    poetry init

  3. 시는 완료할 수 있는 몇 가지 프롬프트를 표시합니다. 이러한 프롬프트는 Databricks 커넥트 관련이 없습니다. 이러한 프롬프트에 대한 자세한 내용은 init를 참조하세요.

  4. 프롬프트를 완료하면 시가 pyproject.toml Python 프로젝트에 파일을 추가합니다. 파일에 대한 pyproject.toml 자세한 내용은 pyproject.toml 파일을 참조하세요.

  5. Python 코드 프로젝트의 루트 디렉터리에서 파일을 읽고pyproject.toml, 종속성을 확인하고, 설치하고, 종속성을 잠그는 파일을 만들고poetry.lock, 마지막으로 가상 환경을 만들도록 지시 poetry 합니다. 이렇게 하려면 다음 명령을 실행합니다.

    poetry install

  6. Python 코드 프로젝트의 루트 디렉터리에서 가상 환경을 활성화하고 셸을 입력하도록 지시 poetry 합니다. 이렇게 하려면 다음 명령을 실행합니다.

    poetry shell

예를 들어 (my-project-py3.10)가상 환경의 이름이 터미널 프롬프트 바로 앞에 괄호로 표시되면 가상 환경이 활성화되고 셸이 입력된다는 것을 알 수 있습니다.

가상 환경을 비활성화하고 언제든지 셸을 종료하려면 명령을 exit실행합니다.

터미널 프롬프트 직전에 가상 환경의 이름이 더 이상 괄호 안에 표시되지 않을 때 셸을 종료했음을 알 수 있습니다.

시 가상 환경을 만들고 관리하는 방법에 대한 자세한 내용은 환경 관리를 참조 하세요.

클라이언트 설정

팁

Visual Studio Code용 Databricks 확장이 이미 설치된 경우 이러한 설정 지침을 따를 필요가 없습니다.

Visual Studio Code용 Databricks 확장에는 Databricks Runtime 13.0 이상에 대한 Databricks 커넥트 대한 기본 제공 지원이 이미 있습니다. Visual Studio Code용 Databricks 확장에 Databricks 커넥트 사용하여 디버그 코드로 건너뜁니다.

Databricks 커넥트 대한 요구 사항을 충족한 후 다음 단계를 완료하여 Databricks 커넥트 클라이언트를 설정합니다.

1단계: Databricks 커넥트 클라이언트 설치

이 섹션에서는 venv 또는 Poetry를 사용하여 Databricks 커넥트 클라이언트를 설치하는 방법을 설명합니다.

venv를 사용하여 Databricks 커넥트 클라이언트 설치

  1. 가상 환경이 활성화되면 명령을 실행 uninstall 하여 PySpark가 이미 설치된 경우 제거합니다. databricks-connect 패키지가 PySpark와 충돌하기 때문에 필요한 작업입니다. 자세한 내용은 PySpark 설치 충돌을 참조하세요. PySpark가 이미 설치되어 있는지 여부를 검사 명령을 실행합니다show.

    # Is PySpark already installed?
pip3 show pyspark

# Uninstall PySpark
pip3 uninstall pyspark

  2. 가상 환경이 계속 활성화된 상태에서 명령을 실행하여 Databricks 커넥트 클라이언트를 설치합니다install. --upgrade 이 옵션을 사용하여 기존 클라이언트 설치를 지정된 버전으로 업그레이드합니다.

    pip3 install --upgrade "databricks-connect==14.0.*"  # Or X.Y.* to match your cluster version.

    참고 항목

    Databricks는 "점 별표" 표기법을 추가하여 가장 최근 패키지가 설치되었는지 확인하는 대신 databricks-connect=X.Y지정 databricks-connect==X.Y.* 하는 것이 좋습니다. 이는 요구 사항은 아니지만 해당 클러스터에 지원되는 최신 기능을 사용할 수 있는지 확인하는 데 도움이 됩니다.

2단계: 연결 속성 구성으로 건너뜁니다.

시를 사용하여 Databricks 커넥트 클라이언트 설치

  1. 가상 환경이 활성화되면 명령을 실행 remove 하여 PySpark가 이미 설치된 경우 제거합니다. databricks-connect 패키지가 PySpark와 충돌하기 때문에 필요한 작업입니다. 자세한 내용은 PySpark 설치 충돌을 참조하세요. PySpark가 이미 설치되어 있는지 여부를 검사 명령을 실행합니다show.

    # Is PySpark already installed?
poetry show pyspark

# Uninstall PySpark
poetry remove pyspark

  2. 가상 환경이 계속 활성화된 상태에서 명령을 실행하여 Databricks 커넥트 클라이언트를 설치합니다add.

    poetry add databricks-connect@~14.0  # Or X.Y to match your cluster version.

    참고 항목

    Databricks는 "at-tilde" 표기법을 사용하여 가장 최근 패키지가 설치되어 있는지 확인하는 대신 databricks-connect==14.0지정 databricks-connect@~14.0 하는 것이 좋습니다. 이는 요구 사항은 아니지만 해당 클러스터에 지원되는 최신 기능을 사용할 수 있는지 확인하는 데 도움이 됩니다.

2단계: 연결 속성 구성

이 섹션에서는 Databricks 커넥트 원격 Azure Databricks 클러스터 간에 연결을 설정하도록 속성을 구성합니다. 이러한 속성에는 클러스터를 사용하여 Databricks 커넥트 인증하는 설정이 포함됩니다.

Databricks Runtime 13.1 이상용 Databricks 커넥트 경우 Databricks 커넥트 Python용 Databricks SDK를 포함합니다. 이 SDK는 인증에 대한 통합되고 일관된 아키텍처 및 프로그래밍 방식인 Databricks 클라이언트 통합 인증 표준을 구현합니다. 이 방법을 사용하면 Azure Databricks를 사용하여 인증을 설정하고 자동화하는 것이 더 중앙 집중화되고 예측 가능합니다. 이를 통해 Azure Databricks 인증을 한 번 구성한 다음, 추가 인증 구성 변경 없이 여러 Azure Databricks 도구 및 SDK에서 해당 구성을 사용할 수 있습니다.

참고 항목

  • OAuth U2M(사용자-컴퓨터) 인증 은 Python 0.19.0 이상용 Databricks SDK에서 지원됩니다. OAuth U2M 인증을 사용하려면 코드 프로젝트의 설치된 Python용 Databricks SDK 버전을 0.19.0 이상으로 업데이트해야 할 수 있습니다. Python용 Databricks SDK 시작 참조

    OAuth U2M 인증의 경우 Python 코드를 실행하기 전에 Databricks CLI를 사용하여 인증해야 합니다. 자습서를 참조하세요.

  • OAuth M2M(컴퓨터-컴퓨터) 인증 OAuth M2M(컴퓨터 대 컴퓨터) 인증은 Python 0.18.0 이상용 Databricks SDK에서 지원됩니다. OAuth M2M 인증을 사용하려면 코드 프로젝트의 설치된 Python용 Databricks SDK 버전을 0.18.0 이상으로 업데이트해야 할 수 있습니다. Python용 Databricks SDK 시작 참조

  • Python용 Databricks SDK는 아직 Azure 관리 ID 인증을 구현하지 않았습니다.

  • Databricks Runtime 13.0용 Databricks 커넥트 인증을 위한 Azure Databricks 개인용 액세스 토큰 인증만 지원합니다.

  1. 다음 구성 속성을 수집합니다.

  2. 코드 내에서 연결을 구성합니다. Databricks 커넥트 구성 속성을 찾을 때까지 다음 순서대로 검색합니다. 찾으면 다시 기본 옵션을 통해 검색을 중지합니다. 각 옵션에 대한 세부 정보는 다음 표 다음에 표시됩니다.

    구성 속성 옵션 적용 대상
    1. DatabricksSession 클래스의 remote() 메서드 Azure Databricks 개인용 액세스 토큰 인증만
    2. Azure Databricks 구성 프로필 모든 Azure Databricks 인증 유형
    3. SPARK_REMOTE 환경 변수 Azure Databricks 개인용 액세스 토큰 인증만
    4. DATABRICKS_CONFIG_PROFILE 환경 변수 모든 Azure Databricks 인증 유형
    5. 각 구성 속성에 대한 환경 변수 모든 Azure Databricks 인증 유형
    6. 명명된 Azure Databricks 구성 프로필 DEFAULT 모든 Azure Databricks 인증 유형

    1. DatabricksSession 클래스의 remote() 메서드

      Azure Databricks 개인용 액세스 토큰 인증에만 적용되는 이 옵션의 경우 작업 영역 인스턴스 이름, Azure Databricks 개인용 액세스 토큰 및 클러스터의 ID를 지정합니다.

      다음과 같이 여러 가지 방법으로 클래스를 초기화 DatabricksSession 할 수 있습니다.

      • 에서 host, token및 cluster_id 필드를 DatabricksSession.builder.remote()설정합니다.
      • Databricks SDK의 클래스를 Config 사용합니다.
      • 필드와 함께 Databricks 구성 프로필을 지정합니다 cluster_id .
      • 에서 Spark 커넥트 연결 문자열 DatabricksSession.builder.remote()설정합니다.

      Databricks는 코드에서 이러한 연결 속성을 직접 지정하지 않는 것이 좋습니다. 대신 Databricks는 이 섹션 전체에서 설명한 대로 환경 변수 또는 구성 파일을 통해 속성을 구성하는 것이 좋습니다. 다음 코드 예제에서는 사용자 또는 Azure KeyVault와 같은 다른 구성 저장소에서 필요한 속성을 가져오기 위해 제안된 retrieve_* 함수의 일부 구현을 직접 제공한다고 가정합니다.

      이러한 각 방법에 대한 코드는 다음과 같습니다.

      # Set the host, token, and cluster_id fields in DatabricksSession.builder.remote.
# If you have already set the DATABRICKS_CLUSTER_ID environment variable with the
# cluster's ID, you do not also need to set the cluster_id field here.
from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.remote(
  host       = f"https://{retrieve_workspace_instance_name()}",
  token      = retrieve_token(),
  cluster_id = retrieve_cluster_id()
).getOrCreate()

# Use the Databricks SDK's Config class.
# If you have already set the DATABRICKS_CLUSTER_ID environment variable with the
# cluster's ID, you do not also need to set the cluster_id field here.
from databricks.connect import DatabricksSession
from databricks.sdk.core import Config

config = Config(
  host       = f"https://{retrieve_workspace_instance_name()}",
  token      = retrieve_token(),
  cluster_id = retrieve_cluster_id()
)

spark = DatabricksSession.builder.sdkConfig(config).getOrCreate()

# Specify a Databricks configuration profile along with the `cluster_id` field.
# If you have already set the DATABRICKS_CLUSTER_ID environment variable with the
# cluster's ID, you do not also need to set the cluster_id field here.
from databricks.connect import DatabricksSession
from databricks.sdk.core import Config

config = Config(
  profile    = "<profile-name>",
  cluster_id = retrieve_cluster_id()
)

spark = DatabricksSession.builder.sdkConfig(config).getOrCreate()

# Set the Spark Connect connection string in DatabricksSession.builder.remote.
from databricks.connect import DatabricksSession

workspace_instance_name = retrieve_workspace_instance_name()
token                   = retrieve_token()
cluster_id              = retrieve_cluster_id()

spark = DatabricksSession.builder.remote(
  f"sc://{workspace_instance_name}:443/;token={token};x-databricks-cluster-id={cluster_id}"
).getOrCreate()

    2. Azure Databricks 구성 프로필

      이 옵션의 경우 사용하려는 Databricks 인증 유형에 필요한 필드 cluster_id 및 기타 필드가 포함된 Azure Databricks 구성 프로필을 만들거나 식별합니다.

      각 인증 유형에 필요한 구성 프로필 필드는 다음과 같습니다.

      그런 다음 클래스를 통해 Config 이 구성 프로필의 이름을 설정합니다.

      다음과 같이 몇 가지 방법으로 지정할 cluster_id 수 있습니다.

      • 구성 프로필에 cluster_id 필드를 포함하고 구성 프로필의 이름을 지정하기만 하면 됩니다.
      • 필드와 함께 구성 프로필 이름을 지정합니다 cluster_id .

      클러스터의 ID를 사용하여 DATABRICKS_CLUSTER_ID 환경 변수를 이미 설정한 경우 지정 cluster_id하지 않아도 됩니다.

      이러한 각 방법에 대한 코드는 다음과 같습니다.

      # Include the cluster_id field in your configuration profile, and then
# just specify the configuration profile's name:
from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.profile("<profile-name>").getOrCreate()

# Specify the configuration profile name along with the cluster_id field.
# In this example, retrieve_cluster_id() assumes some custom implementation that
# you provide to get the cluster ID from the user or from some other
# configuration store:
from databricks.connect import DatabricksSession
from databricks.sdk.core import Config

config = Config(
  profile    = "<profile-name>",
  cluster_id = retrieve_cluster_id()
)

spark = DatabricksSession.builder.sdkConfig(config).getOrCreate()

    3. SPARK_REMOTE 환경 변수

      Azure Databricks 개인용 액세스 토큰 인증에만 적용되는 이 옵션의 경우 환경 변수를 다음 문자열로 설정하고 SPARK_REMOTE 자리 표시자를 적절한 값으로 바꿉니다.

      sc://<workspace-instance-name>:443/;token=<access-token-value>;x-databricks-cluster-id=<cluster-id>

      그런 다음, 다음과 같이 클래스를 DatabricksSession 초기화합니다.

      from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

      환경 변수를 설정하려면 운영 체제 설명서를 참조하세요.

    4. DATABRICKS_CONFIG_PROFILE 환경 변수

      이 옵션의 경우 사용하려는 Databricks 인증 유형에 필요한 필드 cluster_id 및 기타 필드가 포함된 Azure Databricks 구성 프로필을 만들거나 식별합니다.

      클러스터의 ID를 사용하여 DATABRICKS_CLUSTER_ID 환경 변수를 이미 설정한 경우 지정 cluster_id하지 않아도 됩니다.

      각 인증 유형에 필요한 구성 프로필 필드는 다음과 같습니다.

      환경 변수를 DATABRICKS_CONFIG_PROFILE 이 구성 프로필의 이름으로 설정합니다. 그런 다음, 다음과 같이 클래스를 DatabricksSession 초기화합니다.

      from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

      환경 변수를 설정하려면 운영 체제 설명서를 참조하세요.

    5. 각 구성 속성에 대한 환경 변수

      이 옵션의 DATABRICKS_CLUSTER_ID 경우 사용하려는 Databricks 인증 유형에 필요한 환경 변수 및 기타 환경 변수를 설정합니다.

      각 인증 유형에 필요한 환경 변수는 다음과 같습니다.

      그런 다음, 다음과 같이 클래스를 DatabricksSession 초기화합니다.

      from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

      환경 변수를 설정하려면 운영 체제 설명서를 참조하세요.

    6. 명명된 Azure Databricks 구성 프로필 DEFAULT

      이 옵션의 경우 사용하려는 Databricks 인증 유형에 필요한 필드 cluster_id 및 기타 필드가 포함된 Azure Databricks 구성 프로필을 만들거나 식별합니다.

      클러스터의 ID를 사용하여 DATABRICKS_CLUSTER_ID 환경 변수를 이미 설정한 경우 지정 cluster_id하지 않아도 됩니다.

      각 인증 유형에 필요한 구성 프로필 필드는 다음과 같습니다.

      이 구성 프로필 DEFAULT의 이름을 지정합니다.

      그런 다음, 다음과 같이 클래스를 DatabricksSession 초기화합니다.

      from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

  3. Databricks 클러스터에 대한 환경 및 연결 유효성 검사

    • 다음 명령은 사용자 환경, 기본 자격 증명 및 클러스터에 대한 연결이 모두 Databricks 커넥트 대해 올바르게 설정되었는지 확인합니다.

      databricks-connect test

      이 명령은 환경에 구성된 기본 자격 증명(예: DEFAULT 구성 프로필 또는 환경 변수를 통해)을 선택합니다.

      설정에서 비호환성을 감지하면 0이 아닌 종료 코드와 해당 오류 메시지와 함께 명령이 실패합니다.

    • 또한 Python용 pyspark Databricks 커넥트 일부로 포함된 셸을 사용할 수도 있습니다. 다음을 실행하여 셸을 시작합니다.

      pyspark

      예를 들어 Spark 셸이 나타납니다.

      Python 3.10 ...
[Clang ...] on darwin
Type "help", "copyright", "credits" or "license" for more information.
Welcome to
      ____              __
     / __/__  ___ _____/ /__
    _\ \/ _ \/ _ `/ __/  '_/
   /__ / .__/\_,_/_/ /_/\_\   version 13.0
      /_/

Using Python version 3.10 ...
Client connected to the Spark Connect server at sc://...:.../;token=...;x-databricks-cluster-id=...
SparkSession available as 'spark'.
>>>

      프롬프트에서 >>> 다음과 같은 spark.range(1,10).show()간단한 PySpark 명령을 실행합니다. 오류가 없으면 성공적으로 연결되었습니다.

      성공적으로 연결한 경우 Spark 셸을 중지하려면 명령을 누르 Ctrl + d 거나 Ctrl + z실행하거나 실행 quit() 합니다 exit().

      이진 파일에 대한 databricks-connect 자세한 내용은 Python용 Databricks 커넥트 고급 사용을 참조하세요.