Autenticare le richieste API Vertex AI

Questa pagina descrive come autenticare le chiamate ai servizi Vertex AI su Google Distributed Cloud (GDC) air-gapped. Devi configurare l'autenticazione dei token per proteggere le richieste all'API Vertex AI nelle applicazioni air-gapped. Questo processo convalida le richieste API fornendo la tua identità e autorizzando le tue interazioni.

Questa pagina è rivolta agli sviluppatori di applicazioni all'interno dei gruppi di operatori di applicazioni responsabili della configurazione degli ambienti di sviluppo e delle applicazioni per abilitare le funzionalità di AI. Per saperne di più, consulta Pubblico per la documentazione di GDC con air gap.

Prima di iniziare

Per autenticare le richieste API e configurare i service account, richiedi le autorizzazioni necessarie all'amministratore. Assicurati inoltre di aver configurato il progetto per Vertex AI. Per saperne di più, consulta Configurare un progetto per Vertex AI.

  • Assicurati di aggiornare l'archivio di attendibilità locale prima di configurare l'autenticazione nell'ambiente di sviluppo.

Richiedere i ruoli IAM

Contatta l'amministratore IAM del progetto per richiedere i seguenti ruoli nello spazio dei nomi del progetto:

  • Project IAM Admin (project-iam-admin): crea service account e gestisci le associazioni di ruoli nello spazio dei nomi del progetto.
  • AI OCR Developer (ai-ocr-developer): autentica le richieste all'API OCR.
  • AI Speech Developer (ai-speech-developer): autentica le richieste all'API Speech-to-Text.
  • AI Speech Chirp Developer (ai-speech-chirp-developer): autentica le richieste al modello Speech-to-Text Chirp.
  • AI Text Embedding Developer (ai-text-embedding-developer): autentica le richieste al modello Text-Embedding-Gecko.
  • AI Text Embedding Multilingual Developer (ai-text-embedding-multilingual-developer): autentica le richieste al modello Text-Multilingual-Embedding.
  • AI Translation Developer (ai-translation-developer): autentica le richieste all'API Vertex AI Translation.
  • Vertex AI Prediction User (vertex-ai-prediction-user): autentica le richieste di previsione ai modelli predittivi online.

Per saperne di più su questi ruoli, consulta Prepara le autorizzazioni IAM.

Autenticazione ai servizi Vertex AI

Le interazioni con i servizi Vertex AI vengono eseguite tramite token di autenticazione. I token sono oggetti digitali che verificano la tua identità e autorizzazione dopo aver fornito credenziali valide. Il token contiene informazioni specifiche sul tuo account e sulle autorizzazioni per accedere e operare con servizi e risorse.

Esistono due modi per configurare l'autenticazione:

Autenticazione con l'account utente

La seguente procedura ti guida nell'ottenimento di un token di autenticazione per il tuo account utente:

  1. Prendi nota dell'endpoint dell'API che vuoi utilizzare.

  2. Ottieni l'accesso al servizio Vertex AI o al modello di AI generativa che vuoi utilizzare concedendo al tuo account utente il ruolo corrispondente elencato in Prepara le autorizzazioni IAM.

  3. Accedi a Distributed Cloud con l'account utente con cui devi interagire con l'API:

    gdcloud auth login

  4. Ottieni il token di autenticazione:

    gdcloud auth print-identity-token --audiences=https://ENDPOINT

    Sostituisci ENDPOINT con l'endpoint API che utilizzi per la tua organizzazione. Per saperne di più, consulta Stato del servizio ed endpoint.

    A seconda dell'utilizzo previsto del token di autenticazione, potrebbe essere necessario includere la porta dopo l'endpoint del servizio nel percorso dei destinatari come segue:

    • Se utilizzi una libreria client per la richiesta, devi includere la porta :443 dopo l'endpoint del servizio nel percorso dei destinatari. Pertanto, il percorso --audiences nel comando deve essere https://ENDPOINT:443.
    • Se utilizzi gRPC, curl o chiamate REST programmatiche per la richiesta, non includere la porta. Pertanto, il percorso --audiences nel comando deve essere https://ENDPOINT.

    L'output mostra il token di autenticazione. Aggiungi il token all'intestazione delle richieste della riga di comando che effettui, come nell'esempio seguente:

     -H "Authorization: Bearer TOKEN"

    Sostituisci TOKEN con il valore del token di autenticazione visualizzato nell'output.

Autenticazione con il account di servizio

La seguente procedura ti guida nell'ottenimento di un token di autenticazione per il tuo account di servizio:

  1. Prendi nota dell'endpoint dell'API che vuoi utilizzare.

  2. Configura il service account che vuoi utilizzare per accedere al servizio Vertex AI o al modello di AI generativa.

  3. Concedi al account di servizio il ruolo corrispondente elencato in Prepara le autorizzazioni IAM per consentirgli di accedere al servizio o al modello che vuoi utilizzare.

  4. Ottieni le coppie di chiavi di servizio del tuo service account.

  5. Imposta la seguente variabile di ambiente:

    export GOOGLE_APPLICATION_CREDENTIALS=PATH_TO_SERVICE_KEY

    Sostituisci PATH_TO_SERVICE_KEY con il percorso del file JSON contenente le coppie di chiavi del tuo account di servizio.

  6. Installa la libreria client google-auth:

    pip install google-auth

  7. Aggiungi il seguente codice a uno script Python:

    import os
import google.auth
from google.auth.transport import requests
import requests as reqs

os.environ["GOOGLE_APPLICATION_CREDENTIALS"] = "PATH_TO_SERVICE_KEY"
os.environ["GRPC_DEFAULT_SSL_ROOTS_FILE_PATH"] = "CERT_NAME"

# If you use a client library for your request,
# you must include port :443 after the service endpoint
# in the audience path.
audience = "https://ENDPOINT"

creds, project_id = google.auth.default()
print(project_id)
creds = creds.with_gdch_audience(audience)

def test_get_token():
  sesh = reqs.Session()
  req = requests.Request(session=sesh)
  creds.refresh(req)
  print(creds.token)

if __name__=="__main__":
  test_get_token()

    Sostituisci quanto segue:

    • PATH_TO_SERVICE_KEY: il percorso del file JSON contenente le coppie di chiavi del tuo account di servizio.
    • CERT_NAME: il nome del file del certificato dell'autorità di certificazione (CA), ad esempio org-1-trust-bundle-ca.cert. Questo valore è necessario solo se ti trovi in un ambiente di sviluppo. In caso contrario, omettilo.

    • ENDPOINT: l'endpoint API che utilizzi per la tua organizzazione. Per saperne di più, consulta Stato del servizio ed endpoint. A seconda dell'utilizzo previsto del token di autenticazione, potrebbe essere necessario includere la porta dopo l'endpoint del servizio nel percorso dei destinatari come segue:

      • Se utilizzi una libreria client per la richiesta, devi includere la porta :443 dopo l'endpoint del servizio nel percorso dei destinatari. Pertanto, il percorso audience nello script deve essere "https://ENDPOINT:443".
      • Se utilizzi gRPC, curl o chiamate REST programmatiche per la richiesta, non includere la porta. Pertanto, il audience percorso nello script deve essere "https://ENDPOINT".

  8. Salva lo script Python.

  9. Esegui lo script Python per recuperare il token:

      python SCRIPT_NAME

    Sostituisci SCRIPT_NAME con il nome che hai assegnato allo script Python, ad esempio token.py.

    L'output mostra il token di autenticazione. Aggiungi il token all'intestazione delle richieste della riga di comando che effettui, come nell'esempio seguente:

     -H "Authorization: Bearer TOKEN"

    Sostituisci TOKEN con il valore del token di autenticazione visualizzato nell'output.