Mit der Slurm Job API können Sie Ihre Gemini Enterprise Agent Platform-Trainingscluster über die Agent Platform API, ein Skript, ein Notebook oder eine CI/CD-Pipeline verwalten. Mit der Slurm Job API können Sie den Slurm-Clusterjob verwalten, ohne eine SSH-Verbindung zum Cluster herstellen zu müssen.
Vorbereitung
Bevor Sie die Slurm Job API zum Verwalten Ihres Clusters verwenden, müssen die folgenden Anforderungen erfüllt sein:
Sie haben Zugriff auf die Trainingscluster, in der Regel über die Rolle Agent Platform User (
roles/aiplatform.user) im Projekt des Clusters oder über eine beliebige Rolle, die die Berechtigungaiplatform.googleapis.com/modelDevelopmentClusters.runenthält.Die Google Cloud CLI ist installiert und Sie haben Standardanmeldedaten für Anwendungen (
gcloud auth application-default login) konfiguriert. Für automatisierte Tools, die keine interaktive Anmeldung ausführen können, authentifizieren Sie sich als Dienstkonto mit der Berechtigungaiplatform.googleapis.com/modelDevelopmentClusters.run.Sie kennen die Projekt-ID, die Region und die Cluster-ID Ihres Clusters.
Außerdem empfehlen wir, einen Alias einzurichten:
alias gcurl='curl -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" -H "Content-Type: application/json"'
Übersicht
Jeder Aufruf ist eine POST-Anfrage an den callSlurmRestApi-Endpunkt für Ihren Cluster. Geben Sie im Anfragetext folgende Felder an:
method: Die Slurm-REST-HTTP-Methode, z. B.HTTP_METHOD_GET,HTTP_METHOD_POSToderHTTP_METHOD_DELETE.path: Der Slurm-REST-Pfad. Beispiel:/slurm/v0.0.42/job/submitVerwenden Sie die Slurm-Version, die auf Ihrem Cluster ausgeführt wird. In den Beispielen in diesem Leitfaden wird v0.0.42 verwendet.
body: Ein JSON-Objekt mit der Nutzlast der Anfrage. Der Text ist fürHTTP_METHOD_POST-Anfragen erforderlich. Lassen Sie es beiHTTP_METHOD_GET- undHTTP_METHOD_DELETE-Anfragen weg.
Die Antwort umfasst die folgenden Felder:
status: Der von der Slurm Job API zurückgegebene HTTP-Status. Beispiel:200.structuredBody: Die Antwort der Slurm Job API als JSON-Objekt. Lesen Sie die benötigten Felder, z. B. die Job-ID oder die Jobliste, direkt ausstructuredBody.
Sie führen Jobs automatisch in Ihrem eigenen Linux-Konto auf den Trainingsclustern aus. Es ist keine zusätzliche Konfiguration erforderlich und Sie können den Job nicht als anderer Nutzer ausführen. SSH ist nicht erforderlich, da alles über die Agent Platform API erledigt wird.
Bei jedem Aufruf wird die Antwort von Slurm direkt zurückgegeben, ohne dass ein Vorgang abgefragt werden muss. Sie können den Status eines Jobs im Zeitverlauf verfolgen. Weitere Informationen finden Sie unter Jobstatus prüfen.
API aufrufen
In den folgenden Abschnitten wird die Verwendung der Slurm Job API beschrieben.
Job senden
gcurl -X POST \
"https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/modelDevelopmentClusters/CLUSTER_ID:callSlurmRestApi" \
-d '{
"method": "HTTP_METHOD_POST",
"path": "/slurm/v0.0.42/job/submit",
"body": {
"job": {
"name": "my-run",
"partition": "PARTITION",
"current_working_directory": "/home/USERNAME",
"minimum_nodes": 1,
"tasks_per_node": 1,
"environment": ["PATH=/bin:/usr/bin"],
"time_limit": {"set": true, "number": 120}
},
"script": "#!/bin/bash\necho hello\nsleep 5\necho done\n"
}
}'
Ersetzen Sie Folgendes:
REGION: Die Region, in der sich der Cluster befindet.PROJECT_ID: Ihre Projekt-ID.CLUSTER_ID: Ihre Cluster-ID.PARTITION: Die Slurm-Partition, zu der Sie eine Verbindung herstellen.USERNAME: Ihr Nutzername auf der Slurm-Partition.
Der Wert time_limit ist die Zeit in Minuten. Das Feld script enthält den Skriptinhalt, nicht den Pfad zu einer Datei.
Die Slurm Job API gibt die ID des neuen Jobs in structuredBody zurück. Mit dem Befehl jq können Sie die Job-ID isolieren:
gcurl -sS -X POST "https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/modelDevelopmentClusters/CLUSTER_ID:callSlurmRestApi" \
-d '{ ... }' | jq -r '.structuredBody.job_id'
Jobstatus prüfen
Verwenden Sie Folgendes, um einen laufenden Job zu überwachen. Führen Sie den Vorgang so lange aus, bis der Status einen beendeten Zustand erreicht, z. B. COMPLETED, FAILED oder CANCELLED:
gcurl -X POST \
"https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/modelDevelopmentClusters/CLUSTER_ID:callSlurmRestApi" \
-d '{
"method": "HTTP_METHOD_GET",
"path": "/slurm/v0.0.42/job/JOB_ID"
}'
Ersetzen Sie Folgendes:
REGION: Die Region, in der sich der Cluster befindet.PROJECT_ID: Ihre Projekt-ID.CLUSTER_ID: Ihre Cluster-ID.JOB_ID: Die Job-ID des Slurm-Jobs.
Jobs auflisten
Verwenden Sie den folgenden Befehl, um laufende Jobs aufzulisten:
gcurl -X POST \
"https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/modelDevelopmentClusters/CLUSTER_ID:callSlurmRestApi" \
-d '{
"method": "HTTP_METHOD_GET",
"path": "/slurm/v0.0.42/jobs/"
}'
Ersetzen Sie Folgendes:
REGION: Die Region, in der sich der Cluster befindet.PROJECT_ID: Ihre Projekt-ID.CLUSTER_ID: Ihre Cluster-ID.
Job abbrechen
Der Abbruch wird sofort akzeptiert, es dauert jedoch einen Moment, bis der Job beendet wird. Prüfen Sie den Status, um festzustellen, ob der Status CANCELLED lautet. Sie können nur Ihre eigenen Jobs abbrechen. Das Abbrechen eines abgeschlossenen Jobs ist sicher und gibt „Erfolgreich“ zurück.
Verwenden Sie Folgendes, um einen laufenden Job abzubrechen:
gcurl -X POST \
"https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/modelDevelopmentClusters/CLUSTER_ID:callSlurmRestApi" \
-d '{
"method": "HTTP_METHOD_DELETE",
"path": "/slurm/v0.0.42/job/JOB_ID"
}'
Ersetzen Sie Folgendes:
REGION: Die Region, in der sich der Cluster befindet.PROJECT_ID: Ihre Projekt-ID.CLUSTER_ID: Ihre Cluster-ID.JOB_ID: Die Job-ID des Slurm-Jobs.
Abgeschlossenen Job anzeigen
Die Prüfung eines Jobs mit dem Pfad /slurm funktioniert nur, solange sich der Job noch in der Live-Warteschlange befindet. Verwenden Sie für abgeschlossene Jobs stattdessen den Pfad slurmdb:
gcurl -X POST \
"https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/modelDevelopmentClusters/CLUSTER_ID:callSlurmRestApi" \
-d '{
"method": "HTTP_METHOD_GET",
"path": "/slurmdb/v0.0.42/job/JOB_ID"
}'
Ersetzen Sie Folgendes:
REGION: Die Region, in der sich der Cluster befindet.PROJECT_ID: Ihre Projekt-ID.CLUSTER_ID: Ihre Cluster-ID.JOB_ID: Die Job-ID des Slurm-Jobs.
Slurm Job API über Python verwenden
Wenn Sie Python gegenüber curl bevorzugen, können Sie das folgende Hilfsskript verwenden, um Jobs einzureichen, den Jobstatus zu prüfen und Jobs abzubrechen. Das Hilfsskript verwendet die google-auth-Bibliothek für Standardanmeldedaten für Anwendungen.
So verwenden Sie die Slurm Job API in Python:
Installieren Sie die Standardanmeldedaten für Anwendungen:
pip install google-auth requestsVerwenden Sie das folgende Python-Skript, um die API zu verwenden:
import google.auth import google.auth.transport.requests # Fill in your cluster's values. PROJECT_ID = "PROJECT_ID" REGION = "REGION" CLUSTER_ID = "CLUSTER_ID" PARTITION = "PARTITION" USERNAME = "USERNAME" # Application Default Credentials: gcloud auth application-default login, or a # service account for automated callers. credentials, _ = google.auth.default( scopes=["https://www.googleapis.com/auth/cloud-platform"]) session = google.auth.transport.requests.AuthorizedSession(credentials) url = ( f"https://{REGION}-aiplatform.googleapis.com/v1beta1/projects/{PROJECT_ID}" f"/locations/{REGION}/modelDevelopmentClusters/{CLUSTER_ID}:callSlurmRestApi" ) def call_slurm(method, path, body=None): request = {"method": method, "path": path} if body is not None: request["body"] = body response = session.post(url, json=request) response.raise_for_status() envelope = response.json() return envelope["status"], envelope.get("structuredBody", {}) # Submit a job. status, result = call_slurm( "HTTP_METHOD_POST", "/slurm/v0.0.42/job/submit", { "job": { "name": "my-run", "partition": f"{PARTITION}", "current_working_directory": f"/home/{USERNAME}", "minimum_nodes": 1, "tasks_per_node": 1, "environment": ["PATH=/bin:/usr/bin"], "time_limit": {"set": True, "number": 120}, }, "script": "#!/bin/bash\necho hello\nsleep 5\necho done\n", }, ) job_id = result["job_id"] print("submitted job", job_id) # Check its status. _, pending_result = call_slurm("HTTP_METHOD_GET", f"/slurm/v0.0.42/job/{job_id}") print("state:", pending_result["jobs"][0]["job_state"]) # Cancel it. call_slurm("HTTP_METHOD_DELETE", f"/slurm/v0.0.42/job/{job_id}") print("cancelled job", job_id) # Confirm the job is cancelled. _, cancelled_result = call_slurm("HTTP_METHOD_GET", f"/slurm/v0.0.42/job/{job_id}") print("state", cancelled_result["jobs"][0]["job_state"])
Das Hilfsskript gibt den Status von Slurm und structuredBody zurück, sodass Sie Felder wie job_id oder job_state direkt lesen können. Wenn Sie das Script in automatisierten Umgebungen verwenden möchten, authentifizieren Sie sich als Dienstkonto, anstatt eine interaktive Anmeldung zu verwenden.
API-Antwort
Hier ist eine typische Slurm Job API-Antwort:
{
"status": 200,
"structuredBody": {
"job_id": 1234,
"errors": [],
"warnings": []
}
}
Das Feld status ist der HTTP-Status von Slurm und structuredBody enthält die Antwort von Slurm als JSON-Objekt, sodass Sie die Felder direkt lesen können, z. B. jq -r '.structuredBody.job_id'.
Prüfen Sie immer structuredBody, unabhängig vom Wert von status, da structuredBody alle Fehler oder Warnungen enthält, die Slurm meldet.
Wenn die CallSlurmRestApi-Anfrage falsch formatiert ist, erhalten Sie möglicherweise ein error-Ergebnis wie im folgenden Beispiel:
{
"error": {
"code": 400,
"message": "{ ... some error ... }",
"status": "INVALID_ARGUMENT"
}
}
Häufige Antworten
| Was wird angezeigt? | Bedeutung |
|---|---|
| Status 200 mit einer Job-ID | Job wurde gesendet. |
| Status 200, keine Fehler | Anfrage erfolgreich. |
| Status 200 mit Warnungen | Die Anfrage war erfolgreich, aber Slurm hat etwas ignoriert oder angepasst. Lesen Sie die Warnung. |
| Status 404 für einen Job | Der Job befindet sich nicht in der Live-Warteschlange. Er ist möglicherweise abgeschlossen. Versuchen Sie es mit dem Verlaufspfad. |
| Status 400 oder 500 |
Slurm hat die Anfrage abgelehnt. Gründe für die Ablehnung können ein fehlerhafter Text oder ein Feld mit dem falschen Typ sein. Lesen Sie den Fehler in structuredBody.
|
| PERMISSION_DENIED-Fehler | Sie haben keinen Zugriff auf diesen Cluster. |
| NOT_FOUND-Fehler | Der Clustername ist falsch oder der Cluster ist nicht vorhanden. |
| INVALID_ARGUMENT-Fehler | Der Pfad ist kein gültiger Slurm-Pfad oder die Anfrage ist zu groß. |
| Fehler UNAVAILABLE | Der Cluster ist vorübergehend nicht erreichbar. Warten Sie kurz und versuchen Sie es dann noch einmal. |
Limits
Die gesamte Anfrage muss kleiner als 1 MB sein. Wenn Sie große Skripts verwenden möchten, legen Sie das Skript im freigegebenen Speicher des Clusters ab und rufen Sie es dann über ein kurzes Wrapper-Skript auf.