Notebook 범위의 Python 라이브러리

Notebook 범위 라이브러리를 사용하면 Notebook에 특정한 사용자 지정 Python 환경을 만들기, 수정, 저장, 재사용 및 공유할 수 있습니다. Notebook 범위 라이브러리를 설치하면 현재 Notebook 및 해당 Notebook과 연결된 모든 작업만 해당 라이브러리에 액세스할 수 있습니다. 동일한 클러스터에 연결된 다른 Notebooks는 영향을 받지 않습니다.

Notebook 범위 라이브러리는 세션 간에 지속되지 않습니다. 각 세션이 시작될 때 또는 Notebook이 클러스터에서 분리될 때마다 Notebook 범위 라이브러리를 다시 설치해야 합니다.

Notebook 범위 라이브러리를 설치하는 방법에는 두 가지가 있습니다.

  • Notebook에서 %pip 매직 명령을 실행합니다. %pip 명령은 Databricks Runtime 7.1 이상 및 Databricks Runtime 6.4 ML 이상에서 지원됩니다. Databricks는 새 워크로드에 이 방법을 사용하는 것이 좋습니다. 이 문서에서는 이러한 매직 명령을 사용하는 방법을 설명합니다.
  • Azure Databricks 라이브러리 유틸리티를 사용합니다. 라이브러리 유틸리티는 Databricks Runtime에서만 지원되며 Databricks Runtime ML 또는 Databricks Runtime for Genomics에서는 지원되지 않습니다. 라이브러리 유틸리티(dbutils.library)를 참조하세요.

클러스터에 연결된 모든 Notebooks의 라이브러리를 설치하려면 작업 영역 또는 클러스터 설치 라이브러리를 사용합니다.

요구 사항

매직 명령을 사용하는 Notebook 범위 라이브러리는 Databricks Runtime 7.1 이상, Databricks Runtime 7.1 ML 이상 및 Genomics용 Databricks Runtime 7.1 이상에서 기본적으로 사용됩니다.

또한 Databricks Runtime 6.4 ML~7.0 ML 및 Genomics용 Databricks Runtime 6.4~Genomics용 Databricks Runtime 7.0의 구성 설정을 사용할 수도 있습니다. Spark 구성spark.databricks.conda.condaMagic.enabledtrue로 설정합니다.

Databricks Runtime 7.4 ML 또는 Databricks Runtime 7.4 for Genomics 이하를 실행하는 높은 동시성 클러스터에서 Notebook 범위 라이브러리는 테이블 액세스 제어 또는 자격 증명 통과와 호환되지 않습니다. 대안은 Databricks Runtime 클러스터에서 라이브러리 유틸리티(dbutils.library)를 사용하거나 클러스터를 Databricks Runtime 7.5 ML 또는 Databricks Runtime 7.5 for Genomics 이상으로 업그레이드하는 것입니다.

Databricks Connect와 함께 Notebook 범위 라이브러리를 사용하려면 라이브러리 유틸리티(dbutils.library)를 사용해야 합니다.

드라이버 노드

Notebook 범위 라이브러리를 사용하면 실행기 노드에서 환경을 일관되게 유지하기 위해 작동하므로 드라이버 노드에 더 많은 트래픽이 발생할 수 있습니다.

10개 이상의 노드가 있는 클러스터를 사용하는 경우 Databricks는 드라이버 노드에 대한 최소 요구 사항으로 다음 사양을 권장합니다.

  • 100노드 CPU 클러스터의 경우 Standard_DS5_v2를 사용합니다.
  • 10노드 GPU 클러스터의 경우 Standard_NC12를 사용합니다.

더 큰 클러스터의 경우 더 큰 드라이버 노드를 사용합니다.

%pip를 사용하여 Notebook 범위 라이브러리 설치

중요

  • Notebook의 시작 부분에 모든 %pip 명령을 배치해야 합니다. Notebook 상태는 환경을 수정하는 모든 %pip 명령 후에 다시 설정됩니다. Notebook에서 Python 메서드 또는 변수를 만든 다음 이후 셀에서 %pip 명령을 사용하면 메서드나 변수가 손실됩니다.
  • %pip를 사용하여 핵심 Python 패키지(예: IPython)를 업그레이드, 수정 또는 제거하면 일부 기능이 예상대로 작동하지 않을 수 있습니다. 예를 들어 IPython 7.21 이상은 Databricks Runtime 8.1 이하와 호환되지 않습니다. 이러한 문제가 발생하면 Notebook을 분리했다가 다시 연결하거나 클러스터를 다시 시작하여 환경을 다시 설정합니다.

%pip 명령을 사용하여 라이브러리 관리

%pip 명령은 pip 명령과 동일하며 동일한 API를 지원합니다. 다음 섹션에서는 %pip 명령을 사용하여 환경을 관리하는 방법의 예를 보여 줍니다. pip를 사용하여 Python 패키지를 설치하는 방법에 대한 자세한 내용은 pip 설치 설명서 및 관련 페이지를 참조하세요.

이 섹션에서는 다음 작업을 수행합니다.

%pip를 사용하여 라이브러리 설치

%pip install matplotlib

%pip를 사용하여 휠 패키지 설치

%pip install /path/to/my_package.whl

%pip를 사용하여 라이브러리 제거

참고

Databricks Runtime에 포함된 라이브러리 또는 클러스터 라이브러리로 설치된 라이브러리는 제거할 수 없습니다. Databricks Runtime에 포함된 버전이나 클러스터에 설치된 것과 다른 라이브러리 버전을 설치한 경우 %pip uninstall을 사용하여 라이브러리를 Databricks Runtime의 기본 버전이나 클러스터에 설치된 버전으로 되돌릴 수 있지만 %pip 명령을 사용하여 Databricks Runtime에 포함되거나 클러스터에 설치된 라이브러리 버전을 제거할 수 없습니다.

%pip uninstall -y matplotlib

-y 옵션은 필수입니다.

%pip를 사용하여 버전 제어 시스템에서 라이브러리 설치

%pip install git+https://github.com/databricks/databricks-cli

URL에 매개 변수를 추가하여 버전 또는 git 하위 디렉터리와 같은 항목을 지정할 수 있습니다. 자세한 내용과 다른 버전 제어 시스템 사용 예는 VCS 지원을 참조하세요.

%pip를 사용하여 Databricks 보안 비밀에서 관리하는 자격 증명으로 프라이빗 패키지 설치

Pip는 NexusArtifactory와 같은 프라이빗 버전 제어 시스템 및 프라이빗 패키지 리포지토리를 포함하여 기본 인증으로 프라이빗 원본에서 패키지 설치를 지원합니다. 비밀 관리는 인증 토큰과 비밀을 저장할 수 있는 Databricks Secrets API를 통해 사용할 수 있습니다. DBUtils API를 사용하여 Notebook의 보안 비밀에 액세스합니다. 매직 명령에서 $variables를 사용할 수 있습니다.

프라이빗 리포지토리에서 패키지를 설치하려면 --index-url 옵션을 사용하여 리포지토리 URL을 %pip install에 지정하거나 ~/.pip/pip.confpip 구성 파일에 추가합니다.

token = dbutils.secrets.get(scope="scope", key="key")
%pip install --index-url https://<user>:$token@<your-package-repository>.com/<path/to/repo> <package>==<version> --extra-index-url https://pypi.org/simple/

마찬가지로 매직 명령과 함께 비밀 관리를 사용하여 버전 제어 시스템에서 프라이빗 패키지를 설치할 수 있습니다.

token = dbutils.secrets.get(scope="scope", key="key")
%pip install git+https://<user>:$token@<gitprovider>.com/<path/to/repo>

%pip를 사용하여 DBFS에서 패키지 설치

%pip를 사용하여 DBFS에 저장된 프라이빗 패키지를 설치할 수 있습니다.

DBFS에 파일을 업로드하면 파일 이름이 자동으로 변경되어 공백, 마침표 및 하이픈이 밑줄로 바뀝니다. pip를 사용하려면 휠 파일 이름이 버전에서 마침표(예: 0.1.0)를 사용하고 공백이나 밑줄 대신 하이픈을 사용해야 합니다. %pip 명령을 사용하여 패키지를 설치하려면 이러한 요구 사항을 충족하도록 파일 이름을 변경해야 합니다.

%pip install /dbfs/mypackage-0.0.1-py3-none-any.whl

요구 사항 파일에 라이브러리 저장

%pip freeze > /dbfs/requirements.txt

파일 경로의 모든 하위 디렉터리가 이미 있어야 합니다. %pip freeze > /dbfs/<new-directory>/requirements.txt를 실행하는 경우 /dbfs/<new-directory> 디렉터리가 아직 없으면 명령이 실패합니다.

요구 사항 파일을 사용하여 라이브러리 설치

요구 사항 파일에는 pip를 사용하여 설치할 패키지 목록이 포함되어 있습니다. 요구 사항 파일을 사용하는 예는 다음과 같습니다.

%pip install -r /dbfs/requirements.txt

requirements.txt 파일에 대한 자세한 내용은 요구 사항 파일 형식을 참조하세요.

%conda 명령을 사용하여 라이브러리 관리

중요

%conda 명령은 더 이상 사용되지 않으며 Databricks Runtime ML 8.4 이후에는 더 이상 지원되지 않습니다. Databricks는 Notebook 범위 라이브러리를 관리하기 위해 %pip를 사용할 것을 권장합니다. conda를 통해서만 설치할 수 있는 Python 라이브러리가 필요한 경우 conda 기반 Docker 컨테이너를 사용하여 필요한 라이브러리를 사전 설치할 수 있습니다.

Anaconda Inc.는 2020년 9월에 anaconda.org 채널에 대한 서비스 약관을 업데이트했습니다. 새로운 서비스 약관에 따라 Anaconda의 패키지 및 배포에 의존하는 경우 상용 라이선스가 필요할 수 있습니다. 자세한 내용은 Anaconda Commercial Edition FAQ를 참조하세요. 모든 Anaconda 채널 사용에는 서비스 약관이 적용됩니다.

이 변경의 결과로 Databricks는 Conda 패키지 관리자에 대한 기본 채널 구성을 제거했습니다. 이는 주요 변경 내용입니다.

%conda 명령을 사용하여 패키지를 설치하거나 업데이트하려면 -c를 사용하여 채널을 지정해야 합니다. 또한 -c를 사용하여 채널을 지정하려면 %conda install%sh conda install의 모든 사용법을 업데이트해야 합니다. 채널을 지정하지 않으면 conda 명령이 PackagesNotFoundError와 함께 실패합니다.

%conda 명령은 conda 명령과 동일하며 아래에 언급된 몇 가지 제한 사항과 함께 동일한 API를 지원합니다. 다음 섹션에는 %conda 명령을 사용하여 환경을 관리하는 방법의 예가 포함되어 있습니다. conda를 사용하여 Python 패키지를 설치하는 방법에 대한 자세한 내용은 conda 설치 설명서를 참조하세요.

%conda 매직 명령은 Databricks Runtime에서 사용할 수 없습니다. Databricks Runtime ML 최대 Databricks Runtime ML 8.4 및 Databricks Runtime for Genomics에서만 사용할 수 있습니다. Databricks는 pip를 사용하여 라이브러리를 설치할 것을 권장합니다. 자세한 내용은 conda 및 pip 이해를 참조하세요.

메모장에서 %pip%conda 명령을 모두 사용해야 하는 경우 pip 및 conda 명령 간의 상호 작용을 참조하세요.

참고

다음 conda 명령은 %conda와 함께 사용할 때 지원되지 않습니다.

  • activate
  • create
  • init
  • run
  • env create
  • env remove

이 섹션에서는 다음 작업을 수행합니다.

%conda를 사용하여 라이브러리 설치

%conda install matplotlib -c conda-forge

%conda를 사용하여 라이브러리 제거

%conda uninstall matplotlib

환경 저장 및 재사용 또는 공유

클러스터에서 Notebook을 분리하면 환경이 저장되지 않습니다. 나중에 재사용하거나 다른 사람과 공유할 수 있도록 환경을 저장하려면 다음 단계를 따릅니다.

Databricks는 동일한 버전의 Databricks Runtime ML 또는 동일한 버전의 Databricks Runtime for Genomics를 실행하는 클러스터 간에만 환경을 공유할 것을 권장합니다.

  1. 환경을 conda YAML 사양으로 저장합니다.

    %conda env export -f /dbfs/myenv.yml
    
  2. conda env update를 사용하여 파일을 다른 Notebook으로 가져옵니다.

    %conda env update -f /dbfs/myenv.yml
    

Notebook의 Python 환경 나열

Notebook과 연결된 Python 환경을 표시하려면 %conda list를 사용합니다.

%conda list

pipconda 명령 간 상호 작용

충돌을 방지하려면 pip 또는 conda를 사용하여 Python 패키지 및 라이브러리를 설치할 때 다음 가이드라인을 따릅니다.

  • API 또는 클러스터 UI를 사용하여 설치된 라이브러리는 pip를 사용하여 설치됩니다. API 또는 클러스터 UI에서 라이브러리가 설치된 경우 Notebook 범위 라이브러리를 설치할 때 %pip 명령만 사용해야 합니다.
  • 클러스터에서 Notebook 범위 라이브러리를 사용하는 경우 해당 클러스터에서 실행되는 초기화 스크립트는 conda 또는 pip 명령을 사용하여 라이브러리를 설치할 수 있습니다. 그러나 init 스크립트에 pip 명령이 포함된 경우 Notebooks에서 %pip 명령만 사용합니다(%conda 아님).
  • pip 명령을 단독으로 사용하거나 conda 명령을 단독으로 사용하는 것이 가장 좋습니다. conda를 사용하여 일부 패키지를 설치하고 pip를 사용하여 일부 패키지를 설치해야 하는 경우 먼저 conda 명령을 실행한 다음 pip 명령을 실행합니다. 자세한 내용은 Conda 환경에서 Pip 사용을 참조하세요.

질문과 대답(FAQ)

클러스터 UI/API에서 설치된 라이브러리는 Notebook 범위 라이브러리와 어떻게 상호 작용하나요?

클러스터 UI 또는 API에서 설치된 라이브러리는 클러스터의 모든 Notebooks에서 사용할 수 있습니다. 이러한 라이브러리는 pip를 사용하여 설치됩니다. 따라서 클러스터 UI를 사용하여 라이브러리를 설치하는 경우 Notebooks에서 %pip 명령만 사용합니다.

init 스크립트를 사용하여 설치된 라이브러리는 Notebook 범위 라이브러리와 어떻게 상호 작용하나요?

init 스크립트를 사용하여 설치된 라이브러리는 클러스터의 모든 Notebooks에서 사용할 수 있습니다.

Databricks Runtime ML 또는 Databricks Runtime for Genomics를 실행하는 클러스터에서 Notebook 범위 라이브러리를 사용하는 경우 클러스터에서 실행되는 초기화 스크립트는 conda 또는 pip 명령을 사용하여 라이브러리를 설치할 수 있습니다. 그러나 init 스크립트에 pip 명령이 포함된 경우 Notebooks에서는 %pip 명령만 사용합니다.

예를 들어 이 Notebook 코드 조각은 모든 클러스터 노드에 fast.ai 패키지를 설치하는 스크립트를 생성합니다.

dbutils.fs.put("dbfs:/home/myScripts/fast.ai", "conda install -c pytorch -c fastai fastai -y", True)

작업 Notebooks에서 %pip%conda 명령을 사용할 수 있나요?

예.

R 또는 Scala Notebooks에서 %pip%conda 명령을 사용할 수 있나요?

예, Python 매직 셀에서.

%sh pip 또는 %sh conda를 사용할 수 있나요?

Databricks는 %pip 사용과 호환되지 않기 때문에 %sh pip 사용을 권장하지 않습니다.

%conda 명령을 사용하여 R 패키지를 업데이트할 수 있나요?

아니요.

알려진 문제

  • Databricks Runtime 7.0 ML 이하 및 Databricks Runtime 7.0 for Genomics 이하에서 등록된 UDF가 %pip 또는 %conda를 사용하여 설치된 Python 패키지에 종속되는 경우 %sql 셀에서 작동하지 않습니다. 대신 Python 명령 셸에서 spark.sql을 사용합니다.
  • Databricks Runtime 7.2 ML 이하 및 Databricks Runtime 7.2 for Genomics 이하에서 %conda를 사용하여 Notebook 환경을 업데이트하면 작업자 Python 프로세스에서 새 환경이 활성화되지 않습니다. PySpark UDF 함수가 Conda 환경 내부에 설치된 리소스를 사용하는 타사 함수를 호출하는 경우 문제가 발생할 수 있습니다.
  • %conda env update를 사용하여 Notebook 환경을 업데이트할 때 패키지 설치 순서는 보장되지 않습니다. 이로 인해 horovod.tensorflow 또는 horovod.torch를 각각 사용하려면 horovod보다 먼저 tensorflowtorch를 설치해야 하는 horovod 패키지에 문제가 발생할 수 있습니다. 이 경우 horovod 패키지를 제거하고 종속성이 설치되었는지 확인한 후 다시 설치합니다.
  • Databricks Runtime 10.3 이하에서는 Notebook 범위 라이브러리가 일괄 스트리밍 작업과 호환되지 않습니다. Databricks에서는 클러스터 라이브러리 또는 IPython 커널을 대신 사용하는 것이 좋습니다.