ML Diagnostics SDK 시작하기

ML 진단 Python SDK는 ML 워크로드와 통합되어 Google Cloud에서 워크로드 측정항목, 구성, 프로필을 수집하고 관리할 수 있습니다. 이 가이드에서는 머신러닝 실행을 만들고, 워크로드 측정항목과 구성을 수집 및 관리하고, 관리형 XProf 리소스를 배포하고, 프로그래매틱 및 주문형 프로필 캡처를 사용 설정하는 방법을 보여줍니다.

ML Diagnostics SDK 사용에 관한 자세한 내용은 google-cloud-mldiagnostics 저장소를 참고하세요.

ML Diagnostics SDK 설치

google-cloud-mldiagnostics 라이브러리를 설치합니다.

pip install google-cloud-mldiagnostics

ML 워크로드 코드에서 다음 패키지를 가져옵니다.

from google_cloud_mldiagnostics import machinelearning_run
from google_cloud_mldiagnostics import metrics
from google_cloud_mldiagnostics import xprof

Cloud Logging 사용 설정

SDK는 표준 Python logging 모듈을 사용하여 측정항목과 구성 정보를 출력합니다. 이러한 로그를 Cloud Logging으로 라우팅하려면 google-cloud-logging 라이브러리를 설치하고 구성하세요. 이를 통해 Google Cloud 콘솔 내에서 SDK 로그, 기록된 측정항목, 자체 애플리케이션 로그를 볼 수 있습니다.

google-cloud-logging 라이브러리를 설치합니다.

pip install google-cloud-logging

Cloud Logging 핸들러를 Python 루트 로거에 연결하여 스크립트에서 로깅을 구성합니다. Python 스크립트의 시작 부분에 다음 줄을 추가합니다.

  import logging
  import google.cloud.logging

  # Instantiate a Cloud Logging client
  logging_client = google.cloud.logging.Client()

  # Attach the Cloud Logging handler to the Python root logger
  logging_client.setup_logging()

  # Standard logging calls will go to Cloud Logging
  logging.info("SDK logs and application logs will appear in Cloud Logging.")

상세 로깅 사용 설정

기본적으로 로깅 수준은 INFO로 설정됩니다. 머신러닝 실행 세부정보와 같은 SDK의 자세한 로그를 수신하려면 setup_logging()를 호출한 후 로깅 수준을 DEBUG로 설정하세요.

import logging
import google.cloud.logging

logging_client = google.cloud.logging.Client()
logging_client.setup_logging()
logging.getLogger().setLevel(logging.DEBUG) # Enable DEBUG level logs

logging.debug("This is a debug message.")
logging.info("This is an info message.")

DEBUG를 사용 설정하면 Cloud Logging에서 추가 SDK 진단을 받을 수 있습니다. 예를 들면 다음과 같습니다.

DEBUG:google_cloud_mldiagnostics.core.global_manager:current run details:
{'name': 'projects/my-gcp-project/locations/us-central1/mlRuns/my-run-12345',
'gcs_path': 'gs://my-bucket/profiles', ...}

머신러닝 실행 만들기

ML 진단 플랫폼을 사용하려면 먼저 머신러닝 실행을 만들어야 합니다. 여기에는 로깅을 실행하고, 측정항목을 수집하고, 프로필 추적을 사용 설정하기 위해 SDK로 ML 워크로드를 계측하는 작업이 포함됩니다.

다음은 Cloud Logging을 초기화하고, 머신러닝 실행 (MLRun)을 만들고, 측정항목을 기록하고, 프로필을 캡처하는 기본 예입니다.

import logging
import os
import google.cloud.logging
from google_cloud_mldiagnostics import machinelearning_run, metrics, xprof, metric_types

# 1. Set up Cloud Logging
# Make sure to pip install google-cloud-logging
logging_client = google.cloud.logging.Client()
logging_client.setup_logging()
# Optional: Set logging level to DEBUG for more detailed SDK logs
logging.getLogger().setLevel(logging.DEBUG)

# 2. Define and start machinelearning run
try:
    run = machinelearning_run(
          name="<run_name>",
          run_group="<run_group>",
          configs={ "epochs": 100, "batch_size": 32 },
          project="<some_project>",
          region="<some_zone>",
          gcs_path="gs://<some_bucket>",
          on_demand_xprof=True,
        )
    logging.info(f"MLRun created: {run.name}")

    # 3. Collect metrics during your run
    metrics.record(metric_types.MetricType.LOSS, 0.123, step=1)
    logging.info("Loss metric recorded.")

    # 4. Capture profiles programmatically
    with xprof():
        # ... your code to profile here ...
        pass
    logging.info("Profile captured.")

except Exception as e:
    logging.error(f"Error during MLRun: {e}", exc_info=True)

코드 예시에서는 다음 변수를 사용합니다.

변수	요구사항	설명
name	필수	특정 실행의 식별자입니다. SDK는 실행 이름이 고유하도록 machine-learning-run-id를 자동으로 만듭니다.
run_group	선택사항	동일한 실험에 속하는 여러 실행을 그룹화하는 데 도움이 되는 식별자입니다. 예를 들어 TPU 슬라이스 크기 스위프와 연결된 모든 실행은 동일한 그룹에 속할 수 있습니다.
project	선택사항	지정하지 않으면 프로젝트가 Google Cloud CLI에서 추출됩니다.
region	필수	us-east5를 제외한 모든 클러스터 디렉터 위치가 지원됩니다. 이 플래그는 각 명령어의 인수로 설정하거나 gcloud config set compute/region 명령어로 설정할 수 있습니다.
configs	선택사항	실행의 구성 매개변수가 포함된 키-값 쌍입니다. 구성이 정의되지 않으면 기본 소프트웨어 및 시스템 구성이 표시되지만 ML 워크로드 구성은 표시되지 않습니다.
gcs_path	조건부 필수	모든 프로필이 저장되는 Google Cloud 스토리지 위치입니다. 예를 들면 gs://my-bucket 또는 gs://my-bucket/folder1입니다. SDK가 프로필 캡처에 사용되는 경우에만 필요합니다.
on-demand-xprof	선택사항	주문형 프로파일링을 사용 설정하기 위해 포트 9999에서 xprofz daemon를 시작합니다. 동시에 발생하지 않는 한 동일한 코드에서 온디맨드 프로파일링과 프로그래매틱 프로파일링을 모두 사용 설정할 수 있습니다.

다음 구성은 SDK에 의해 자동으로 수집되므로 machinelearning_run 내에서 지정할 필요가 없습니다.

• 소프트웨어 구성: 프레임워크, 프레임워크 버전, XLA 플래그
• 시스템 구성: 기기 유형, 슬라이스 수, 슬라이스 크기, 호스트 수입니다.

프로젝트 및 리전 정보는 머신러닝 실행 메타데이터로 저장됩니다. 머신러닝 실행에 사용되는 리전은 워크로드 실행에 사용되는 리전과 일치하지 않아도 됩니다.

구성 쓰기

많은 워크로드에는 machinelearning_run 정의에 직접 정의하기에는 너무 많은 구성이 포함되어 있습니다. 이러한 경우 JSON 또는 YAML을 사용하여 실행에 구성을 작성할 수 있습니다.

import yaml
import json

# Read the YAML file
with open('config.yaml', 'r') as yaml_file:
  # Parse YAML into a Python dictionary
  yaml_data = yaml.safe_load(yaml_file)

# Define machinelearning run
machinelearning_run(
  name="RUN_NAME",
  run_group="GROUP_NAME",
  configs=yaml_data,
  project="PROJECT_NAME",
  region="ZONE",
  gcs_path="gs://BUCKET_NAME",
)

측정항목 수집

SDK를 사용하여 모델 측정항목, 모델 성능 측정항목, 시스템 측정항목을 수집할 수 있습니다. 이러한 측정항목을 평균값으로, 시계열 차트로 시각화할 수 있습니다.

SDK는 측정항목을 기록하는 두 가지 함수를 제공합니다. 개별 데이터 포인트를 캡처하는 metrics.record()와 단일 배치에서 여러 측정항목을 기록하는 metrics.record_metrics()입니다. 두 함수 모두 측정항목을 Cloud Logging에 작성하여 시각화 및 분석을 지원합니다.

단일 측정항목을 기록하려면 다음 단계를 따르세요.

# Record a metric only with time as the x-axis
metrics.record(metric_types.MetricType.LOSS, 0.123)

# Record a metric with time and step as the x-axis
metrics.record(metric_types.MetricType.LOSS, 0.123, step=1)

여러 측정항목을 기록하려면 다음 단계를 따르세요.

from google_cloud_mldiagnostics import metric_types
# User codes
# machinelearning_run should be called
# ......

for step in range(num_steps):
  if (step + 1) % 10 == 0:
    metrics.record_metrics([
        # Model quality metrics
        {"metric_name": metric_types.MetricType.LEARNING_RATE, "value": step_size},
        {"metric_name": metric_types.MetricType.LOSS, "value": loss},
        {"metric_name": metric_types.MetricType.GRADIENT_NORM, "value": gradient},
        {"metric_name": metric_types.MetricType.TOTAL_WEIGHTS, "value": total_weights},
        # Model performance metrics
        {"metric_name": metric_types.MetricType.STEP_TIME, "value": step_time},
        {"metric_name": metric_types.MetricType.THROUGHPUT, "value": throughput},
        {"metric_name": metric_types.MetricType.LATENCY, "value": latency},
        {"metric_name": metric_types.MetricType.TFLOPS, "value": tflops},
        {"metric_name": metric_types.MetricType.MFU, "value": mfu},
    ], step=step+1)

다음 시스템 측정항목은 SDK가 libTPU, psutil, JAX 라이브러리에서 자동으로 수집합니다.

• TPU TensorCore 사용률
• TPU 가동 주기
• HBM 사용률
• 호스트 CPU 사용률
• 호스트 메모리 사용률

이러한 측정항목을 수동으로 지정할 필요가 없습니다. 이러한 시스템 측정항목의 기본 x축은 시간입니다.

다음 사전 정의된 측정항목 키는 할당된 경우Google Cloud 콘솔에 자동으로 표시됩니다. 이러한 측정항목은 자동으로 계산되지 않으며 값을 할당할 수 있는 사전 정의된 키입니다.

• 모델 품질 측정항목 키: LEARNING_RATE, LOSS, GRADIENT_NORM, TOTAL_WEIGHTS
• 모델 성능 측정항목 키: STEP_TIME, THROUGHPUT, LATENCY, MFU, TFLOPS.

사전 정의된 측정항목과 기타 사용자 정의 측정항목은 x축을 time 또는 time 및 step으로 기록할 수 있습니다. 워크로드에서 맞춤 측정항목을 기록할 수 있습니다.

다음 예에서는 워크로드의 단일 측정항목을 캡처합니다. 이 측정항목은 특정 머신러닝 실행의 모델 측정항목 탭에서 볼 수 있습니다.

metrics.record("custom_metrics_1", step_size, step=step + 1)

한 번의 호출로 여러 측정항목을 기록하려면 record_metrics 메서드를 사용하세요. 예를 들면 다음과 같습니다.

metrics.record_metrics([
        # Model quality metrics
        {"metric_name": metric_types.MetricType.LEARNING_RATE, "value": step_size},
        {"metric_name": metric_types.MetricType.LOSS, "value": loss},
        {"metric_name": metric_types.MetricType.GRADIENT_NORM, "value": gradient},
        {"metric_name": metric_types.MetricType.TOTAL_WEIGHTS, "value": total_weights},
        # Model performance metrics
        {"metric_name": metric_types.MetricType.STEP_TIME, "value": step_time},
        {"metric_name": metric_types.MetricType.THROUGHPUT, "value": throughput},
        {"metric_name": metric_types.MetricType.LATENCY, "value": latency},
        {"metric_name": metric_types.MetricType.TFLOPS, "value": tflops},
        {"metric_name": metric_types.MetricType.MFU, "value": mfu},
     # Custom metrics
     {"custom_metrics_1", "value":<value>},
     {"custom_metrics_2", "value":<value>},
     {"avg_mtp_acceptance_rate_percent", "value":<value>},
     {"dpo_reward_accuracy", "value":<value>},
    ], step=step+1)

프로필 캡처

프로그래매틱 캡처 또는 온디맨드 캡처 (수동 캡처)를 사용하여 ML 워크로드의 XProf 프로필을 캡처할 수 있습니다. 프로그래매틱 캡처는 프로파일링 명령어를 머신러닝 코드에 직접 삽입하고 데이터 기록을 시작하고 중지할 시점을 명시적으로 지정하는 것을 말합니다. 온디맨드 캡처는 워크로드가 이미 활성 상태로 실행되는 동안 프로파일러를 트리거하는 실시간으로 발생합니다.

프로필을 캡처하는 SDK 명령어는 프레임워크에 구속되지 않습니다. 모든 프레임워크 수준 프로파일링 명령어가 ML 진단 프로파일링 명령어에 자동으로 통합되기 때문입니다. 즉, 프로파일링 코드가 사용하는 프레임워크에 종속되지 않습니다.

프로그래매틱 프로필 캡처

프로그래매틱 캡처를 사용하려면 모델 코드에 주석을 달고 프로필을 캡처할 위치를 지정해야 합니다. 일반적으로 몇 번의 학습 단계에 대한 프로필을 캡처하거나 모델 내의 특정 코드 블록을 프로파일링합니다.

다음과 같은 방법으로 ML Diagnostics SDK를 사용하여 프로그래매틱 프로필 캡처를 실행할 수 있습니다.

• API 기반 수집: start() 및 stop() 메서드로 프로파일링을 제어합니다.
• 데코레이터 기반 수집: 자동 프로파일링을 위해 @xprof(run)로 함수에 주석을 추가합니다.
• 컨텍스트 관리자: xprof()와 함께 사용하여 start() 및 stop() 작업을 자동으로 처리하는 범위 기반 프로파일링을 실행합니다.

모든 프레임워크에서 동일한 프로필 캡처 코드를 사용할 수 있습니다. 모든 프로파일 세션은 머신러닝 실행에 정의된 Cloud Storage 버킷에 캡처됩니다.

# Support collection via APIs
prof = xprof()  # Updates metadata and starts xprofz collector
prof.start()  # Collects traces to bucket
# ..... Your code execution here
# ....
prof.stop()

# Also supports collection via decorators
@xprof()
def abc(self):
    # does something
    pass

# Use xprof as a context manager to automatically start and stop collection
with xprof() as prof:
    # Your training or execution code here
    train_model()
    evaluate_model()

멀티 호스트 (프로세스) 프로파일링

프로그래매틱 프로파일링 중에 SDK는 ML 워크로드 코드가 실행되는 각 호스트 (프로세스)에서 프로파일링을 시작합니다. 노드 목록이 제공되지 않으면 모든 호스트가 포함됩니다.

# starts profiling on all nodes
prof = xprof()
prof.start()
# ...
prof.stop()

기본적으로 여러 호스트에서 session_id 인수가 없는 prof.start() 메서드를 호출하면 호스트별로 하나씩 별도의 추적 세션이 생성됩니다. XProf에서 여러 호스트의 트레이스를 단일 통합 멀티 호스트 세션으로 그룹화하려면 참여하는 모든 호스트에서 prof.start() 메서드가 동일한 session_id 인수로 호출되는지 확인하세요. 예를 들면 다음과 같습니다.

# Use the same session_id on all hosts to group traces
prof = xprof()
prof.start(session_id="profiling_session")
# ...
prof.stop()

특정 호스트의 프로파일링을 사용 설정하려면 다음 단계를 따르세요.

# starts profiling on node with index 0 and 2
prof = xprof(process_index_list=[0,2])
prof.start()
# ...
prof.stop()

주문형 프로필 캡처

애드혹 방식으로 프로필을 캡처하려는 경우이거나 프로그래매틱 프로필 캡처가 아직 사용 설정되지 않은 경우에는 온디맨드 프로필 캡처를 사용하세요. 온디맨드 캡처는 실행 중에 모델 측정항목에 문제가 표시되었을 때 해당 문제를 진단하기 위해 해당 시점의 프로필을 캡처하려는 경우에 유용합니다.

주문형 프로필 캡처를 사용 설정하려면 주문형 지원으로 실행을 구성하세요.

# Define machinelearning run
machinelearning_run(
    name="<run_name>",
    # specify where profiling data is stored
    gcs_path="gs://<bucket>",
    ...
    # enable on demand profiling, starts xprofz daemon on port 9999
    on_demand_xprof=True
)

모든 프레임워크에서 동일한 프로필 캡처 코드를 사용할 수 있습니다. 모든 프로파일 세션은 머신러닝 실행에 정의된 Cloud Storage 버킷에 캡처됩니다.

GKE에서 주문형 프로파일링을 하려면 GKE connection-operator 및 injection-webhook을 GKE 클러스터에 배포합니다. 이렇게 하면 머신러닝 실행이 실행 중인 GKE 노드를 찾을 수 있고 주문형 캡처 드롭다운이 이러한 노드를 자동으로 채울 수 있습니다. 자세한 내용은 GKE 클러스터 구성을 참고하세요.

GKE용 워크로드 패키징

Dockerfile을 사용하여 ML 진단 SDK를 사용하는 애플리케이션을 패키징할 수 있습니다. Cloud Logging 통합을 위해 google-cloud-logging 패키지를 설치합니다. 예를 들면 다음과 같습니다.

# Base image (user's choice, e.g., python:3.10-slim, or a base with ML frameworks)
FROM python:3.11-slim

# Install base utilities
RUN pip install --no-cache-dir --upgrade pip

# Install SDK and Logging client
# psutil is installed as a dependency of google-cloud-mldiagnostics
RUN pip install --no-cache-dir \
    google-cloud-mldiagnostics \
    google-cloud-logging

# Optional: For JAX/TPU workloads
# RUN pip install --no-cache-dir "jax[tpu]" -f https://storage.googleapis.com/jax-releases/libtpu_releases.html &&
#     pip install --no-cache-dir libtpu xprof

# Add your application code
COPY ./app /app
WORKDIR /app

# Run your script
CMD ["python", "your_train_script.py"]

워크로드 배포

SDK를 워크로드와 통합한 후 이미지를 사용하여 워크로드를 패키징하고 지정된 이미지를 사용하여 YAML 파일을 만듭니다. YAML 파일에서 managed-mldiagnostics-gke=true로 워크로드에 라벨을 지정합니다.

GKE의 경우:

kubectl apply -f YAML_FILE_NAME

Compute Engine의 경우 SSH를 사용하여 VM에 연결하고 워크로드의 Python 코드를 실행합니다.

source venv/bin/activate
python3.11 WORKLOAD_FILE_NAME

워크로드를 배포한 후 워크로드 네임스페이스를 검색하여 작업 이름을 찾습니다.

kubectl get job -n YOUR_NAMESPACE

작업 이름과 네임스페이스를 전달하여 kubectl 로그에서 실행 이름과 링크를 찾을 수 있습니다. ML 진단 사이드카는 자체 로깅을 처리하므로 워크로드 컨테이너 (예: -c workload)를 지정해야 합니다.

kubectl logs jobs/s5-tpu-slice-0 -n YOUR_NAMESPACE -c workload