다음을 통해 공유

Databricks 자산 번들을 사용하여 Python 휠 파일 빌드

이 문서에서는 Databricks 자산 번들 프로젝트의 일부로 Python 휠 파일을 빌드, 배포 및 실행하는 방법을 설명합니다. Databricks 자산 번들이란?.

JAR을 빌드하고 Unity 카탈로그에 업로드하는 예제 구성은 JAR 파일을 Unity 카탈로그 업로드하는번들을 참조하세요.

Requirements

템플릿을 사용하여 번들 만들기

이 단계에서는 Python용 Azure Databricks 기본 번들 템플릿을 사용하여 번들을 만듭니다. 이 번들은 Python 휠 파일로 빌드할 파일과 이 Python 휠 파일을 빌드하기 위한 Azure Databricks 작업의 정의로 구성됩니다. 그런 다음 Azure Databricks 작업 영역 내의 Python 휠 작업에서 배포된 파일의 유효성을 검사, 배포 및 Python 휠 파일로 빌드합니다.

Note

The Azure Databricks default bundle template for Python uses uv to build the Python wheel file. To install uv, see Installing uv.

번들을 처음부터 만들려면 수동으로 번들 만들기를 참조하세요.

1단계: 번들 만들기

번들에는 배포하려는 아티팩트와 실행하려는 워크플로에 대한 설정이 포함됩니다.

  1. 터미널 또는 명령 프롬프트를 사용하여 템플릿의 생성된 번들을 포함하는 로컬 개발 머신의 디렉터리로 전환합니다.

  2. Databricks CLI 버전을 사용하여 명령을 실행합니다 bundle init .

    databricks bundle init

  3. Template to use의 경우, default-python를 눌러 기본값 Enter를 그대로 둡니다.

  4. Unique name for this project의 경우 기본값 my_project를 그대로 두거나 다른 값을 입력한 다음 Enter를 누릅니다. 이것으로 번들의 루트 디렉터리 이름이 결정됩니다. 이 루트 디렉터리가 현재 작업 디렉터리에 만들어집니다.

  5. Include a stub (sample) notebook에서 no을 선택하고 Enter를 누릅니다. Databricks CLI에 샘플 노트북을 번들에 추가하지 않도록 지시합니다.

  6. Include a stub (sample) Delta Live Tables pipeline에서 no을 선택하고 Enter를 누릅니다. 그러면 Databricks CLI가 번들에 샘플 파이프라인을 정의하지 않도록 지시합니다.

  7. Include a stub (sample) Python package의 경우, yes를 눌러 기본값 Enter를 그대로 둡니다. 그러면 Databricks CLI에서 샘플 Python 휠 패키지 파일 및 관련 빌드 지침을 번들에 추가하도록 지시합니다.

  8. Use serverless에서 yes을 선택하고 Enter를 누릅니다. 그러면 Databricks CLI가 서버리스 컴퓨팅에서 실행되도록 번들을 구성하도록 지시합니다.

2단계: 번들 탐색

템플릿이 생성한 파일을 보려면 새로 만든 번들의 루트 디렉터리로 전환하고 원하는 IDE를 사용하여 이 디렉터리를 엽니다. 특히 관심 있는 파일은 다음과 같습니다.

  • databricks.yml: 이 파일은 번들의 이름을 지정하고, 빌드 설정을 지정 whl 하고, 작업 구성 파일에 대한 참조를 포함하며, 대상 작업 영역에 대한 설정을 정의합니다.
  • resources/<project-name>_job.yml: 이 파일은 Python 휠 작업의 설정을 지정합니다.
  • src/<project-name>: 이 디렉터리에는 Python 휠 작업이 Python 휠 파일을 빌드하는 데 사용하는 파일이 포함됩니다.

Note

Databricks Runtime 12.2 LTS 이하의 클러스터에 Python 휠 파일을 설치하려면 다음 최상위 매핑을 databricks.yml 파일에 추가해야 합니다.

# Applies to all tasks of type python_wheel_task.
experimental:
  python_wheel_wrapper: true

3단계: 프로젝트의 번들 구성 파일 유효성 검사

이 단계에서는 번들 구성이 유효한지 확인합니다.

  1. 루트 디렉터리에서 Databricks CLI를 사용하여 다음과 같이 bundle validate 명령을 실행합니다.

    databricks bundle validate

  2. 번들 구성 요약이 반환되면 유효성 검사는 성공입니다. 오류가 반환되면 오류를 수정한 다음 이 단계를 반복합니다.

이 단계 후에 번들을 변경한 경우 이 단계를 반복하여 번들 구성이 여전히 유효한지 확인해야 합니다.

4단계: Python 휠 파일 빌드 및 원격 작업 영역에 로컬 프로젝트 배포

이 단계에서 Python 휠 파일은 원격 Azure Databricks 작업 영역에 빌드되고 배포되며, Azure Databricks 작업은 작업 영역 내에 만들어집니다.

  1. Databricks CLI를 사용하여 bundle deploy 명령을 다음과 같이 실행합니다.

    databricks bundle deploy -t dev

  2. 로컬로 빌드된 Python 휠 파일이 배포되었는지 확인하려면 다음을 수행합니다.

    1. In your Azure Databricks workspace's sidebar, click Workspace.
    2. 다음 폴더로 이동하십시오: Workspace > Users ><your-username>> .bundle ><project-name>> dev > artifacts > .internal ><random-guid> 폴더로 클릭하세요.

    Python 휠 파일은 이 폴더에 있어야 합니다.

  3. 작업이 만들어졌는지 여부를 확인하려면 다음을 수행합니다.

    1. Azure Databricks 작업 영역의 사이드바에서 작업 및 파이프라인을 클릭합니다.
    2. Optionally, select the Jobs and Owned by me filters.
    3. [개발<your-username>] <project-name>_job 클릭합니다.
    4. Click the Tasks tab.

    There should be one task: main_task.

이 단계 후에 번들을 변경한 경우 3-4단계를 반복하여 번들 구성이 여전히 유효한지 확인한 다음 프로젝트를 다시 배포합니다.

5단계: 배포된 프로젝트 실행

이 단계에서는 작업 영역에서 Azure Databricks 작업을 실행합니다.

  1. 루트 디렉터리에서 Databricks CLI를 사용하여 다음과 같이 명령을 실행하고 bundle run을(를) 1단계에서 프로젝트 이름으로 교체합니다.

    databricks bundle run -t dev <project-name>_job

  2. 터미널에 표시되는 Run URL의 값을 복사하고 이 값을 웹 브라우저에 붙여넣어 Azure Databricks 작업 영역을 엽니다.

  3. In your Azure Databricks workspace, after the task completes successfully and shows a green title bar, click the main_task task to see the results.

Poetry 또는 setuptools를 사용하여 whl 파일을 생성하세요.

기본 Python 템플릿과 함께 databricks bundle init를 사용하면, uv과 pyproject.toml을 사용하여 Python 휠을 빌드하는 번들을 구성하는 방법을 보여주는 번들이 생성됩니다. 그러나 휠을 빌드하려면 대신 Poetry 또는 setuptools를 사용할 수도 있습니다.

Poetry 또는 setuptools 설치

  1. Poetry를 설치하거나 setuptools을(를) 실행하세요.

    Poetry

    • Install Poetry, version 1.6 or above, if it is not already installed. 설치된 버전의 시를 확인하려면 명령 poetry -V 또는 poetry --version.를 실행합니다.
    • Python 버전 3.10 이상이 설치되어 있는지 확인합니다. Python 버전을 확인하려면 명령을 python -V 실행하거나 python --version.

    Setuptools

    wheel 및 setuptools 패키지가 아직 설치되지 않은 경우, 다음 명령을 실행하여 설치합니다.

    pip3 install --upgrade wheel setuptools

  2. 이 번들을 Git 공급자와 함께 저장하려는 경우 프로젝트의 루트에 파일을 추가하고 .gitignore 이 파일에 다음 항목을 추가합니다.

    Poetry

    .databricks
dist

    Setuptools

    .databricks
build
dist
src/my_package/my_package.egg-info

빌드 파일 추가

  1. 번들의 루트에서 Poetry를 사용하거나 setuptools를 사용하여 Python 휠 파일을 빌드할 경우 다음 폴더와 파일을 만드십시오.

    Poetry

    ├── src
│     └── my_package
│           ├── __init__.py
│           ├── main.py
│           └── my_module.py
└── pyproject.toml

    Setuptools

    ├── src
│     └── my_package
│           ├── __init__.py
│           ├── main.py
│           └── my_module.py
└── setup.py

  2. pyproject.toml 또는 setup.py 파일에 다음 코드를 추가합니다.

    Pyproject.toml

    [tool.poetry]
name = "my_package"
version = "0.0.1"
description = "<my-package-description>"
authors = ["my-author-name <my-author-name>@<my-organization>"]

[tool.poetry.dependencies]
python = "^3.10"

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

[tool.poetry.scripts]
main = "my_package.main:main"
    • 조직의 기본 연락처 이름으로 대체 my-author-name 합니다.
    • 조직의 기본 전자 메일 연락처 주소로 대체 my-author-name>@<my-organization 합니다.
    • Python 휠 파일의 표시 설명으로 <my-package-description>를 대체합니다.

    Setup.py

    from setuptools import setup, find_packages

import src

setup(
  name = "my_package",
  version = "0.0.1",
  author = "<my-author-name>",
  url = "https://<my-url>",
  author_email = "<my-author-name>@<my-organization>",
  description = "<my-package-description>",
  packages=find_packages(where='./src'),
  package_dir={'': 'src'},
  entry_points={
    "packages": [
      "main=my_package.main:main"
    ]
  },
  install_requires=[
    "setuptools"
  ]
)
    • 을 organization URL로 대체 https://<my-url> 합니다.
    • 조직의 기본 연락처 이름으로 대체 <my-author-name> 합니다.
    • 조직의 기본 전자 메일 연락처 주소로 대체 <my-author-name>@<my-organization> 합니다.
    • Python 휠 파일의 표시 설명으로 <my-package-description>를 대체합니다.

아티팩트 번들 구성 추가

  1. artifacts 매핑 구성을 databricks.yml에 추가하여 whl 아티팩트를 빌드하십시오.

    Poetry

    이 구성은 poetry build 명령을 실행하고 파일 경로가 pyproject.toml 파일과 동일한 디렉터리에 databricks.yml 있음을 나타냅니다.

    Note

    Python 휠 파일을 이미 빌드했고 이제 배포만 하려는 경우, artifacts 매핑을 생략하여 다음 번들 구성 파일을 수정하십시오. 그러면 Databricks CLI는 Python 휠 파일이 이미 빌드되었다고 가정하고 배열의 libraries 항목에 whl 지정된 파일을 자동으로 배포합니다.

    bundle:
  name: my-wheel-bundle

artifacts:
  default:
    type: whl
    build: poetry build
    path: .

resources:
  jobs:
    wheel-job:
      name: wheel-job
      tasks:
        - task_key: wheel-task
          new_cluster:
            spark_version: 13.3.x-scala2.12
            node_type_id: Standard_DS3_v2
            data_security_mode: USER_ISOLATION
            num_workers: 1
          python_wheel_task:
            entry_point: main
            package_name: my_package
          libraries:
            - whl: ./dist/*.whl

targets:
  dev:
    workspace:
    host: <workspace-url>

    Setuptools

    이 구성은 setuptools 명령을 실행하고 파일 경로가 setup.py 파일과 동일한 디렉터리에 databricks.yml 있음을 나타냅니다.

    bundle:
  name: my-wheel-bundle

artifacts:
  default:
    type: whl
    build: python3 setup.py bdist wheel
    path: .

resources:
  jobs:
    wheel-job:
      name: wheel-job
      tasks:
        - task_key: wheel-task
          new_cluster:
            spark_version: 13.3.x-scala2.12
            node_type_id: Standard_DS3_v2
            data_security_mode: USER_ISOLATION
            num_workers: 1
          python_wheel_task:
            entry_point: main
            package_name: my_package
          libraries:
            - whl: ./dist/*.whl

targets:
  dev:
    workspace:
    host: <workspace-url>