ML 진단 CLI 시작하기

ML 진단 Google Cloud CLI를 사용하여 머신러닝 실행을 만들고, 확장 가능한 백엔드가 있는 관리형 인스턴스로 XProf를 배포하고, Google Cloud에서 관리형 프로파일링 환경을 제공합니다.

ML 진단 gcloud CLI 명령어에는 machine-learning-run 명령어와 profiler 명령어의 두 가지 카테고리가 있습니다. machine-learning-run 명령어를 사용하여 머신러닝 실행을 생성, 삭제, 설명, 나열, 업데이트합니다. profiler 명령어를 사용하여 노드를 나열하고 CLI에서 주문형 프로필을 캡처합니다.

Machine-learning-run 명령어: Create, Delete, Describe, List, Update
프로파일러 명령어:
- profiler-target: List
- profiler-session: Capture, List

모든 gcloud CLI 명령어에는 환경에 정의된 프로젝트가 필요합니다. 프로젝트를 설정하려면 다음 단계를 따르세요.

gcloud config set project PROJECT_ID

ML 진단 gcloud CLI 명령어에 대한 자세한 내용은 API 참조를 확인하세요.

프로필 캡처

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

온디맨드 프로필 캡처를 사용 설정하려면 코드 내에서 XProf 서버를 시작하고 profiler.start_server 메서드를 호출해야 합니다. 이렇게 하면 프로필 캡처를 시작하기 위해 주문형 캡처 트리거를 수신 대기하는 ML 워크로드에서 XProf 서버가 시작됩니다. 이 명령어에는 포트 9999를 사용하세요. profiler.start_server(port=9999)

프로그래매틱 프로필 캡처와 온디맨드 프로필 캡처 모두 캡처된 프로필을 저장할 위치를 지정합니다. 예를 들면 gs://my-bucket/my-run입니다. 프로필은 gs://my-bucket/my-run/plugins/profile/session1/ 위치 내에 중첩된 디렉터리에 저장됩니다. 프로그래매틱 프로필 캡처와 주문형 캡처는 동일한 기간에 발생해서는 안 됩니다.

온디맨드 프로필 캡처의 경우 GKE 클러스터를 설정하고 managed-mldiagnostics-gke=true 라벨로 워크로드를 배포합니다.

JAX를 사용한 프로파일링에 관한 자세한 내용은 계산 프로파일링을 참고하세요.

머신러닝 실행 만들기

지정된 프로젝트와 위치에 머신러닝 실행 리소스를 만듭니다. machine-learning-run create 명령어는 XProf를 프로젝트의 관리형 인스턴스로 배포합니다. 관리형 XProf 인스턴스는 프로젝트의 모든 프로필을 보는 데 사용되며 프로젝트에서 첫 번째 머신러닝 실행이 생성될 때 생성됩니다.

machine-learning-run create 명령어를 사용합니다.

gcloud alpha mldiagnostics machine-learning-run create

머신러닝 실행을 만드는 방법에는 두 가지가 있습니다.

기존 캡처된 프로필을 ML 진단 플랫폼에 등록합니다.
ML 진단을 사용하여 활성 실행을 등록하여 온디맨드 프로필 캡처를 실행합니다. 이를 위해서는 GKE 클러스터 설정과 managed-mldiagnostics-gke=true 라벨이 있는 GKE에 배포된 워크로드가 필요합니다.

ML 실행을 만들고 기존 캡처 프로필 등록

다음 코드는 실행을 만들고 기존 캡처된 프로필을 ML 진단에 등록합니다.

gcloud alpha mldiagnostics machine-learning-run create RUN_NAME \
  --location LOCATION \
  --run-group GROUP_NAME \
  --gcs-path gs://BUCKET_NAME \
  --display-name DISPLAY_NAME \
  --labels "list_existing_sessions_only"="true"

코드 예시에서는 다음 플래그를 사용합니다.

플래그	요구사항	설명
`machine-learning-run`	필수	이 특정 실행의 고유 식별자입니다. 이름이 고유하지 않으면 'ML 실행이 이미 존재함'이라는 메시지와 함께 실행 생성이 실패합니다.
`location`	필수	`us-east5`를 제외한 모든 클러스터 디렉터 위치가 지원됩니다. 이 플래그는 각 명령어의 인수로 설정하거나 `gcloud config set compute/region` 명령어로 설정할 수 있습니다.
`gcs-path`	필수	모든 프로필이 저장되는 Google Cloud 스토리지 위치입니다. 예를 들면 `gs://my-bucket` 또는 `gs://my-bucket/folder1`입니다. SDK가 프로필 캡처에 사용되는 경우에만 필요합니다.
`run-group`	선택사항	동일한 실험에 속하는 여러 실행을 그룹화하는 데 도움이 되는 식별자입니다. 예를 들어 TPU 슬라이스 크기 스위프와 연결된 모든 실행은 동일한 그룹에 속할 수 있습니다.
`display-name`	선택사항	머신러닝 실행의 표시 이름입니다. 제공되지 않으면 머신러닝 실행 ID로 설정됩니다.

ML 진단에서 기존에 수집된 프로필을 보고 관리하려면 --labels list_existing_sessions_only=true 플래그가 필요합니다. 이 플래그는 다음 작업을 실행합니다.

상태가 'Completed'인 머신러닝 실행을 만듭니다.
Cloud Storage 디렉터리 경로 내에서 xplane.pb 파일을 재귀적으로 검색합니다.
위치한 모든 프로필 세션을 ML 진단 데이터베이스에 로드하여 Google Cloud에서 확인하고, 프로필 세션의 공유 가능한 링크를 만들고, 사용자가 ML 진단 플랫폼으로 이러한 프로필을 관리할 수 있도록 합니다.

실행에 대해 --labels list_existing_sessions_only 플래그가 true로 설정된 경우 주문형 프로파일링을 실행하거나 실행을 업데이트할 수 없습니다. 기존 프로필만 보고 관리할 수 있습니다.

주문형 프로필 캡처를 실행하기 위한 ML 실행 만들기

다음 코드는 주문형 프로필 캡처를 실행하기 위해 mlrun를 만듭니다.

gcloud alpha mldiagnostics machine-learning-run create RUN_NAME \
  --location LOCATION \
  --orchestrator gke \
  --run-group RUN_GROUP \
  --gcs-path gs://BUCKET_NAME \
  --display-name DISPLAY_NAME \
  --gke-cluster-name projects/user/locations/LOCATION/clusters/CLUSTER_NAME \
  --gke-namespace NAMESPACE \
  --gke-workload-name WORKLOAD_NAME \
  --gke-kind GKE_KIND \
  --gke-workload-create-time CREATE_TIME \
  --run-phase RUN_PHASE

이 코드 예에서는 이전 예의 플래그와 함께 다음 추가 플래그를 사용합니다.

플래그	요구사항	설명
`orchestrator`	선택사항	실행에 사용된 오케스트레이터입니다. 지정하지 않으면 기본적으로 `gke`이 사용됩니다. 유효한 값: `gce`, `gke`, `slurm`.
`gke-cluster-name`	GKE에 필요	워크로드의 클러스터입니다. 예: `/projects/<project_id>/locations/<location>/clusters/<cluster_name>`
`gke-kind`	GKE에 필요	워크로드의 종류입니다. 예를 들면 `JobSet`입니다.
`gke-namespace`	GKE에 필요	워크로드의 네임스페이스입니다. 예를 들면 `default`입니다.
`gke-workload-name`	GKE에 필요	워크로드의 식별자입니다. 예를 들면 `jobset-abcd`입니다.
`gke-workload-create-time`	GKE에 필요	ISO 타임스탬프 형식의 JobSet 생성 타임스탬프입니다. 예를 들면 `2026-02-20T06:00:00Z`입니다.
`run-phase`	선택사항	실행의 단계와 상태입니다. 제공되지 않은 경우 기본값은 `ACTIVE`입니다.

머신러닝 실행 설명

machine-learning-run describe 명령어를 사용하여 머신러닝 실행의 세부정보를 확인합니다.

gcloud alpha mldiagnostics machine-learning-run describe RUN_NAME --FORMAT=FORMAT

다음은 JSON 형식의 실행 세부정보 요청입니다.

gcloud alpha mldiagnostics machine-learning-run describe my-run-on-demand \
  --format json

출력은 다음과 비슷합니다.

{
  "artifacts": {
    "gcsPath": "gs://my-bucket"
  },
  "createTime": "2026-02-05T16:25:28.367865234Z",
  "displayName": "mldiagnostics-my-run-on-demand",
  "endTime": "0001-01-01T00:00:00Z",
  "etag": "1f54a7f4-bd25-4f98-a91c-97bfa1c5b7a6",
   "name": "projects/163028815180/locations/us-central1/machineLearningRuns/my-run-on-demand",
  "orchestrator": "GKE",
  "runPhase": "ACTIVE",
  "runSet": "my-run-on-demand-group",
  "tools": [
    {
      "XProf": {}
    }
  ],
  "updateTime": "2026-02-05T16:25:28.367865344Z",
  "workloadDetails": {
    "gke": {
      "cluster": "projects/163028815180/locations/us-central1/clusters/my-cluster",
      "id": "jobset-abcd",
      "kind": "JobSet",
      "namespace": "default"
    }
  }
}

머신러닝 실행 나열

machine-learning-run list 명령어를 사용하여 지정된 프로젝트와 위치 내의 머신러닝 실행 목록을 가져옵니다.

gcloud alpha mldiagnostics machine-learning-run list

다음 예는 최대 2개의 실행 목록을 요청하며, URI 경로의 출력이 있습니다.

gcloud alpha mldiagnostics machine-learning-run list --limit 2 --uri

https://hypercomputecluster.googleapis.com/v1alpha/projects/163028815180/locations/us-central1/machineLearningRuns/my-run-on-demand
https://hypercomputecluster.googleapis.com/v1alpha/projects/163028815180/locations/us-central1/machineLearningRuns/my-run-on-demand-2

머신러닝 실행 업데이트

지정된 프로젝트와 위치에서 머신러닝 실행을 업데이트합니다. 표시 이름, 실행 단계, 오케스트레이터, GKE 워크로드 세부정보를 업데이트할 수 있습니다. 러닝 ID와 위치는 변경할 수 없습니다. machine-learning-run update 명령어를 사용하여 실행을 업데이트합니다.

gcloud alpha mldiagnostics machine-learning-run update

create 요청에 포함된 모든 필드를 제공합니다. 업데이트 요청 중에 필수 필드가 제공되지 않으면 기본값으로 재정의됩니다.

etag 플래그는 필수 필드이며 ML 실행 리소스의 최신 ETag (엔티티 태그) 값이어야 합니다. 자세한 내용은 최적의 동시 실행 제어를 위해 항목 태그 사용을 참고하세요. 다음 값을 사용하여 올바른 ETAG 값을 찾습니다.

gcloud alpha mldiagnostics machine-learning-run describe RUN_NAME

다음은 전체 업데이트 요청의 예입니다.

gcloud alpha mldiagnostics machine-learning-run update my-run-on-demand \
  --orchestrator gke \
  --run-group my-run-on-demand-group \
  --gcs-path gs://my-bucket \
  --display-name mldiagnostics-my-run-on-demand-completed \
  --gke-cluster-name projects/user/locations/us-central1/clusters/my-cluster \
  --gke-namespace default \
  --gke-workload-name jobset-abcd \
  --gke-kind JobSet \
  --gke-workload-create-time 2026-02-20T06:06:06Z \
  --run-phase COMPLETED \
  --etag 1f54a7f4-bd25-4f98-a91c-97bfa1c5b7a6

머신러닝 실행 삭제

machine-learning-run delete 명령어를 사용하여 지정된 프로젝트와 위치에서 머신러닝 실행을 삭제합니다.

gcloud alpha mldiagnostics machine-learning-run delete RUN_NAME

ML 실행을 삭제해도 Cloud Storage, Cloud Logging 또는 GKE 워크로드의 데이터는 삭제되지 않습니다. mlrun를 삭제하면 ML 진단 시스템 내에서 실행과 관련된 메타데이터만 삭제됩니다.

프로파일러 명령어

프로파일러 명령 그룹을 사용하여 모든 프로필을 나열하고, XProf 서버가 실행 중인 워크로드의 GKE 노드를 찾고, CLI에서 주문형 프로필을 캡처할 수 있습니다.

프로파일러 타겟 나열

지정된 프로젝트와 위치의 머신러닝 실행과 연결된 모든 프로파일러 대상을 나열합니다.

gcloud alpha mldiagnostics profiler-target list --machine-learning-run RUN_NAME

이 명령어에는 다음이 필요합니다.

온디맨드 Xprof가 워크로드에서 사용 설정되어 있으며, 이 워크로드는 XProf 서버를 워크로드의 모든 노드에 배포합니다.
GKE 클러스터가 ML 진단용으로 설정되어 있고 웹훅과 연산자가 배포되어 있습니다.
라벨 managed-mldiagnostics-gke=true이(가) 있는 GKE에 워크로드가 배포되었습니다.

다음은 요청의 예입니다.

gcloud alpha mldiagnostics profiler-target list \
  --machine-learning-run my-run-on-demand

다음은 출력의 예시입니다.

---
hostname: gke-tpu-1f0789b5-jqx9
name: projects/163028815180/locations/us-central1/machineLearningRuns/my-run-on-demand/profilerTargets/jobset-abcd-tpu-slice-0-0-tcw2k
---
hostname: gke-tpu-1f0789b5-rxvf
name: projects/163028815180/locations/us-central1/machineLearningRuns/my-run-on-demand/profilerTargets/jobset-abcd-tpu-slice-0-1-dct59

프로파일러 세션 나열

다음 명령어를 사용하여 지정된 프로젝트와 위치에서 머신러닝 실행과 연결된 모든 프로파일러 세션을 나열합니다.

gcloud alpha mldiagnostics profiler-session list --machine-learning-run RUN_NAME

이 프로파일러 명령어에는 GKE 또는 워크로드 설정이 필요하지 않습니다. 프로그래매틱 세션과 주문형 세션이 모두 나열됩니다. 프로그래매틱 프로필 캡처만 있는 경우 이 명령어를 사용하여 모든 프로필 세션을 나열합니다. 필요한 GKE 설정, GKE 워크로드 라벨 지정 또는 주문형 XProf 사용 설정이 없습니다.

다음은 요청의 예입니다.

gcloud alpha mldiagnostics profiler-session list \
  --machine-learning-run my-run-on-demand

주문형 프로파일러 세션 캡처

워크로드가 실행되는 지정된 노드 집합 (프로파일러 타겟)에서 머신러닝 실행의 주문형 프로파일러 세션을 캡처할 수 있습니다.

이 명령어에는 다음이 필요합니다.

온디맨드 XProf가 워크로드에서 사용 설정되어 있으며, 이 워크로드는 XProf 서버를 워크로드의 모든 노드에 배포합니다.
GKE 클러스터가 ML 진단용으로 설정되어 있고 웹훅과 연산자가 배포됨
라벨 managed-mldiagnostics-gke=true이(가) 있는 GKE에 워크로드가 배포되었습니다.

다음은 요청의 예입니다.

gcloud alpha mldiagnostics profiler-session capture \
  profiler-session-on-demand \
  --machine-learning-run RUN_NAME \
  --targets TARGET \
  --duration DURATION

이 예시에서는 다음 플래그를 사용합니다.

플래그	요구사항	설명
`profiler-session-name`	필수	캡처할 프로파일러 세션의 이름입니다.
`duration`	필수	프로파일러 세션 캡처 시간입니다. `Duration` 유형입니다. 예를 들어 1초의 경우 `1s`, 400밀리초의 경우 `400ms`, 5분의 경우 `5m`를 지정합니다.
`targets`	필수	프로파일러 타겟의 ID 또는 프로파일러 타겟의 정규화된 식별자입니다. 실행과 연결된 타겟 목록과 일치해야 합니다.
`device-tracer-level`	선택사항	세션의 기기 추적기 수준입니다. 허용되는 값: `device-tracer-level-enabled`, `device-tracer-level-disabled` (기본값)
`host-tracer-level`	선택사항	세션의 호스트 추적기 수준입니다. 허용되는 값: `host-tracer-level-info` (기본값), `host-tracer-level-critical`, `host-tracer-level-disabled`, `host-tracer-level-verbose`
`python-tracer-level`	선택사항	세션의 Python 추적기 수준입니다. 허용되는 값: `python-tracer-level-disabled` (기본값), `python-tracer-level-enabled`