L'API Slurm Job ti consente di gestire i cluster di addestramento di Gemini Enterprise Agent Platform tramite l'API Agent Platform, uno script, un notebook o una pipeline CI/CD. L'API Slurm Job consente di gestire il job del cluster Slurm senza connettersi al cluster con SSH.
Prerequisiti
Prima di utilizzare l'API Slurm Job per gestire il cluster, assicurati di soddisfare i seguenti requisiti:
Hai accesso ai cluster di addestramento, in genere tramite il ruolo Agent Platform User
roles/aiplatform.usernel progetto del cluster o qualsiasi ruolo che includa l'autorizzazioneaiplatform.googleapis.com/modelDevelopmentClusters.run.Google Cloud CLI è installato e hai configurato Credenziali predefinite dell'applicazione (
gcloud auth application-default login). Per gli strumenti automatici che non possono eseguire un accesso interattivo, esegui l'autenticazione come account di servizio con l'autorizzazioneaiplatform.googleapis.com/modelDevelopmentClusters.run.Conosci l'ID progetto, la regione e l'ID cluster del tuo cluster.
Inoltre, ti consigliamo di configurare un alias di convenienza:
alias gcurl='curl -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" -H "Content-Type: application/json"'
Panoramica
Ogni chiamata è una richiesta POST all'endpoint callSlurmRestApi per il tuo cluster. Nel corpo della richiesta, fornisci i seguenti campi:
method: il metodo HTTP REST di Slurm, ad esempio:HTTP_METHOD_GET,HTTP_METHOD_POSToHTTP_METHOD_DELETE.path: il percorso REST di Slurm. Ad esempio:/slurm/v0.0.42/job/submit. Utilizza la versione di Slurm in esecuzione nel tuo cluster. Gli esempi in questa guida utilizzano la versione 0.0.42.
body: un oggetto JSON con il payload della richiesta. Il corpo è obbligatorio per le richiesteHTTP_METHOD_POST. Omettilo per le richiesteHTTP_METHOD_GETeHTTP_METHOD_DELETE.
La risposta contiene i seguenti campi:
status: lo stato HTTP restituito dall'API Slurm Job. Ad esempio200.structuredBody: la risposta dall'API Slurm Job, come oggetto JSON. Leggi i campi necessari, ad esempio l'ID job o l'elenco dei job, direttamente dastructuredBody.
Esegui i job sul tuo account Linux nei cluster di addestramento automaticamente. Non è richiesta alcuna configurazione aggiuntiva e non puoi eseguire il job come un altro utente. SSH non è richiesto, perché tutto viene eseguito tramite l'API Agent Platform.
Ogni chiamata restituisce direttamente la risposta di Slurm, senza un'operazione di polling. Puoi seguire lo stato di un job nel tempo. Per saperne di più, consulta Controlla lo stato del job.
Chiama l'API
Le sezioni seguenti mostrano come utilizzare l'API Slurm Job.
Invia un job
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"
}
}'
Sostituisci quanto segue:
REGION: la regione in cui si trova il cluster.PROJECT_ID: il tuo ID progetto.CLUSTER_ID: l'ID del tuo cluster.PARTITION: la partizione Slurm a cui ti stai connettendo.USERNAME: il tuo nome utente nella partizione Slurm.
Il valore time_limit è il tempo in minuti. Il campo script contiene i contenuti dello script, non un percorso di un file.
L'API Slurm Job restituisce l'ID del nuovo job in structuredBody. Puoi utilizzare il comando jq per isolare l'ID job:
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'
Verifica dello stato di un job
Utilizza quanto segue per monitorare un job in esecuzione. Esegui il polling finché lo stato non raggiunge uno stato di arresto, ad esempio COMPLETED, FAILED o 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"
}'
Sostituisci quanto segue:
REGION: la regione in cui si trova il cluster.PROJECT_ID: il tuo ID progetto.CLUSTER_ID: l'ID del tuo cluster.JOB_ID: l'ID job del job Slurm.
Elenca job
Utilizza il seguente comando per elencare i job in esecuzione:
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/"
}'
Sostituisci quanto segue:
REGION: la regione in cui si trova il cluster.PROJECT_ID: il tuo ID progetto.CLUSTER_ID: l'ID del tuo cluster.
Annulla un job
L'annullamento viene accettato immediatamente, ma l'arresto del job richiede un po' di tempo. Controlla lo stato per verificare che sia CANCELLED. Puoi annullare solo i tuoi job. L'annullamento di un job completato è sicuro e restituisce un esito positivo.
Per annullare un job in esecuzione, utilizza quanto segue:
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"
}'
Sostituisci quanto segue:
REGION: la regione in cui si trova il cluster.PROJECT_ID: il tuo ID progetto.CLUSTER_ID: l'ID del tuo cluster.JOB_ID: l'ID job del job Slurm.
Visualizza un job completato
Il controllo di un job con il percorso /slurm funziona solo mentre il job è ancora nella coda live. Per i job completati, utilizza invece il percorso 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"
}'
Sostituisci quanto segue:
REGION: la regione in cui si trova il cluster.PROJECT_ID: il tuo ID progetto.CLUSTER_ID: l'ID del tuo cluster.JOB_ID: l'ID job del job Slurm.
Utilizzo dell'API Slurm Job da Python
Se preferisci utilizzare Python anziché curl, puoi utilizzare il seguente script di supporto per inviare job, controllarne lo stato e annullarli. Lo script helper utilizza la libreria google-auth per le Credenziali predefinite dell'applicazione.
Per utilizzare l'API Slurm Job da Python, segui questi passaggi:
Installa le Credenziali predefinite dell'applicazione:
pip install google-auth requestsUtilizza il seguente script Python per utilizzare l'API:
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"])
Lo script helper restituisce lo stato di Slurm e structuredBody, in modo che tu possa leggere direttamente campi come job_id o job_state. Per utilizzare lo script in ambienti automatizzati, esegui l'autenticazione come service account anziché utilizzare un accesso interattivo.
Risposta dell'API
Di seguito è riportata una tipica risposta dell'API Slurm Job:
{
"status": 200,
"structuredBody": {
"job_id": 1234,
"errors": [],
"warnings": []
}
}
Il campo status è lo stato HTTP di Slurm e structuredBody contiene la risposta di Slurm come oggetto JSON, in modo da poter leggere direttamente i suoi campi, ad esempio: jq -r '.structuredBody.job_id'.
Controlla sempre structuredBody indipendentemente dal valore status, perché
structuredBody include eventuali errori o avvisi segnalati da Slurm.
Se la richiesta CallSlurmRestApi non è formattata correttamente, potresti ricevere un risultato error come nell'esempio seguente:
{
"error": {
"code": 400,
"message": "{ ... some error ... }",
"status": "INVALID_ARGUMENT"
}
}
Risposte comuni
| Dati visualizzati | Che cosa significa |
|---|---|
| Stato 200 con un ID job | Job inviato correttamente. |
| Stato 200, nessun errore | Richiesta riuscita. |
| Stato 200 con avvisi | La richiesta è riuscita, ma Slurm ha ignorato o modificato qualcosa. Leggi l'avviso. |
| Stato 404 per un job | Il job non è nella coda attiva; potrebbe essere terminato. Prova il percorso della cronologia. |
| Stato 400 o 500 |
Slurm ha rifiutato la richiesta. I motivi del rifiuto potrebbero includere un corpo non valido o un campo del tipo sbagliato. Leggi l'errore in structuredBody.
|
| Errore PERMISSION_DENIED | Non hai accesso a questo cluster. |
| Errore NOT_FOUND | Il nome del cluster è errato o il cluster non esiste. |
| Errore INVALID_ARGUMENT | Il percorso non è un percorso Slurm valido o la richiesta è troppo grande. |
| Errore UNAVAILABLE | Il cluster è temporaneamente irraggiungibile. Riprova dopo una breve attesa. |
Limiti
L'intera richiesta deve avere dimensioni inferiori a 1 MB. Per utilizzare script di grandi dimensioni, posiziona lo script nello spazio di archiviazione condiviso del cluster e poi chiamalo da uno script wrapper breve.