Memulai ML Diagnostics SDK

ML Diagnostics Python SDK dapat diintegrasikan dengan workload ML untuk memantau workload, mengumpulkan dan mengelola metrik, konfigurasi, dan profil model di Google Cloud. Gunakan SDK untuk pembuatan profil terprogram dan untuk melihat metrik model. Metrik model tidak tersedia jika Anda menggunakan pembuatan profil on-demand tanpa SDK.

Panduan ini menunjukkan cara membuat operasi machine learning, memantau workload, mengumpulkan dan mengelola metrik dan konfigurasi workload, men-deploy resource XProf terkelola, serta mengaktifkan pengambilan profil terprogram dan on-demand.

Untuk memiliki pemantauan workload, pengumpulan metrik dan konfigurasi, serta mengaktifkan pembuatan profil, gunakan versi SDK yang setidaknya terbaru seperti 1.0.6.

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

Menginstal ML Diagnostics SDK

Instal the google-cloud-mldiagnostics library:

pip install google-cloud-mldiagnostics

Impor paket berikut dalam kode workload 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 menampilkan informasi metrik dan konfigurasi. Untuk merutekan log ini ke Cloud Logging, instal dan konfigurasi library google-cloud-logging. Hal ini memungkinkan Anda melihat log SDK, metrik yang dicatat, dan log aplikasi Anda sendiri di dalam Google Cloud konsol.

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, tingkat logging ditetapkan ke INFO. Untuk menerima log yang lebih mendetail dari SDK, seperti detail operasi machine learning, tetapkan tingkat 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 operasi machine learning

Untuk menggunakan platform ML Diagnostics, Anda harus membuat operasi machine learning terlebih dahulu. Hal ini melibatkan instrumentasi workload ML Anda dengan SDK untuk melakukan logging, mengumpulkan metrik, dan mengaktifkan pelacakan profil.

Berikut adalah contoh dasar yang menginisialisasi Cloud Logging, membuat operasi machine learning (MLRun), mencatat metrik, dan mengambil 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 operasi tertentu. SDK secara otomatis membuat machine-learning-run-id untuk memastikan nama operasi unik.
run_group	Opsional	ID yang dapat membantu mengelompokkan beberapa operasi yang termasuk dalam eksperimen yang sama. Misalnya, semua operasi yang terkait dengan rentang 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 operasi. Jika konfigurasi tidak ditentukan, konfigurasi software dan sistem default akan muncul tetapi konfigurasi workload ML tidak.
gcs_path	Wajib Bersyarat	Lokasi Google Cloud Storage 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 on-demand pembuatan profil. Anda dapat mengaktifkan pembuatan profil on-demand dan pembuatan profil terprogram dalam kode yang sama, asalkan tidak terjadi pada waktu yang sama.

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 operasi machine learning. Region yang digunakan untuk operasi machine learning tidak harus cocok dengan region yang digunakan untuk operasi workload.

Menulis konfigurasi

Banyak workload berisi terlalu banyak konfigurasi untuk ditentukan langsung dalam definisi machinelearning_run. Dalam kasus ini, Anda dapat menulis konfigurasi ke operasi 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 mencatat metrik: metrics.record() untuk mengambil titik data individual, dan metrics.record_metrics() untuk mencatat beberapa metrik dalam satu batch. Kedua fungsi tersebut menulis metrik ke Cloud Logging, sehingga memungkinkan visualisasi dan analisis.

Untuk mencatat 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 mencatat 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 TPU TensorCore
• 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 yang telah ditentukan sebelumnya berikut akan otomatis muncul di Google Cloud konsol 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 lain yang ditentukan pengguna dapat dicatat dengan sumbu x sebagai time, atau time dan step. Anda dapat mencatat metrik kustom apa pun dalam workload.

Contoh berikut mengambil satu metrik untuk workload, yang dapat Anda lihat di tab Model Metrics untuk operasi machine learning tertentu:

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

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

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)

Metrik sistem

Anda dapat mengumpulkan metrik sistem secara otomatis pada interval 1 menit default atau interval yang lebih mendetail.

Interval default

Kumpulkan metrik sistem secara otomatis dengan interval 1 menit dari Cloud Monitoring dengan menetapkan log_system_metrics=false. Lihat Memantau workload untuk mengetahui detail metrik sistem yang dikumpulkan secara otomatis dengan default ini.

Berikut adalah contoh cara menerima metrik sistem default dari Cloud Monitoring:

machinelearning_run(
      name="my-run-123",
      run_group="my-group",
      project="gcp-project",
      region="us-central1",
      gcs_path="gs://my_bucket_path",
      on_demand_xprof=True,
      log_system_metrics=False
  )

Interval mendetail

Kumpulkan metrik sistem secara otomatis dengan interval mendetail (10 detik) dengan menetapkan log_system_metrics=true. Dengan opsi ini, metrik sistem berikut dikumpulkan secara otomatis oleh SDK dari library libTPU, psutil, dan JAX:

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

Berikut adalah contoh cara mengumpulkan metrik sistem mendetail:

machinelearning_run(
      name="my-run-123",
      run_group="my-group",
      project="gcp-project",
      region="us-central1",
      gcs_path="gs://my_bucket_path",
      on_demand_xprof=True,
      log_system_metrics=True
  )

Metrik sistem ini memiliki waktu sebagai sumbu x default.

Mengambil profil

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

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

Pengambilan profil terprogram

Pengambilan terprogram mengharuskan Anda membuat anotasi kode model dan menentukan tempat Anda ingin mengambil profil. Biasanya, Anda mengambil 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 start() dan stop() metode.
• Pengumpulan berbasis dekorator: Anotasi fungsi dengan @xprof(run) untuk pembuatan profil otomatis.
• Pengelola konteks: Gunakan dengan xprof() untuk pembuatan profil berbasis cakupan yang 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 operasi 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 akan mulai membuat profil di setiap host (proses) tempat kode workload 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 pelacakan terpisah - satu untuk setiap host. Untuk mengelompokkan pelacakan dari host yang berbeda ke dalam satu sesi multi-host terpadu di XProf, pastikan metode prof.start() dipanggil dengan argumen session_id yang sama 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 on-demand

Gunakan pengambilan profil on-demand jika Anda ingin mengambil profil secara ad hoc, atau jika pengambilan profil terprogram belum diaktifkan. Pengambilan on-demand berguna jika ada masalah dengan performa model selama operasi, dan Anda ingin mengambil profil pada saat tersebut untuk mendiagnosis masalah.

Untuk mengaktifkan pengambilan profil on-demand, konfigurasi operasi 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 operasi machine learning.

Untuk pembuatan profil on-demand di GKE, deploy GKE connection-operator dan injection-webhook ke dalam cluster GKE. Hal ini memastikan bahwa operasi machine learning Anda dapat menemukan node GKE yang dijalankannya, dan drop-down pengambilan on-demand dapat otomatis mengisi 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 Anda, kemas workload dalam image dan buat file YAML dengan image yang ditentukan. Untuk pembuatan profil terprogram, beri label workload dalam file YAML dengan managed-mldiagnostics-gke=true. Pembuatan profil on-demand tidak memerlukan label ini.

Untuk GKE:

kubectl apply -f YAML_FILE_NAME

Untuk Compute Engine, hubungkan ke VM menggunakan SSH dan jalankan kode Python untuk workload 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 operasi di log kubectl dengan meneruskan nama dan namespace tugas. Anda harus menentukan penampung workload (misalnya: -c workload) karena sidecar ML Diagnostics menangani logging-nya sendiri.

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