Mulai menggunakan ML Diagnostics SDK

ML Diagnostics Python SDK dapat diintegrasikan dengan beban kerja ML untuk mengumpulkan dan mengelola metrik, konfigurasi, dan profil beban kerja di Google Cloud. Panduan ini menunjukkan cara membuat run machine learning, mengumpulkan dan mengelola metrik serta konfigurasi beban kerja, men-deploy resource XProf terkelola, serta mengaktifkan pengambilan profil terprogram dan sesuai permintaan.

Untuk mengetahui informasi selengkapnya tentang cara menggunakan ML Diagnostics SDK, lihat repositori google-cloud-mldiagnostics.

Instal ML Diagnostics SDK

Instal google-cloud-mldiagnostics library:

pip install google-cloud-mldiagnostics

Impor paket berikut dalam kode beban kerja ML Anda:

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

Mengaktifkan Cloud Logging

SDK menggunakan modul logging Python standar untuk menghasilkan metrik dan informasi konfigurasi. Untuk merutekan log ini ke Cloud Logging, instal dan konfigurasi library google-cloud-logging. Dengan begitu, Anda dapat melihat log SDK, metrik yang dicatat ke dalam log, dan log aplikasi Anda sendiri dalam konsol Google Cloud .

Instal library google-cloud-logging:

pip install google-cloud-logging

Konfigurasi logging dalam skrip Anda dengan melampirkan pengendali Cloud Logging ke logger root Python. Tambahkan baris berikut ke awal skrip Python Anda:

  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.")

Mengaktifkan logging mendetail

Secara default, level logging disetel ke INFO. Untuk menerima log yang lebih mendetail dari SDK, seperti detail eksekusi machine learning, tetapkan level logging ke DEBUG setelah memanggil setup_logging():

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.")

Dengan DEBUG diaktifkan, Anda akan menerima diagnostik SDK tambahan di Cloud Logging. Contoh:

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', ...}

Membuat proses machine learning

Untuk menggunakan platform Diagnostik ML, Anda harus membuat proses machine learning terlebih dahulu. Hal ini melibatkan instrumentasi beban kerja ML Anda dengan SDK untuk melakukan pencatatan, mengumpulkan metrik, dan mengaktifkan pelacakan profil.

Berikut adalah contoh dasar yang menginisialisasi Cloud Logging, membuat run machine learning (MLRun), mencatat metrik, dan merekam profil:

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)

Contoh kode menggunakan variabel berikut:

Variabel Persyaratan Deskripsi
name Wajib ID untuk proses tertentu. SDK akan otomatis membuat machine-learning-run-id untuk memastikan nama run unik.
run_group Opsional ID yang dapat membantu mengelompokkan beberapa proses yang termasuk dalam eksperimen yang sama. Misalnya, semua proses yang terkait dengan sapuan ukuran slice TPU dapat termasuk dalam grup yang sama.
project Opsional Jika tidak ditentukan, project akan diekstrak dari Google Cloud CLI.
region Wajib Semua lokasi Cluster Director didukung kecuali us-east5. Flag ini dapat ditetapkan oleh argumen untuk setiap perintah, atau dengan perintah: gcloud config set compute/region.
configs Opsional Key-value pair yang berisi parameter konfigurasi untuk proses. Jika konfigurasi tidak ditentukan, konfigurasi software dan sistem default akan muncul tetapi konfigurasi beban kerja ML tidak.
gcs_path Wajib Bersyarat Google Cloud Lokasi penyimpanan tempat semua profil disimpan. Misalnya gs://my-bucket atau gs://my-bucket/folder1. Hanya diperlukan jika SDK digunakan untuk pengambilan profil.
on-demand-xprof Opsional Memulai xprofz daemon di port 9999 untuk mengaktifkan pembuatan profil sesuai permintaan. Anda dapat mengaktifkan pembuatan profil sesuai permintaan dan pembuatan profil terprogram dalam kode yang sama, asalkan tidak terjadi secara bersamaan.

Konfigurasi berikut dikumpulkan secara otomatis oleh SDK dan tidak perlu ditentukan dalam machinelearning_run:

  • Konfigurasi software: Framework, versi framework, flag XLA.
  • Konfigurasi sistem: Jenis perangkat, jumlah slice, ukuran slice, jumlah host.

Informasi project dan region disimpan sebagai metadata eksekusi machine learning. Region yang digunakan untuk menjalankan machine learning tidak harus sama dengan region yang digunakan untuk menjalankan beban kerja.

Menulis konfigurasi

Banyak workload berisi terlalu banyak konfigurasi untuk ditentukan langsung dalam definisi machinelearning_run. Dalam kasus ini, Anda dapat menulis konfigurasi ke run menggunakan JSON atau 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",
)

Mengumpulkan metrik

Anda dapat mengumpulkan metrik model, metrik performa model, dan metrik sistem dengan SDK. Anda dapat membuat visualisasi metrik ini sebagai nilai rata-rata dan dengan diagram deret waktu.

SDK menyediakan dua fungsi untuk merekam metrik: metrics.record() untuk merekam titik data individual, dan metrics.record_metrics() untuk merekam beberapa metrik dalam satu batch. Kedua fungsi menulis metrik ke Cloud Logging, sehingga memungkinkan visualisasi dan analisis.

Untuk merekam satu metrik:

# 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)

Untuk merekam beberapa metrik:

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)

Metrik sistem berikut dikumpulkan secara otomatis oleh SDK dari library libTPU, psutil, dan JAX:

  • Penggunaan TensorCore TPU
  • Siklus tugas TPU
  • Penggunaan HBM
  • Penggunaan CPU host
  • Penggunaan memori host

Anda tidak perlu menentukan metrik ini secara manual. Metrik sistem ini memiliki waktu sebagai sumbu x default.

Kunci metrik standar berikut akan otomatis muncul di konsolGoogle Cloud jika ditetapkan. Metrik ini tidak dihitung secara otomatis; metrik ini adalah kunci yang telah ditentukan sebelumnya yang dapat Anda tetapkan nilainya.

  • Kunci metrik kualitas model: LEARNING_RATE, LOSS, GRADIENT_NORM, TOTAL_WEIGHTS.
  • Kunci metrik performa model: STEP_TIME, THROUGHPUT, LATENCY, MFU, TFLOPS.

Metrik yang telah ditentukan sebelumnya, serta metrik buatan pengguna lainnya dapat dicatat dengan sumbu x sebagai time, atau time dan step. Anda dapat merekam metrik kustom apa pun dalam beban kerja.

Contoh berikut merekam satu metrik untuk workload, yang dapat Anda lihat di tab Metrik Model untuk menjalankan machine learning tertentu:

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

Untuk mencatat beberapa metrik dalam satu panggilan, gunakan metode record_metrics. Misalnya:

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)

Merekam profil

Anda dapat merekam profil XProf beban kerja ML Anda dengan perekaman terprogram atau perekaman on-demand (perekaman manual). Pengambilan terprogram melibatkan penyematan perintah pembuatan profil langsung ke kode machine learning Anda, dan menyatakan secara eksplisit kapan harus memulai dan berhenti merekam data. Pengambilan data sesuai permintaan terjadi secara real-time, saat Anda memicu profiler ketika workload sudah berjalan aktif.

Perintah SDK untuk merekam profil tidak bergantung pada framework karena semua perintah pembuatan profil tingkat framework otomatis diintegrasikan ke dalam perintah pembuatan profil Diagnostik ML. Artinya, kode pembuatan profil Anda tidak bergantung pada framework yang Anda gunakan.

Pengambilan profil terprogram

Pengambilan data terprogram mengharuskan Anda membuat anotasi kode model dan menentukan tempat Anda ingin mengambil profil. Biasanya, Anda merekam profil untuk beberapa langkah pelatihan, atau membuat profil blok kode tertentu dalam model Anda.

Anda dapat melakukan pengambilan profil terprogram dengan ML Diagnostics SDK dengan cara berikut:

  • Pengumpulan berbasis API: Kontrol pembuatan profil dengan metode start() dan stop().
  • Pengumpulan berbasis dekorator: Anotasi fungsi dengan @xprof(run) untuk pembuatan profil otomatis.
  • Pengelola konteks: Gunakan dengan xprof() untuk pembuatan profil berbasis cakupan yang secara otomatis menangani operasi start() dan stop().

Anda dapat menggunakan kode pengambilan profil yang sama di semua framework. Semua sesi profil diambil di bucket Cloud Storage yang ditentukan dalam proses machine learning.

# 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()

Pembuatan profil multi-host (proses)

Selama pembuatan profil terprogram, SDK memulai pembuatan profil di setiap host (proses) tempat kode beban kerja ML dieksekusi. Jika daftar node tidak diberikan, semua host akan disertakan.

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

Secara default, memanggil metode prof.start() tanpa argumen session_id di beberapa host akan menghasilkan sesi rekaman aktivitas terpisah - satu untuk setiap host. Untuk mengelompokkan rekaman aktivitas dari host yang berbeda ke dalam satu sesi multi-host terpadu di XProf, pastikan metode prof.start() dipanggil dengan argumen same session_id di semua host yang berpartisipasi. Contoh:

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

Untuk mengaktifkan pembuatan profil untuk host tertentu:

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

Pengambilan profil sesuai permintaan

Gunakan pengambilan profil sesuai permintaan jika Anda ingin mengambil profil secara ad hoc, atau jika pengambilan profil terprogram belum diaktifkan. Pengambilan sesuai permintaan berguna jika ada masalah dengan metrik model selama proses berjalan, dan Anda ingin mengambil profil pada saat itu untuk mendiagnosis masalah.

Untuk mengaktifkan pengambilan profil on-demand, konfigurasi eksekusi dengan dukungan on-demand:

# 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
)

Anda dapat menggunakan kode pengambilan profil yang sama di semua framework. Semua sesi profil diambil di bucket Cloud Storage yang ditentukan dalam proses machine learning.

Untuk pembuatan profil sesuai permintaan di GKE, deploy GKE connection-operator dan injection-webhook ke cluster GKE. Hal ini memastikan bahwa proses machine learning Anda dapat menemukan node GKE tempat proses tersebut berjalan, dan drop-down pengambilan on-demand dapat mengisi otomatis node tersebut. Untuk mengetahui informasi selengkapnya, lihat Mengonfigurasi cluster GKE.

Mengemas workload untuk GKE

Anda dapat menggunakan Dockerfile untuk mengemas aplikasi yang menggunakan ML Diagnostics SDK. Instal paket google-cloud-logging untuk integrasi Cloud Logging. Contoh:

# 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"]

Men-deploy workload

Setelah mengintegrasikan SDK dengan workload, kemas workload dalam image dan buat file YAML dengan image yang ditentukan. Beri label workload dalam file YAML dengan managed-mldiagnostics-gke=true.

Untuk GKE:

kubectl apply -f YAML_FILE_NAME

Untuk Compute Engine, hubungkan ke VM menggunakan SSH dan jalankan kode Python untuk beban kerja Anda:

source venv/bin/activate
python3.11 WORKLOAD_FILE_NAME

Setelah men-deploy workload, temukan nama tugas Anda dengan menelusuri namespace workload Anda:

kubectl get job -n YOUR_NAMESPACE

Anda dapat menemukan nama dan link eksekusi di log kubectl dengan meneruskan nama dan namespace tugas. Anda harus menentukan container workload (misalnya: -c workload) karena sidecar Diagnostik ML menangani logging-nya sendiri.

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