Configurare un'estensione per chiamare un servizio Google

Service Extensions consente ai bilanciatori del carico delle applicazioni supportati di configurare le estensioni utilizzando i callout ai servizi Google. Questa pagina mostra come configurare queste estensioni.

Per una panoramica, vedi Integrazione con i servizi Google.

Configura un'estensione del traffico per chiamare il servizio Model Armor

Puoi configurare un'estensione del traffico per chiamare Model Armor per applicare in modo uniforme le policy di sicurezza al traffico di inferenza dell'AI generativa ai bilanciatori del carico delle applicazioni, incluso GKE Inference Gateway.

Un'estensione del traffico raggruppa i servizi di estensione correlati in una o più catene. Puoi configurare sia i plug-in sia i callout nella stessa catena di estensioni. Ogni catena di estensioni seleziona il traffico su cui agire utilizzando le condizioni di corrispondenza Common Expression Language (CEL). Il bilanciatore del carico valuta una richiesta in base alla condizione di corrispondenza di ogni catena in modo sequenziale. Quando una richiesta corrisponde alle condizioni definite da una catena, tutte le estensioni della catena agiscono sulla richiesta. Solo una catena corrisponde a una determinata richiesta.

Ogni estensione di una catena può avere il proprio insieme di eventi supportati. Le modifiche apportate da un'estensione ai contenuti di richiesta e risposta sono visibili alle estensioni rimanenti nella catena. Per le estensioni configurate per supportare gli eventi di risposta, la sequenza di estensioni viene invertita nel percorso di risposta.

L'estensione del traffico viene collegata a una regola di forwarding del bilanciatore del carico creata utilizzando il gateway di inferenza. Dopo aver configurato la risorsa, le richieste corrispondenti vengono inviate al servizio Model Armor.

Prima di iniziare

Identifica un progetto adatto in cui disponi del ruolo di proprietario o editor del progetto oppure dei seguenti ruoli IAM di Compute Engine:
- Per creare istanze: Compute Instance Admin (v1) (roles/compute.instanceAdmin.v1)
- Per creare componenti Cloud Load Balancing: Compute Network Admin (roles/compute.networkAdmin)
Abilita le API richieste.
Console
1. Nella console Google Cloud , vai alla pagina Abilita l'accesso alle API.
  
  Vai ad Attiva l'accesso alle API
2. Segui le istruzioni per abilitare le API richieste, tra cui l'API Compute Engine, l'API Model Armor e l'API Network Services.
gcloud
Utilizza il comando gcloud services enable:
```
gcloud services enable compute.googleapis.com modelarmor.googleapis.com networkservices.googleapis.com
```
Crea i modelli Model Armor richiesti.
Configura l'infrastruttura Google Kubernetes Engine eseguendo il deployment di un gateway di inferenza. Testalo inviando una richiesta di inferenza.

Con alcune limitazioni, sono supportati i seguenti endpoint dell'API OpenAI: Assistenti, Completamenti della chat, Completamenti (legacy), Messaggi e Thread.

Limitazioni durante la configurazione di un endpoint API OpenAI

Quando configuri un endpoint API OpenAI per la tua infrastruttura GKE, tieni presenti le seguenti limitazioni relative alla pulizia di prompt e risposte:

Le risposte dell'API di streaming non sono supportate per nessuna API. Se utilizzi un mix di API di streaming e non streaming, quando configuri l'estensione del traffico, imposta failOpen su true. Model Armor sanifica le risposte non dinamiche e ignora le risposte dinamiche.
Quando vengono sanificati prompt e risposte, sono supportate solo le seguenti operazioni:
- API Assistants: Create, Delete, List, Modify e Retrieve
- API Chat Completions: Create, Delete, Get Chat Completion, Get Chat Message, List e Update
- API Completions (legacy): Create
- API Messages: Create, Delete, List, Modify e Retrieve
- API Threads: Create, Delete, Modify e Retrieve
Per le chiamate API che restituiscono più scelte nella risposta (ad esempio POST https://api.openai.com/v1/chat/completions), viene sanificato solo il primo elemento dell'elenco di scelte.

Configurare l'estensione del traffico

Controlla il comportamento prima che l'estensione venga configurata inviando una richiesta di inferenza al bilanciatore del carico e specificando l'indirizzo IP esposto del bilanciatore del carico:

curl -v http://${IP}/v1/chat/completions
  -H "Content-Type: application/json" \
  -H 'Authorization: Bearer $(gcloud auth print-access-token)' \
  -d '{"model": "meta-llama/Llama-3.1-8B-Instruct",
       "messages": [
          {
            "role": "user",
            "content": "Can you remember my ITIN: 123-45-6789"
          }
        ],
       "max_tokens": 250,
       "temperature": 0.1}'

La richiesta genera un codice di stato HTTP 200 OK anche se sono stati inviati dati sensibili al LLM.

Per consentire a Model Armor di bloccare i prompt che contengono dati sensibili, configura un'estensione del traffico.
Console
1. Nella console Google Cloud , vai alla pagina Estensioni di servizio.
  
  Vai a Service Extensions
2. Fai clic su Crea estensione. Si apre una procedura guidata che ti guiderà attraverso alcuni passaggi iniziali.
3. Per il prodotto, seleziona Bilanciamento del carico. Quindi, fai clic su Continua. Viene visualizzato un elenco di bilanciatori del carico delle applicazioni supportati.
4. Seleziona un tipo di bilanciatore del carico.
5. Specifica la regione come us-central1. Fai clic su Continua.
6. Per il tipo di estensione, seleziona Estensioni di traffico, quindi fai clic su Continua.
7. Per aprire il modulo Crea estensione, fai clic su Continua. Nel modulo Crea estensione, nota che le selezioni precedenti non sono modificabili.
8. Nella sezione Nozioni di base, segui questi passaggi:
  1. Specifica un nome univoco per l'estensione.
    
    Il nome deve iniziare con una lettera minuscola seguita da un massimo di 62 lettere minuscole, numeri o trattini e non può terminare con un trattino.
  2. (Facoltativo) Inserisci una breve descrizione dell'estensione utilizzando fino a 1024 caratteri.
  3. (Facoltativo) Nella sezione Etichette, fai clic su Aggiungi etichetta. Quindi, nella riga visualizzata, procedi nel seguente modo:
    
    In Chiave, inserisci un nome per la chiave.
    
    In Valore, inserisci un valore per la chiave.
    
    Per aggiungere altre coppie chiave-valore, fai clic su Aggiungi etichetta. Puoi aggiungere un massimo di 64 coppie chiave-valore.
    
    Per saperne di più sulle etichette, consulta Creare e aggiornare le etichette per i progetti.
9. Per Regole di forwarding, seleziona una o più regole di forwarding da associare all'estensione. Scegli una regola di forwarding generata durante il deployment di Inference Gateway. Le regole di inoltro già associate a un'altra estensione non possono essere selezionate e vengono visualizzate come non disponibili.
10. Per le catene di estensioni, aggiungi una o più catene di estensioni da eseguire per una richiesta corrispondente.
  
  Per aggiungere una catena di estensioni, procedi nel seguente modo, quindi fai clic su Fine:
  - Per Nome nuova catena di estensioni, specifica un nome univoco.
    
    Il nome deve essere conforme a RFC-1034, utilizzare solo lettere minuscole, numeri e trattini e avere una lunghezza massima di 63 caratteri. Inoltre, il primo carattere deve essere una lettera e l'ultimo carattere deve essere una lettera o un numero.
  - Per trovare le richieste per le quali viene eseguita la catena di estensioni, specifica un'espressione Common Expression Language (CEL) per Condizione di corrispondenza, ad esempio request.path == "/v1/chat/completions".
    
    Per ulteriori informazioni sulle espressioni CEL, fai clic su Guida alla sintassi o consulta il riferimento al linguaggio del matcher CEL.
  - Aggiungi una o più estensioni da eseguire per una richiesta corrispondente.
    
    Per ogni estensione, nella sezione Estensioni, procedi nel seguente modo e poi fai clic su Fine:
    
    In Nome estensione, specifica un nome univoco.
    
    Il nome deve essere conforme a RFC-1034, utilizzare solo lettere minuscole, numeri e trattini e avere una lunghezza massima di 63 caratteri. Inoltre, il primo carattere deve essere una lettera e l'ultimo carattere deve essere una lettera o un numero.
    
    In Tipo di programmabilità, seleziona Servizi Google e poi seleziona un endpoint del servizio Model Armor, ad esempio modelarmor.us-central1.rep.googleapis.com.
    
    Per Timeout, specifica un valore compreso tra 10 e 1000 millisecondi dopo il quale un messaggio nello stream scade. Tieni presente che Model Armor ha una latenza di circa 250 millisecondi.
    
    Per Eventi, seleziona tutti i tipi di eventi HTTP.
    
    Per Inoltra intestazioni, fai clic su Aggiungi intestazione e poi aggiungi le intestazioni HTTP da inoltrare all'estensione (dal client o dal backend). Se non viene specificata un'intestazione, vengono inviate tutte le intestazioni.
    
    (Facoltativo) Se l'estensione scade o non funziona e vuoi che l'elaborazione della richiesta o della risposta continui, per Fail open, seleziona Attivato. Vengono eseguite anche le estensioni successive nella catena.
    
    Per impostazione predefinita, l'opzione Fail open non è selezionata. In questo caso, quando si verifica un errore, l'elaborazione della richiesta o della risposta si interrompe. Se le intestazioni della risposta non sono state inviate al client downstream, al client viene restituito un codice di stato HTTP 500 generico. Se le intestazioni della risposta sono state recapitate, il flusso HTTP al client viene reimpostato.
    
    L'opzione predefinita di non selezionare Fail open è preferibile quando si dà la priorità alla sicurezza o all'integrità. L'attivazione di Fail open, in particolare per le operazioni non critiche, è utile quando si dà la priorità alla disponibilità.
    
    In Metadati, fai clic su Aggiungi metadati per specificare i modelli Model Armor da utilizzare per filtrare prompt e risposte corrispondenti a modelli specifici.
    
    In Chiave, specifica model_armor_settings. Per Valore, specifica i modelli come stringa JSON, ad esempio:
    
    [{ "model": "MODEL_NAME", "model_response_template_id": "projects/TEMPLATE_PROJECT_ID/locations/LOCATION/templates/RESPONSE_TEMPLATE", "user_prompt_template_id": "projects/TEMPLATE_PROJECT_ID/locations/LOCATION/templates/PROMPT_TEMPLATE" }]
    
    Sostituisci quanto segue:
    
    MODEL_NAME: il nome del modello come configurato con la risorsa InferenceModel, ad esempio meta-llama/Llama-3.1-8B-Instruct
    
    TEMPLATE_PROJECT_ID: l'ID progetto dei modelli Model Armor
    
    LOCATION: la posizione del modello Model Armor, ad esempio us-central1
    
    RESPONSE_TEMPLATE: il template di risposta da utilizzare per il modello
    
    PROMPT_TEMPLATE: il modello di prompt da utilizzare
    
    È possibile specificare un modello predefinito da utilizzare quando una richiesta non corrisponde esattamente a un modello. Per configurare un modello predefinito, specifica MODEL_NAME come default.
    
    Se non vuoi traffico di prompt o risposte dello schermo, crea e includi un modello di filtro vuoto.
    
    La dimensione totale di metadata deve essere inferiore a 1 KiB. Il numero totale di chiavi nei metadati deve essere inferiore a 20. La lunghezza di ogni chiave deve essere inferiore a 64 caratteri. La lunghezza di ogni valore deve essere inferiore a 1024 caratteri. Tutti i valori devono essere stringhe.
    
    Quando una richiesta viene bloccata, Model Armor restituisce un codice di stato 403 Forbidden standard. Puoi ignorare lo stato definendo impostazioni di risposta personalizzate (inclusi un codice di stato e un messaggio personalizzati) nella policy di sicurezza del modello Model Armor. Per i dettagli, vedi TemplateMetadata.
11. Fai clic su Crea estensione.
gcloud
1. Definisci il callout in un file YAML e associalo alla regola di forwarding generata durante il deployment di Inference Gateway. Utilizza i valori di esempio forniti.
  cat >traffic_callout_service.yaml <<EOF name: traffic-ext forwardingRules: - https://www.googleapis.com/compute/v1/projects/LB_PROJECT_ID/regions/us-central1/forwardingRules/FORWARDING_RULE loadBalancingScheme: INTERNAL_MANAGED extensionChains: - name: "chain1-model-armor" matchCondition: celExpression: 'request.path == "/v1/chat/completions"' extensions: - name: extension-chain-1-model-armor service: modelarmor.us-central1.rep.googleapis.com failOpen: true supportedEvents: - REQUEST_HEADERS - REQUEST_BODY - REQUEST_TRAILERS - RESPONSE_HEADERS - RESPONSE_BODY - RESPONSE_TRAILERS timeout: 1s metadata: model_armor_settings: '[ { "model": "MODEL_NAME", "model_response_template_id": "projects/TEMPLATE_PROJECT_ID/locations/LOCATION/templates/RESPONSE_TEMPLATE", "user_prompt_template_id": "projects/TEMPLATE_PROJECT_ID/locations/LOCATION/templates/PROMPT_TEMPLATE" } ]' EOF
  Sostituisci quanto segue:
  - TEMPLATE_PROJECT_ID: l'ID progetto dei modelli Model Armor
  - LB_PROJECT_ID: l'ID progetto della regola di forwarding del bilanciatore del carico
  - FORWARDING_RULE: una o più regole di inoltro da associare all'estensione. Scegli una regola di forwarding generata nell'ambito del deployment di Inference Gateway.
    
    Le regole di inoltro già associate a un'altra estensione non possono essere selezionate e vengono visualizzate come non disponibili.
  - MODEL_NAME: il nome del modello come configurato con la risorsa InferenceModel, ad esempio meta-llama/Llama-3.1-8B-Instruct
  - LOCATION: la posizione del modello Model Armor, ad esempio us-central1
  - RESPONSE_TEMPLATE: il template di risposta da utilizzare per il modello
  - PROMPT_TEMPLATE: il modello di prompt da utilizzare
  Nel campo metadata, specifica le impostazioni e i modelli di Model Armor da utilizzare durante il controllo dei prompt e delle risposte corrispondenti a modelli specifici.
  
  È possibile specificare un modello predefinito da utilizzare quando una richiesta non corrisponde esattamente a un modello. Per configurare un modello predefinito, specifica MODEL_NAME come default.
  
  Se non vuoi traffico di prompt o risposte dello schermo, crea e includi un modello di filtro vuoto.
  
  La dimensione totale di metadata deve essere inferiore a 1 KiB. Il numero totale di chiavi nei metadati deve essere inferiore a 16. La lunghezza di ogni chiave deve essere inferiore a 64 caratteri. La lunghezza di ogni valore deve essere inferiore a 1024 caratteri. Tutti i valori devono essere stringhe.
  
  Quando una richiesta viene bloccata, Model Armor restituisce un codice di stato 403 Forbidden standard. Puoi ignorare lo stato definendo impostazioni di risposta personalizzate (inclusi un codice di stato e un messaggio personalizzati) nella policy di sicurezza del modello Model Armor. Per i dettagli, vedi TemplateMetadata.
2. Importa l'estensione traffico. Utilizza il comando gcloud service-extensions lb-traffic-extensions import con i seguenti valori di esempio.
  gcloud service-extensions lb-traffic-extensions import traffic-ext \ --source=traffic_callout_service.yaml \ --location=us-central1
kubectl
1. Se utilizzi una versione di GKE precedente alla v1.32.2-gke.1182001, installa il CRD dell'estensione di gestione del traffico:
  kubectl apply -f https://raw.githubusercontent.com/GoogleCloudPlatform/gke-gateway-api/refs/heads/main/config/crd/networking.gke.io_gcptrafficextensions.yaml
2. Definisci l'estensione in un file YAML. Questa risorsa personalizzata collega il tuo Inference Gateway al servizio Model Armor. Utilizza i valori di esempio forniti.
  cat >traffic_callout_service.yaml <<EOF apiVersion: networking.gke.io/v1 kind: GCPTrafficExtension metadata: name: traffic-ext spec: targetRefs: - group: "gateway.networking.k8s.io" kind: Gateway name: inference-gateway extensionChains: - name: "chain1-model-armor" matchCondition: celExpressions: - celMatcher: 'request.path == "/v1/chat/completions"' extensions: - name: extension-chain-1-model-armor googleAPIServiceName: modelarmor.us-central1.rep.googleapis.com failOpen: true supportedEvents: - RequestHeaders - RequestBody - RequestTrailers - ResponseHeaders - ResponseBody - ResponseTrailers timeout: 1s metadata: model_armor_settings: '[ { "model": "MODEL_NAME", "model_response_template_id": "projects/TEMPLATE_PROJECT_ID/locations/LOCATION/templates/RESPONSE_TEMPLATE", "user_prompt_template_id": "projects/TEMPLATE_PROJECT_ID/locations/LOCATION/templates/PROMPT_TEMPLATE" } ]' EOF
  Sostituisci quanto segue:
  - MODEL_NAME: il nome del modello come configurato con la risorsa InferenceModel, ad esempio meta-llama/Llama-3.1-8B-Instruct
  - TEMPLATE_PROJECT_ID: l'ID progetto dei modelli Model Armor
  - LOCATION: la posizione del modello Model Armor, ad esempio us-central1
  - RESPONSE_TEMPLATE: il template di risposta da utilizzare per il modello
  - PROMPT_TEMPLATE: il modello di prompt da utilizzare
  Nel campo metadata, specifica le impostazioni e i modelli di Model Armor da utilizzare durante il controllo dei prompt e delle risposte corrispondenti a modelli specifici.
  
  È possibile specificare un modello predefinito da utilizzare quando una richiesta non corrisponde esattamente a un modello. Per configurare un modello predefinito, specifica MODEL_NAME come default.
  
  Se non vuoi traffico di prompt o risposte dello schermo, crea e includi un modello di filtro vuoto.
  
  La dimensione totale di metadata deve essere inferiore a 1 KiB. Il numero totale di chiavi nei metadati deve essere inferiore a 16. La lunghezza di ogni chiave deve essere inferiore a 64 caratteri. La lunghezza di ogni valore deve essere inferiore a 1024 caratteri. Tutti i valori devono essere stringhe.
  
  Quando una richiesta viene bloccata, Model Armor restituisce un codice di stato 403 Forbidden standard. Puoi ignorare lo stato definendo impostazioni di risposta personalizzate (inclusi un codice di stato e un messaggio personalizzati) nella policy di sicurezza del modello Model Armor. Per i dettagli, vedi TemplateMetadata.
3. Applica la configurazione definita nel file traffic_callout_service.yaml al tuo cluster GKE. Questo comando crea la risorsa GCPTrafficExtension, che collega Inference Gateway al servizio Model Armor.
  kubectl apply -f traffic_callout_service.yaml

Concedi i ruoli richiesti al account di servizio Service Extensions. Utilizza il comando gcloud projects add-iam-policy-binding:

gcloud projects add-iam-policy-binding TEMPLATE_PROJECT_ID \
    --member=serviceAccount:service-LB_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
    --role=roles/container.admin
gcloud projects add-iam-policy-binding TEMPLATE_PROJECT_ID \
    --member=serviceAccount:service-LB_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
    --role=roles/modelarmor.calloutUser
gcloud projects add-iam-policy-binding TEMPLATE_PROJECT_ID \
    --member=serviceAccount:service-LB_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
    --role=roles/serviceusage.serviceUsageConsumer
gcloud projects add-iam-policy-binding TEMPLATE_PROJECT_ID \
    --member=serviceAccount:service-LB_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
    --role=roles/modelarmor.user

Sostituisci quanto segue:

TEMPLATE_PROJECT_ID: l'ID progetto dei modelli Model Armor
LB_PROJECT_NUMBER: il numero di progetto del bilanciatore del carico

Questi valori sono elencati nel riquadro Informazioni progetto della Google Cloud console per il tuo progetto.

Per verificare che l'estensione del traffico funzioni come previsto, esegui lo stesso comando curl:

curl -v http://${IP}/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H 'Authorization: Bearer $(gcloud auth print-access-token)' \
  -d '{"model": "meta-llama/Llama-3.1-8B-Instruct",
       "messages": [
          {
            "role": "user",
            "content": "Can you remember my ITIN: 123-45-6789"
          }
        ],
       "max_tokens": 250,
       "temperature": 0.1}'
  ```

Con l'estensione del servizio configurata, una richiesta con dati sensibili genera un codice di stato HTTP 403 Forbidden, registra un messaggio di errore come configurato nel modello e chiude la connessione.

Quando la richiesta è sicura, genera un codice di stato HTTP 200 OK e restituisce la risposta del LLM all'utente.

Per monitorare il comportamento dell'estensione, utilizza Esplora log. Nel riquadro della query, a seconda della configurazione di Inference Gateway, filtra per il tipo di risorsa del bilanciatore del carico appropriato.

Le voci di log del bilanciatore del carico delle applicazioni contengono informazioni utili per eseguire il debug del traffico HTTP o HTTPS.

Per eseguire un'analisi più dettagliata delle valutazioni di sicurezza, attiva la registrazione degli audit di Model Armor.

Passaggi successivi

Gestire le estensioni

Configurare un'estensione per chiamare un servizio Google Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.