Utilizzo di un account di servizio personalizzato

Questa guida descrive come configurare Gemini Enterprise Agent Platform per utilizzare un account di servizio personalizzato nei seguenti scenari:

Quando utilizzare un account di servizio personalizzato

Quando viene eseguita, la piattaforma dell'agente agisce generalmente con le autorizzazioni di uno dei vari service account che Google crea e gestisce per il tuo progetto Google Cloud . Per concedere ad Agent Platform un maggiore accesso ad altri Google Cloud servizi in determinati contesti, puoi aggiungere ruoli specifici agli agenti di servizio di Agent Platform.

Tuttavia, la personalizzazione delle autorizzazioni degli agenti di servizio potrebbe non fornire il controllo dell'accesso granulare che desideri. Alcuni casi d'uso comuni includono:

  • Consentire meno autorizzazioni per i job e i modelli di Agent Platform. L'agente di servizio della piattaforma dell'agente predefinito ha accesso a BigQuery e Cloud Storage.
  • Consentire a lavori diversi di accedere a risorse diverse. Potresti voler consentire a molti utenti di avviare job in un singolo progetto, ma concedere l'accesso ai job di ogni utente solo a una determinata tabella BigQuery o a un bucket Cloud Storage.

Ad esempio, potresti voler personalizzare individualmente ogni job di addestramento personalizzato che esegui per accedere a diverse risorseGoogle Cloud al di fuori del tuo progetto.

Inoltre, la personalizzazione delle autorizzazioni degli agenti di servizio non modifica le autorizzazioni disponibili per un contenitore che pubblica previsioni da un Model addestrato personalizzato.

Per personalizzare l'accesso ogni volta che esegui l'addestramento personalizzato o per personalizzare le autorizzazioni di un container di previsione Model addestrato in modo personalizzato, devi utilizzare un account di servizio personalizzato.

Accesso predefinito

Questa sezione descrive l'accesso predefinito disponibile per i container di addestramento personalizzato e i container di previsione delle risorse Model addestrate in modo personalizzato. Quando utilizzi un account di servizio personalizzato, esegui l'override di questo accesso per una risorsa CustomJob, HyperparameterTuningJob, TrainingPipeline o DeployedModel specifica.

Container di addestramento

Quando crei un CustomJob, un HyperparameterTuningJob o un TrainingPipeline personalizzato, il training container viene eseguito utilizzando per impostazione predefinita il servizio di codice personalizzato dell'agente Gemini Enterprise Agent Platform del tuo progettoGoogle Cloud .

Scopri di più su Gemini Enterprise Agent Platform Custom Code Service Agent, incluso come concedergli l'accesso a risorse Google Cloud aggiuntive.

Container di previsione

Quando esegui il deployment di un Model addestrato personalizzato in un Endpoint, il container di previsione viene eseguito utilizzando un account di servizio gestito da Agent Platform. Questo account di servizio è diverso dagli agenti di servizio della piattaforma Agent Platform.

Il account di servizio utilizzato per impostazione predefinita dal contenitore di previsione dispone dell'autorizzazione per leggere gli artefatti del modello che Agent Platform rende disponibili in un URI archiviato nella variabile di ambiente AIP_STORAGE_URI. Non fare affidamento sull'account di servizio per disporre di altre autorizzazioni. Non puoi personalizzare le autorizzazioni del account di servizio.

Configura un account di servizio personalizzato

Le sezioni seguenti descrivono come configurare un account di servizio personalizzato da utilizzare con Agent Platform e come configurare un CustomJob, HyperparameterTuningJob, TrainingPipeline o DeployedModel per utilizzare il account di servizio. Tieni presente che non puoi configurare un account di servizio personalizzato per estrarre immagini da Artifact Registry. Gemini Enterprise Agent Platform utilizza l'account di servizio predefinito per estrarre le immagini.

Configurare un account di servizio personalizzato

Per configurare un account di servizio personalizzato:

  1. Crea un service account gestito dall'utente. Il account di serviziot gestito dall'utente può trovarsi nello stesso progetto delle risorse della piattaforma dell'agente o in un progetto diverso.

  2. Concedi al nuovo account di servizio i ruoli IAM che forniscono l'accesso ai servizi e alle risorse Google Cloud che vuoi che Agent Platform possa utilizzare durante l'addestramento personalizzato o la previsione.

  3. (Facoltativo) Se il account di servizio gestito dall'utente si trova in un progetto diverso dai tuoi job di addestramento, devi concedere il ruolo Service Account Token Creator (roles/iam.serviceAccountTokenCreator) al service agent di Agent Platform del progetto in cui utilizzi Agent Platform.

    gcloud iam service-accounts add-iam-policy-binding \
    --role=roles/iam.serviceAccountTokenCreator \
    --member=serviceAccount:AI_PLATFORM_SERVICE_AGENT \
    CUSTOM_SERVICE_ACCOUNT

  4. (Facoltativo) Se prevedi di utilizzare l'account di servizio gestito dall'utente anche per le previsioni, devi concedere il ruolo Amministratore service account (roles/iam.serviceAccountAdmin) al service agent della piattaforma di agenti del progetto in cui utilizzi la piattaforma di agenti:

    gcloud iam service-accounts add-iam-policy-binding \
  --role=roles/iam.serviceAccountAdmin \
  --member=serviceAccount:AI_PLATFORM_SERVICE_AGENT \
  CUSTOM_SERVICE_ACCOUNT

    Sostituisci quanto segue:

    • AI_PLATFORM_SERVICE_AGENT: l'indirizzo email dell'agente del servizio Agent Platform del tuo progetto, che ha il seguente formato:

      service-PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com

      Per trovare il service agent della piattaforma dell'agente, vai alla pagina IAM nella console Google Cloud .

      Vai a IAM

    • CUSTOM_SERVICE_ACCOUNT: l'indirizzo email del nuovo account di servizio gestito dall'utente che hai creato nel primo passaggio di questa sezione.

Specifica un account di servizio personalizzato per le risorse di Agent Platform

La procedura di configurazione di Agent Platform per utilizzare un service account specifico per una risorsa è denominata associazione del account di servizio alla risorsa. Le sezioni seguenti descrivono come collegare il service account creato nella sezione precedente a diverse risorse della piattaforma Agent.

Collega un account di servizio a una risorsa di addestramento personalizzato

Per configurare Agent Platform in modo che utilizzi il tuo nuovo service account durante l'addestramento personalizzato, specifica l'indirizzo email del account di servizio nel campo serviceAccount di un messaggio CustomJobSpec quando avvii l'addestramento personalizzato. A seconda del tipo di risorsa di addestramento personalizzato che stai creando, il posizionamento di questo campo nella richiesta API varia:

  • Se stai creando un CustomJob, specifica l'indirizzo email del account di servizio in CustomJob.jobSpec.serviceAccount.

    Scopri di più sulla creazione di un CustomJob.

  • Se stai creando un HyperparameterTuningJob, specifica l'indirizzo email del service account in HyperparameterTuningJob.trialJobSpec.serviceAccount.

    Scopri di più sulla creazione di un HyperparameterTuningJob.

  • Se stai creando un TrainingPipeline personalizzato senza ottimizzazione degli iperparametri, specifica l'indirizzo email dell'account di servizio in TrainingPipeline.trainingTaskInputs.serviceAccount.

  • Se stai creando un TrainingPipeline personalizzato con l'ottimizzazione degli iperparametri, specifica l'indirizzo email del account di servizio in TrainingPipeline.trainingTaskInputs.trialJobSpec.serviceAccount.

Collega un account di servizio a un container che fornisce previsioni online

Per configurare un contenitore di previsione Model addestrato personalizzato in modo che utilizzi il tuo nuovo service account, specifica l'indirizzo email del account di servizio quando esegui il deployment di Model in un Endpoint:

Console

Segui la procedura descritta in Deployment di un modello utilizzando la Google Cloud console. Quando specifichi le impostazioni del modello, seleziona il account di servizio nell'elenco a discesa Service account.

gcloud

Segui la procedura descritta in Deployment di un modello mediante l'API Agent Platform. Quando esegui il comando gcloud ai endpoints deploy-model, utilizza il flag --service-account per specificare l'indirizzo email delaccount di serviziot.

Prima di utilizzare i dati dei comandi riportati di seguito, effettua le seguenti sostituzioni:

  • ENDPOINT_ID: l'ID dell'endpoint.
  • LOCATION_ID: la regione in cui utilizzi Agent Platform.
  • MODEL_ID: l'ID del modello da implementare.
  • DEPLOYED_MODEL_NAME: un nome per DeployedModel. Puoi utilizzare il nome visualizzato di Model anche per DeployedModel.
  • MACHINE_TYPE: (Facoltativo) Le risorse macchina utilizzate per ogni nodo di questo deployment. L'impostazione predefinita è n1-standard-2. Scopri di più sui tipi di macchina.
  • MIN_REPLICA_COUNT: il numero minimo di nodi per questo deployment. Il conteggio di nodi può essere aumentato o diminuito in base al carico di inferenza, fino al numero massimo di nodi e mai al di sotto di questo numero di nodi.
  • MAX_REPLICA_COUNT: Il numero massimo di nodi per questo deployment. Il conteggio di nodi può essere aumentato o diminuito in base al carico di inferenza, fino a questo numero di nodi e mai al di sotto del numero minimo di nodi.
  • CUSTOM_SERVICE_ACCOUNT: l'indirizzo email del account di servizio. Ad esempio: SA_NAME@PROJECT_ID.iam.gserviceaccount.com.

Esegui il comando gcloud ai endpoints deploy-model:

Linux, macOS o Cloud Shell

gcloud ai endpoints deploy-model ENDPOINT_ID \
  --region=LOCATION \
  --model=MODEL_ID \
  --display-name=DEPLOYED_MODEL_NAME \
  --machine-type=MACHINE_TYPE \
  --min-replica-count=MIN_REPLICA_COUNT \
  --max-replica-count=MAX_REPLICA_COUNT \
  --traffic-split=0=100 \
  --service-account=CUSTOM_SERVICE_ACCOUNT

Windows (PowerShell)

gcloud ai endpoints deploy-model ENDPOINT_ID `
  --region=LOCATION `
  --model=MODEL_ID `
  --display-name=DEPLOYED_MODEL_NAME `
  --machine-type=MACHINE_TYPE `
  --min-replica-count=MIN_REPLICA_COUNT `
  --max-replica-count=MAX_REPLICA_COUNT `
  --traffic-split=0=100 `
  --service-account=CUSTOM_SERVICE_ACCOUNT

Windows (cmd.exe)

gcloud ai endpoints deploy-model ENDPOINT_ID ^
  --region=LOCATION ^
  --model=MODEL_ID ^
  --display-name=DEPLOYED_MODEL_NAME ^
  --machine-type=MACHINE_TYPE ^
  --min-replica-count=MIN_REPLICA_COUNT ^
  --max-replica-count=MAX_REPLICA_COUNT ^
  --traffic-split=0=100 ^
  --service-account=CUSTOM_SERVICE_ACCOUNT
  

API

Segui la procedura descritta in Deployment di un modello mediante l'API Agent Platform. Quando invii la projects.locations.endpoints.deployModel richiesta, imposta il campo deployedModel.serviceAccount sull'indirizzo email del account di servizio.

Collega un account di servizio a una richiesta CopyModel

Per configurare Agent Platform in modo che utilizzi il tuo nuovo service account quando copi un modello, specifica l'indirizzo email del account di servizio nel campo customServiceAccount del messaggio CopyModelRequest. Questo account di servizio deve appartenere al progetto di destinazione in cui viene copiato il modello e devi disporre dell'autorizzazione iam.serviceAccounts.actAs per questo account di servizio.

REST

Segui la procedura descritta in Copiare un modello utilizzando l'API Agent Platform, aggiungi il campo customServiceAccount nel corpo JSON della richiesta.

API

Quando invii la richiesta projects.locations.models.copy, imposta il campo customServiceAccount sull'indirizzo email del account di servizio.

Accedere ai servizi Google Cloud nel codice

Se configuri Agent Platform per utilizzare un account di servizio personalizzato seguendo le istruzioni nelle sezioni precedenti, il container di addestramento o il container di previsione possono accedere a qualsiasi servizio Google Cloud e risorsa a cui ha accesso il account di servizio.

Per accedere ai servizi Google Cloud , scrivi il tuo codice di addestramento o il tuo codice di servizio di previsione per utilizzare le credenziali predefinite dell'applicazione (ADC) e specifica esplicitamente l'ID progetto o il numero di progetto della risorsa a cui vuoi accedere. Scopri di più su come scrivere il codice per accedere ad altri Google Cloud servizi.

Limitazioni

I service account personalizzati in Gemini Enterprise Agent Platform presentano le seguenti limitazioni:

  • Per l'inferenza batch, l'agente di servizio della piattaforma Gemini Enterprise Agent verrà comunque utilizzato per accedere a BigQuery e Cloud Storage anche quando è configurato un account di servizio personalizzato.
  • Esiste un massimo di 20 service account personalizzati per progetto per regione per servizio (ad esempio, Vertex AI Inference).

Passaggi successivi