Esegui il deployment di un'applicazione di AI con agenti su GKE con Agent Development Kit (ADK) e un LLM self-hosted

Questo tutorial mostra come eseguire il deployment e gestire applicazioni di AI/ML agentiche containerizzate utilizzando Google Kubernetes Engine (GKE). Combinando Google Agent Development Kit (ADK) con un modello linguistico di grandi dimensioni (LLM) self-hosted come Llama 3.1 fornito da vLLM, puoi rendere operativi gli agenti AI in modo efficiente e su scala, mantenendo il pieno controllo dello stack di modelli. Questo tutorial illustra l'intero processo di sviluppo e deployment di un agente basato su Python in produzione su un cluster GKE Autopilot con accelerazione GPU.

Questo tutorial è rivolto a ingegneri di machine learning (ML), sviluppatori e architetti cloud interessati a utilizzare le funzionalità di orchestrazione dei container Kubernetes per pubblicare applicazioni di AI/ML con agenti. Per scoprire di più sui ruoli comuni e sulle attività di esempio a cui facciamo riferimento nei contenuti di Google Cloud GKE Enterprise, consulta Ruoli e attività comuni degli utenti di GKE Enterprise.

Prima di iniziare, assicurati di avere familiarità con quanto segue:

Sfondo

Questa sezione descrive le tecnologie chiave utilizzate in questo tutorial.

Agent Development Kit (ADK)

Agent Development Kit (ADK) è un framework flessibile e modulare per lo sviluppo e il deployment di agenti AI. Sebbene sia ottimizzato per Gemini e l'ecosistema Google, ADK non richiede l'utilizzo di un modello o di un deployment specifico ed è progettato per la compatibilità con altri framework. ADK è stato progettato per rendere lo sviluppo di agenti più simile allo sviluppo di software, in modo che gli sviluppatori possano creare, implementare e orchestrare più facilmente architetture agentiche che vanno da attività di base a workflow complessi.

Per saperne di più, consulta la documentazione dell'ADK.

Servizio Kubernetes gestito GKE

Google Cloud offre una gamma di servizi, tra cui GKE, particolarmente adatti per il deployment e la gestione dei carichi di lavoro di AI/ML. GKE è un servizio Kubernetes gestito che semplifica il deployment, la scalabilità e la gestione delle applicazioni containerizzate. GKE fornisce l'infrastruttura necessaria, tra cui risorse scalabili, computing distribuito e networking efficiente, per gestire le richieste di calcolo dei LLM.

Per saperne di più sui concetti chiave di Kubernetes, consulta Inizia a scoprire Kubernetes. Per saperne di più su GKE e su come ti aiuta a scalare, automatizzare e gestire Kubernetes, consulta la panoramica di GKE.

vLLM

vLLM è un framework di erogazione di LLM open source altamente ottimizzato che può aumentare la velocità effettiva di erogazione sulle GPU, con funzionalità come le seguenti:

  • Implementazione ottimizzata del transformer con PagedAttention.
  • Batching continuo per migliorare la velocità effettiva complessiva della pubblicazione.
  • Parallelismo dei tensori e pubblicazione distribuita su più GPU.

Per saperne di più, consulta la documentazione di vLLM.

Prepara l'ambiente

Questo tutorial utilizza Cloud Shell per gestire le risorse ospitate su Google Cloud. Cloud Shell è preinstallato con il software necessario per questo tutorial, tra cui kubectl, terraform e Google Cloud CLI.

Per configurare l'ambiente con Cloud Shell:

  1. Nella console Google Cloud , avvia una sessione Cloud Shell e fai clic su Icona di attivazione di Cloud Shell Attiva Cloud Shell. Questa azione avvia una sessione in un riquadro della console Google Cloud .

  2. Imposta le variabili di ambiente predefinite:

    gcloud config set project PROJECT_ID
export GOOGLE_CLOUD_REGION=REGION
export PROJECT_ID=PROJECT_ID

    Sostituisci i seguenti valori:

    • PROJECT_ID: il tuo Google Cloud ID progetto.
    • REGION: la regione Google Cloud (ad esempio us-east4) in cui eseguire il provisioning del cluster GKE, di Artifact Registry e di altre risorse regionali. Assicurati di specificare una regione che supporti le GPU L4 e le istanze del tipo di macchina G2. Per verificare la disponibilità delle regioni, consulta la sezione Regioni e zone GPU nella documentazione di Compute Engine.

Clona il progetto di esempio

  1. Dal terminale di Cloud Shell, clona il repository del codice campione del tutorial:

    git clone https://github.com/GoogleCloudPlatform/kubernetes-engine-samples.git

  2. Vai alla directory del tutorial:

    cd kubernetes-engine-samples/ai-ml/adk-vllm

Creare e configurare risorse Google Cloud

Per eseguire il deployment dell'agente, devi prima eseguire il provisioning delle risorse Google Cloud necessarie. Puoi creare il cluster GKE e il repository Artifact Registry utilizzando gcloud CLI o Terraform.

gcloud

Questa sezione fornisce i comandi gcloud CLI per configurare il cluster GKE e Artifact Registry.

  1. Crea un cluster GKE: puoi eseguire il deployment dell'applicazione agentica containerizzata in un cluster GKE Autopilot o Standard. Utilizza un cluster Autopilot per un'esperienza Kubernetes completamente gestita. Per scegliere la modalità operativa GKE più adatta ai tuoi workload, consulta Informazioni sulle modalità operative di GKE.

    Autopilot

    In Cloud Shell, esegui questo comando:

    gcloud container clusters create-auto CLUSTER_NAME \
    --location=$GOOGLE_CLOUD_REGION

    Sostituisci CLUSTER_NAME con il nome del tuo cluster GKE.

    Con Autopilot, GKE esegue automaticamente il provisioning dei nodi in base alle richieste di risorse del tuo workload. La GPU richiesta per l'LLM viene richiesta nel manifest deploy-llm.yaml utilizzando un nodeSelector.

    Per aggiungere una richiesta nodeSelector per la GPU nvidia-l4:

    1. Apri kubernetes-engine-samples/ai-ml/adk-vllm/deploy-llm/deploy-llm.yaml in un editor.

    2. Aggiungi il seguente codice nodeSelector in spec.template.spec:

      nodeSelector:
cloud.google.com/gke-accelerator: nvidia-l4

    Standard

    1. In Cloud Shell, crea un cluster Standard eseguendo questo comando:

      gcloud container clusters create CLUSTER_NAME \
    --location=$GOOGLE_CLOUD_REGION

      Sostituisci CLUSTER_NAME con il nome del tuo cluster GKE.

    2. Crea un node pool abilitato per la GPU per il tuo cluster eseguendo il seguente comando:

      gcloud container node-pools create gpu-node-pool \
    --cluster=CLUSTER_NAME \
    --location=$GOOGLE_CLOUD_REGION \
    --machine-type=g2-standard-8 \
    --accelerator=type=nvidia-l4,count=1 \
    --enable-gvnic

      Il file deploy-llm.yaml specifica una GPU nvidia-l4, disponibile nella serie di macchine G2. Per saperne di più su questo tipo di macchina, consulta Tipi di macchine GPU nella documentazione di Compute Engine.

  2. Crea un repository Artifact Registry: crea un repository Artifact Registry per archiviare e gestire in modo sicuro l'immagine container Docker dell'agente.

    gcloud artifacts repositories create REPO_NAME \
    --repository-format=docker \
    --location=$GOOGLE_CLOUD_REGION

    Sostituisci REPO_NAME con il nome del repository Artifact Registry che vuoi utilizzare (ad esempio adk-repo).

  3. Ottieni l'URL del repository: per verificare il percorso completo del repository, esegui questo comando. Utilizzerai questo formato per taggare l'immagine Docker quando crei l'immagine dell'agente.

    gcloud artifacts repositories describe REPO_NAME \
    --location $GOOGLE_CLOUD_REGION

Terraform

Questa sezione descrive come utilizzare la configurazione Terraform inclusa nel repository di esempio per eseguire il provisioning automatico delle risorse Google Cloud .

  1. Vai alla directory Terraform: la directory \terraform contiene tutti i file di configurazione necessari per creare il cluster GKE e altre risorse richieste.

    cd terraform

  2. Crea un file di variabili Terraform: copia il file di variabili di esempio fornito (example_vars.tfvars) per creare il tuo file vars.tfvars.

    cp example_vars.tfvars vars.tfvars

    Apri il file vars.tfvars in un editor e sostituisci i valori segnaposto con la tua configurazione specifica. Come minimo, devi sostituire PROJECT_ID con l' Google Cloud ID progetto e CLUSTER_NAME con il nome del tuo cluster GKE.

  3. Inizializza Terraform: per scaricare i plug-in del provider necessari per Google Cloud, esegui questo comando.

    terraform init

  4. Rivedi il piano di esecuzione: questo comando mostra le modifiche all'infrastruttura che Terraform apporterà.

    terraform plan -var-file=vars.tfvars

  5. Applica la configurazione: per creare le risorse nel tuo progetto Google Cloud , esegui il piano Terraform. Conferma con yes quando richiesto.

    terraform apply -var-file=vars.tfvars

Dopo aver eseguito questi comandi, Terraform esegue il provisioning del cluster GKE e del repository Artifact Registry e configura i service account e i ruoli IAM necessari, inclusa Workload Identity Federation for GKE.

Per scoprire di più sull'utilizzo di Terraform, consulta Eseguire il provisioning delle risorse GKE con Terraform.

Configura kubectl per comunicare con il cluster

Per configurare kubectl in modo che comunichi con il cluster, esegui questo comando:

gcloud container clusters get-credentials CLUSTER_NAME \
    --location=${GOOGLE_CLOUD_REGION}

Sostituisci CLUSTER_NAME con il nome del tuo cluster GKE.

Crea l'immagine dell'agente

Dopo aver creato l'infrastruttura utilizzando gcloud CLI o Terraform, segui questi passaggi per creare l'applicazione agente.

  1. Concedi il ruolo IAM richiesto per Cloud Build: il servizio Cloud Build richiede le autorizzazioni per eseguire il push dell'immagine container dell'agente in Artifact Registry. Concedi il ruolo roles/artifactregistry.writer al account di servizio Compute Engine predefinito, utilizzato da Cloud Build.

    1. Crea l'email per il account di servizio predefinito di Compute Engine:

      export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
export COMPUTE_SA_EMAIL=${PROJECT_NUMBER}-compute@developer.gserviceaccount.com

    2. Concedi il ruolo roles/artifactregistry.writer al service account:

      gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member=serviceAccount:${COMPUTE_SA_EMAIL} \
    --role=roles/artifactregistry.writer

  2. Crea ed esegui il push dell'immagine container dell'agente: dalla directory principale del progetto (adk/llama/vllm), crea l'immagine Docker ed eseguine il push in Artifact Registry eseguendo questi comandi.

    export IMAGE_URL="${GOOGLE_CLOUD_REGION}-docker.pkg.dev/${PROJECT_ID}/REPO_NAME/adk-agent:latest"
gcloud builds submit --tag $IMAGE_URL

  3. Verifica che l'immagine sia stata inviata: al termine della processo di compilazione, verifica che l'immagine container dell'agente sia stata inviata ad Artifact Registry elencando le immagini nel repository.

    gcloud artifacts docker images list ${GOOGLE_CLOUD_REGION}-docker.pkg.dev/${PROJECT_ID}/REPO_NAME

    Dovresti visualizzare un output che elenca l'immagine che hai appena inviato e taggato come latest.

Esegui il deployment del modello

Dopo aver configurato il cluster GKE e creato l'immagine dell'agente, il passaggio successivo consiste nell'eseguire il deployment del modello Llama 3.1 autogestito nel cluster. Per farlo, esegui il deployment di un server di inferenza vLLM preconfigurato che estrae il modello da Hugging Face e lo gestisce internamente all'interno del cluster.

  1. Crea un secret Kubernetes per le credenziali di Hugging Face: per consentire al cluster GKE di scaricare il modello Llama 3.1 con accesso controllato, devi fornire il tuo token Hugging Face come secret Kubernetes. Il manifest deploy-llm.yaml è configurato per utilizzare questo secret per l'autenticazione.

    kubectl create secret generic hf-secret \
    --from-literal=hf-token-secret=HUGGING_FACE_TOKEN

    Sostituisci HUGGING_FACE_TOKEN con il tuo token.

  2. Visualizza il manifest: dalla directory root del progetto (adk/llama/vllm), vai alla directory /deploy-llm che contiene il manifest di Deployment del modello.

    cd deploy-llm

  3. Applica il manifest: esegui questo comando per applicare il manifest deploy-llm.yaml al cluster.

    kubectl apply -f deploy-llm.yaml

    Il comando crea tre risorse Kubernetes:

    • Un deployment che esegue il server vLLM, configurato per utilizzare il modello meta-llama/Llama-3.1-8B-Instruct.
    • Un servizio denominato vllm-llama3-service che espone il server vLLM su un indirizzo IP del cluster interno, consentendo all'agente ADK di comunicare con esso.
    • Un oggetto ConfigMap contenente un modello di chat Jinja richiesto dal modello Llama 3.1.

  4. Verifica il deployment del modello: il server vLLM estrae i file del modello da Hugging Face. Questa procedura può richiedere alcuni minuti. Puoi monitorare lo stato del Pod per assicurarti che sia pronto.

    1. Attendi che il deployment diventi disponibile.

      kubectl wait --for=condition=available --timeout=600s deployment/vllm-llama3-deployment

    2. Visualizza i log del pod in esecuzione per verificare che il server sia stato avviato correttamente.

      export LLM_POD=$(kubectl get pods -l app=vllm-llama3 -o jsonpath='{.items[0].metadata.name}')
kubectl logs -f $LLM_POD

      Il deployment è pronto quando vedi un output del log simile al seguente, che indica che il server LLM è stato avviato e le route API sono disponibili:

      INFO 07-16 14:15:16 api_server.py:129] Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

    3. Invia una richiesta direttamente al server del modello per verificare che il LLM sia pronto. Per farlo, apri un nuovo terminale Cloud Shell ed esegui questo comando per inoltrare vllm-llama3-service alla tua macchina locale:

      kubectl port-forward service/vllm-llama3-service 8000:8000

    4. In un altro terminale, invia una richiesta di esempio all'endpoint API del modello utilizzando curl. Ad esempio:

      curl -X POST http://localhost:8000/v1/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "meta-llama/Llama-3.1-8B-Instruct",
    "prompt": "Hello!",
    "max_tokens": 10
  }'

      Se il comando restituisce una risposta JSON riuscita, il tuo LLM è pronto. Ora puoi terminare il processo di port forwarding tornando alla finestra del terminale e premendo Ctrl+C, quindi procedi con il deployment dell'agente.

Esegui il deployment dell'applicazione dell'agente

Il passaggio successivo consiste nel deployment dell'applicazione agente basata sull'ADK.

  1. Vai alla directory /deploy-agent: dalla directory principale del progetto (adk/llama/vllm), vai alla directory /deploy-agent che contiene il codice sorgente e il manifest di deployment dell'agente.

    cd ../deploy-agent

  2. Aggiorna il manifest di deployment dell'agente:

    1. Il file manifest deploy-agent.yaml di esempio contiene un segnaposto per l'ID progetto nell'URL dell'immagine container. Devi sostituire il segnaposto con l'ID del tuo progetto Google Cloud .

      image: us-central1-docker.pkg.dev/PROJECT_ID/adk-repo/adk-agent:latest

      Per eseguire questa sostituzione sul posto, puoi eseguire il seguente comando:

      sed -i "s/<PROJECT_ID>/$PROJECT_ID/g" deploy-agent.yaml

    2. Assicurati che il percorso readinessProbe sia impostato su / anziché su /dev-ui. Per eseguire questa sostituzione sul posto, puoi eseguire il seguente comando:

      sed -i "s|path: /dev-ui/|path: /|g" deploy-agent.yaml

  3. Applica il manifest: esegui questo comando per applicare il manifest deploy-agent.yaml al cluster.

    kubectl apply -f deploy-agent.yaml

    Questo comando crea due risorse Kubernetes:

    • Un deployment denominato adk-agent che esegue l'immagine container dell'agente creato personalizzato.
    • Un servizio denominato adk-agent di tipo NodePort che espone l'applicazione agente in modo che sia accessibile per i test.

  4. Verifica il deployment dell'agente: controlla lo stato del pod per assicurarti che sia in esecuzione correttamente.

    1. Attendi che il deployment diventi disponibile:

      kubectl wait --for=condition=available --timeout=300s deployment/adk-agent

    2. Visualizza i log del pod dell'agente in esecuzione:

      export AGENT_POD=$(kubectl get pods -l app=adk-agent -o jsonpath='{.items[0].metadata.name}')
kubectl logs -f $AGENT_POD

Il deployment ha esito positivo quando viene visualizzato un output del log simile al seguente, che indica che il server Uvicorn è in esecuzione e pronto ad accettare richieste:

INFO:     Uvicorn running on http://0.0.0.0:8001 (Press CTRL+C to quit)

Testare l'agente di cui è stato eseguito il deployment

Dopo aver eseguito il deployment del server vLLM e dell'applicazione agente, puoi testare la funzionalità end-to-end interagendo con l'interfaccia utente web dell'agente.

  1. Inoltra il servizio dell'agente alla tua macchina locale: il servizio adk-agent è di tipo NodePort, ma il modo più diretto per accedervi dal tuo ambiente Cloud Shell è utilizzare il comando kubectl port-forward. Crea un tunnel sicuro al pod dell'agente eseguendo questo comando.

    kubectl port-forward $AGENT_POD 8001:8001

  2. Accedi alla UI web dell'agente: in Cloud Shell, fai clic sul pulsante Anteprima web e seleziona Anteprima sulla porta 8001. Si apre una nuova scheda del browser che mostra l'interfaccia di chat dell'agente.

  3. Interagisci con l'agente: poni all'agente una domanda che richiami il suo strumento get_weather. Ad esempio:

    What's the weather like in Tokyo?

    L'agente chiamerà prima l'LLM per comprendere l'intent e identificare la necessità di utilizzare lo strumento get_weather. Poi, eseguirà lo strumento con "Tokyo" come parametro. Infine, utilizzerà l'output dello strumento per generare una risposta. Dovresti visualizzare una risposta simile alla seguente:

      The weather in Tokyo is 25°C and sunny.

  4. (Facoltativo) Verifica la chiamata allo strumento nei log: puoi osservare l'interazione dell'agente con il LLM e l'esecuzione dello strumento visualizzando i log dei rispettivi pod.

    1. Log del pod dell'agente: in un nuovo terminale, visualizza i log del pod adk-agent. Vedi la chiamata allo strumento e il relativo risultato.

      kubectl logs -f $AGENT_POD

      L'output mostra la chiamata allo strumento e l'elaborazione del risultato.

    2. Log del pod LLM: visualizza i log del pod vllm-llama3-deployment per vedere la richiesta in arrivo dall'agente.

      kubectl logs -f $LLM_POD

      I log mostrano il prompt completo inviato dall'agente al LLM, incluso il messaggio di sistema, la query e la definizione dello strumento get_weather.

Al termine del test, puoi terminare il processo port-forward tornando alla finestra del terminale e premendo Ctrl+C.