AI 런타임과 함께 커스텀 도커 이미지를 사용하세요

Important

이 기능은 베타 버전으로 제공됩니다. 이를 사용하려면 작업 공간 관리자가 작업 공간 Previews 페이지에서AI 런타임 베타 기능과Databricks 아티팩트 레지스트리 미리보기를 활성화해야 합니다.

AI 런타임은 Artifact Registry에 저장된 맞춤형 Docker 컨테이너 이미지를 실행할 수 있습니다. 필요한 경우 사용자 지정 이미지를 사용합니다.

  • environment.dependencies로 설치할 수 없는 시스템 라이브러리 또는 복잡한 종속성.
  • 개발, 연구, 생산 전반에 걸쳐 재현 가능한 환경입니다.
  • 플랫폼이나 보안팀이 만든 사적인 조직 승인 이미지입니다.

사전 요구 사항

이미지를 아티팩트 레지스트리로 푸시하세요

AI 런타임으로 커스텀 이미지를 사용하기 전에, 작업 파일을 제출하는 동일한 작업 공간에 Artifact Registry에 저장하세요.

  1. 이미지를 위한 Unity 카탈로그 카탈로그와 스키마를 생성하거나 선택하세요.

  2. ' Artifact Registry로 시작 하기'를 따라 Docker 인증을 설정하고, 필요한 권한을 부여하며, 이미지를 푸시하세요.

  3. 이미지 유니티 카탈로그 이름은 다음과 같은 형식으로 표시되어 있습니다:

    <catalog>.<schema>.<image>:<tag>

    main.ml.training:v1을 예로 들 수 있습니다. 워크로드 설정에 레지스트리 호스트네임을 포함하지 마세요.

Tip

또는 Databricks CLI에서 databricks air images push helper 명령어를 사용할 수도 있습니다.

워크로드에서 Docker 이미지를 사용하세요

워크로드 YAML environment.unity_catalog_image에서 이미지 Unity 카탈로그 이름을 다음과 같이 지정하세요:

experiment_name: my-dcs-training
environment:
  unity_catalog_image: main.ml.training:v1
compute:
  num_accelerators: 1
  accelerator_type: GPU_1xA10
command: python /app/train.py

이 예제는 이미지에서 /app의 train.py를 실행합니다. 이미지를 재구성하지 않고 별도로 애플리케이션 코드를 업로드하려면 업로드된 애플리케이션 코드 실행(Runpeded application code)을 참조하세요.

사용자 고유의 Docker 이미지를 environment.dependenciesenvironment.version 가져오는 경우 지원되지 않습니다. 두 필드 중 하나를 사용하여 지정하면 environment.unity_catalog_image 오류가 트리거됩니다. 추가 종속성이 있는 경우 대신 Dockerfile에 패키지를 설치합니다.

워크로드를 제출합니다.

databricks air run -f workload.yaml -p my-databricks-profile

프로필은 이미지가 저장된 동일한 작업 공간에 인증되어야 합니다.

컨테이너에 삽입된 환경 변수

AI 런타임은 런타임 시 모든 컨테이너에 다음 환경 변수를 삽입합니다.

  • CODE_SOURCE_PATH: code_source이 구성된 경우 업로드된 애플리케이션 코드의 경로.
  • NUM_NODES: 총 노드 수.
  • LOCAL_WORLD_SIZE: 노드당 GPU 수.
  • WORLD_SIZE: 총 프로세스 수.
  • POD_RANK: 현재 노드 순위 (0-인덱스). 또한 NODE_RANK로 삽입됩니다.
  • LOCAL_ADDR: 로컬 노드 IP(다중 노드 전용).
  • MASTER_ADDR: 랭크-0 조정 주소(다중 노드 전용).
  • MASTER_PORT: 랭크-0 조정 포트(멀티노드 전용).

예제

다음 예시들은 업로드된 애플리케이션 코드와 분산 학습을 사용자 지정 이미지로 실행하는 방법을 보여줍니다.

업로드한 애플리케이션 코드를 실행하세요

code_source를 사용하여 이미지와 별도로 애플리케이션 코드를 업로드하세요. 이미지를 다시 만들지 않고도 코드를 편집하고 재제출할 수 있습니다. 코드의 Python과 시스템 의존성을 이미지에 설치하세요.

train.py 옆의 로컬 workload.yaml 디렉터리에 src을(를) 배치하세요. 다음 구성은 train.py를 업로드하고 사용자 지정 이미지 내에서 해당 src를 실행합니다:

experiment_name: my-dcs-uploaded-code
environment:
  unity_catalog_image: main.ml.training:v1
compute:
  num_accelerators: 1
  accelerator_type: GPU_1xA10
code_source:
  root_path: ./src
command: |-
  cd "$CODE_SOURCE_PATH"
  python3 train.py

root_path는 workload.yaml를 기준으로 확인됩니다. AI 런타임은 컨테이너에서 $CODE_SOURCE_PATH를 업로드된 디렉터리의 경로로 설정합니다. 코드 소스 옵션은 code_source 를 참조하세요.

RDMA 지원 다중 노드 H100

AWS p5 인스턴스에서 전체 네트워크 대역폭이 필요한 다중 노드 H100 작업의 경우 NCCL 및 EFA가 미리 구성된 Databricks 기본 이미지 중 하나에 이미지를 기반으로 합니다.

experiment_name: my-dcs-distributed
environment:
  unity_catalog_image: main.ml.training:v1
compute:
  num_accelerators: 16 # 2 nodes × 8 H100
  accelerator_type: GPU_8xH100
command: |-
  torchrun \
    --nnodes="${NUM_NODES}" \
    --nproc_per_node="${LOCAL_WORLD_SIZE}" \
    --node_rank="${POD_RANK}" \
    --rdzv_endpoint="${MASTER_ADDR}:${MASTER_PORT}" \
    /app/train.py

사용자 고유의 이미지 빌드

자체 이미지를 빌드할 경우 Databricks는 코딩 에이전트와 함께 databricks-ai-runtime skill을 사용하거나 Databricks 기본 이미지에서 시작할 것을 권장합니다.

코딩 에이전트 사용

처음부터 빌드, CUDA/NCCL/EFA 호환성, 일반적인 문제 및 빌드 전 검사 목록을 포함하여 단계별 Dockerfile 지침에 대한 databricks-ai-runtime Claude Code 기술을 설치합니다. 이 기술을 사용하려면 Databricks CLI 버전 1.0.0 이상이 필요합니다.

databricks aitools install --skills databricks-ai-runtime --experimental

Databricks 기본 이미지

Databricks는 CUDA, NCCL 및 클라우드별 네트워킹(AWS EFA 또는 Azure databricksruntime/air InfiniBand)이 미리 구성된 상태에서 Docker Hub 기본 이미지를 게시합니다.

태그 Variant CUDA 사용 시기
dcs-base-azure-runtime Runtime 12 미리 빌드된 휠만 설치
dcs-base-azure-devel Devel 12 CUDA 확장 기능 컴파일(nvcc 필요)

다음 Dockerfile은 Databricks 기본 이미지에 PyTorch를 추가합니다. 기본 이미지는 /opt/venv에서 관리되는 uv의 Python을 제공합니다. uv pip install 기본적으로 그 환경을 타겟팅합니다. 다른 환경을 사용하려면 실행 uv pip install전에 venv를 생성하고 활성화하세요.

이미지에 학습 스크립트를 포함하려면 Dockerfile 옆에 배치 train.py 하세요. Dockerfile은 이를 /app/train.py에 복사합니다. 애플리케이션 코드를 code_source업로드할 경우, COPY 지침을 생략하고 대신 소스 디렉터리에 train.py 보관하세요.

FROM databricksruntime/air:dcs-base-azure-runtime

RUN uv pip install --no-cache \
    torch==2.6.0 torchvision==0.21.0 torchaudio==2.6.0

RUN uv pip install --no-cache \
    transformers==4.45.0 \
    accelerate==0.34.0 \
    'mlflow>=3.6'

COPY ./train.py /app/train.py

이미지를 로컬에서 구축하세요:

docker build --platform linux/amd64 -t my-training-image:v1 .

그 다음 ' Get started with Artifact Registry '를 따라 이미지를 태그하고 아티팩트 레지스트리로 푸시하세요. 워크로드 YAML에서 결과로 얻은 environment.unity_catalog_image 이름을 <catalog>.<schema>.<image>:<tag>로 사용하세요.

Tip

또는 Databricks CLI에서 databricks air images push도우미 명령을 사용한 후 대화형 프롬프트를 따르세요.

Limitations

  • 이미지는 작업을 제출하는 작업 공간의 아티팩트 레지스트리에 저장되어야 합니다.
  • 이미지 크기는 20GB 미만이어야 합니다.
  • WORKDIR 는 런타임에 적용되지 않습니다. 이미지에 포함된 파일에는 절대 경로를 사용하세요. 예를 들어 python /app/train.py아니라 python train.py사용합니다.
  • environment.dependencies와 함께 environment.version 또는 environment.unity_catalog_image을 사용할 수 없습니다. 이미지에 있는 것 이상으로 추가 패키지가 필요한 경우 Dockerfile에 추가해야 합니다.

Troubleshooting

레지스트리 관련 인증, 권한, 이미지 푸시 또는 이미지 발견 오류에 대해서는 '아티팩트 레지스트리 문제 해결'을 참조하세요.

ssl. 의존성을 로드할 때 SSLError

예를 들어 라이브러리에서 SSL 컨텍스트를 만들려고 할 때 OpenSSL 오류로 런타임에 사용자 지정 이미지가 실패할 수 있습니다.

ssl.SSLError: [CRYPTO] unknown error (_ssl.c:3076)

huggingface_hub와 같이 네트워크 연결을 여는 라이브러리를 가져오는 동안 오류가 발생하여 해당 라이브러리가 로드되지 못합니다.

이는 AI 런타임 워크로드가 연방 정보 처리 표준(FIPS)이 활성화된 호스트에서 실행되기 때문입니다. 이미지의 암호화 라이브러리가 FIPS 규격이 아닌 경우 OpenSSL이 FIPS 모드에서 초기화되지 않으므로 SSL 컨텍스트를 만드는 데 실패합니다.

권장 솔루션:

엔터프라이즈, 정부, 의료 및 재무 워크로드는 종종 FedRAMP, CMMC 또는 HIPAA 감사에 대한 FIPS 140-2 또는 140-3 규정 준수에 의존합니다. 워크로드가 FIPS 규격으로 유지되어야 하는 경우 FIPS 규격 암호화 라이브러리를 사용하여 이미지를 빌드합니다.

워크로드에 FIPS 규정 준수가 필요하지 않은 경우 환경 변수OPENSSL_FORCE_FIPS_MODE를 .로 설정하여 FIPS 모드를 0 사용하지 않도록 설정할 수 있습니다. 이렇게 하면 규정 준수 요구 사항을 자동으로 위반할 수 있습니다.

FIPS 모드를 비활성화하려면 워크로드 YAML의 env_variables 아래에서 설정하세요:

env_variables:
  OPENSSL_FORCE_FIPS_MODE: '0'

또는 이미지를 사용하는 모든 워크로드에 적용되도록 Dockerfile에서 변수를 설정합니다.

ENV OPENSSL_FORCE_FIPS_MODE=0

종속성이 로드되면 워크로드를 다시 제출하고 SSL 오류가 더 이상 나타나지 않는지 확인합니다.

추가 리소스

  • 에 마지막으로 업데이트됨