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, consulta Integrazione con i servizi Google.

Configurare 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 di 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 di Common Expression Language (CEL) Il bilanciatore del carico valuta una richiesta rispetto 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 in una catena può avere il proprio set di eventi supportati. Le modifiche apportate da un'estensione al contenuto della richiesta e della risposta sono visibili alle estensioni rimanenti nella catena. Per le estensioni configurate per supportare gli eventi di risposta, la sequenza delle estensioni viene invertita nel percorso di risposta.

L'estensione del traffico si collega a una regola di forwarding del bilanciatore del carico creata utilizzando Inference Gateway. Dopo aver configurato la risorsa, le richieste corrispondenti vengono inviate al servizio Model Armor.

Prima di iniziare

  1. Identifica un progetto adatto in cui hai il ruolo di proprietario o editor del progetto oppure i seguenti ruoli IAM di Compute Engine:

  2. Abilita le API richieste.

    Console

    1. Nella Google Cloud console, vai alla pagina Abilita l'accesso alle API.

      Vai ad Abilita 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 gcloud services enable comando:

    gcloud services enable compute.googleapis.com modelarmor.googleapis.com networkservices.googleapis.com

  3. Crea i modelli Model Armor richiesti.

  4. Configura l'infrastruttura di Google Kubernetes Engine eseguendo il deployment di Inference Gateway. Testalo inviando una richiesta di inferenza.

    Con alcune limitazioni, sono supportati i seguenti endpoint dell'API OpenAI: Assistants, Chat Completions, Completions (legacy), Messages e Threads.

Limitazioni durante la configurazione di un endpoint API OpenAI

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

  • Le risposte dell'API di streaming non sono supportate per nessuna API. Model Armor sanifica le risposte non di streaming e ignora le risposte di streaming.

  • Durante la sanificazione di prompt e risposte, sono supportate solo le seguenti operazioni; qualsiasi altra operazione viene ignorata e può procedere senza sanificazione:

    • 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 Responses: Create, Delete e Get
    • 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 nell'elenco delle scelte.

Configurare l'estensione del traffico

  1. Controlla il comportamento prima della configurazione dell'estensione 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 i dati sensibili sono stati inviati all'LLM.

  2. Per consentire a Model Armor di bloccare i prompt che contengono dati sensibili, configura un'estensione del traffico.

    Console

    1. Nella Google Cloud console, vai alla pagina Service Extensions.

      Vai a Service Extensions

    2. Fai clic su Crea estensione. Si apre una procedura guidata che ti illustra alcuni passaggi iniziali.

    3. Per il prodotto, seleziona Bilanciamento del carico. Poi 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 del traffico e poi 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 Informazioni di base, procedi nel seguente modo:

      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 deve terminare con un trattino.

      2. (Facoltativo) Inserisci una breve descrizione dell'estensione utilizzando un massimo di 1024 caratteri.

    9. (Facoltativo) Nella sezione Etichette, fai clic su Aggiungi etichetta. Poi, nella riga visualizzata, procedi nel seguente modo:

      • In Chiave, inserisci un nome 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 ulteriori informazioni sulle etichette, consulta Creare e aggiornare le etichette per i progetti.

    10. In Regole di forwarding, seleziona una o più regole di forwarding da associare all'estensione. Scegli una regola di forwarding generata nell'ambito del deployment di Inference Gateway. Le regole di forwarding già associate a un'altra estensione non possono essere selezionate e appaiono non disponibili.

    11. In Estensione, per aggiungere un'estensione da eseguire per una richiesta corrispondente, procedi nel seguente modo:

      • Per trovare le richieste per le quali viene eseguita la catena di estensioni, in Condizione di corrispondenza, specifica un'espressione Common Expression Language (CEL) , ad esempio request.path == "/v1/chat/completions".

        Per ulteriori informazioni sulle espressioni CEL, fai clic Ricevi assistenza per la sintassi o consulta il riferimento al linguaggio del matcher CEL.

      • Aggiungi una o più estensioni da eseguire per una richiesta corrispondente.

        Per ogni estensione, in Estensioni, procedi nel seguente modo e poi fai clic su Fine:

      • In Tipo di programmabilità, seleziona Servizi Google e poi seleziona un endpoint del servizio Model Armor, ad esempio modelarmor.us-central1.rep.googleapis.com.

      • In Timeout, specifica un valore compreso tra 10 e 1000 millisecondi dopo il quale il messaggio nel flusso va in timeout. Tieni presente che Model Armor ha una latenza di circa 250 millisecondi.

      • In Eventi, seleziona tutti i tipi di eventi HTTP.

      • In Intestazioni di forwarding, 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 va in timeout o non riesce e vuoi che l'elaborazione della richiesta o della risposta continui, in 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 mantenere Fail open deselezionata è preferibile quando si dà la priorità alla sicurezza o all'integrità. L'attivazione di Fail open, soprattutto 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 i prompt e le risposte corrispondenti a modelli specifici.

        In Chiave, specifica model_armor_settings. In Valore, specifica i modelli come stringa JSON, ad esempio la seguente:

        [{ "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:

        È possibile specificare anche 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 filtrare il traffico di prompt o risposte, 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 sostituire 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, consulta TemplateMetadata.

      Se vuoi specificare più estensioni o catene di estensioni anziché una singola estensione, fai clic sul pulsante Passa alla modalità avanzata alla fine del modulo e specifica le estensioni e le catene richieste. Le estensioni vengono eseguite nella sequenza in cui sono elencate.

      Specifica nomi univoci per ogni estensione e catena di estensioni. I nomi devono essere conformi 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.

    12. 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 forwarding da associare all'estensione. Scegli una regola di forwarding generata nell'ambito del deployment di Inference Gateway.

        Le regole di forwarding già associate a un'altra estensione non possono essere selezionate e appaiono 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 località del modello Model Armor, ad esempio us-central1

      • RESPONSE_TEMPLATE: il modello di risposta da utilizzare per il modello

      • PROMPT_TEMPLATE: il modello di prompt da utilizzare per il modello

      Nel campo metadata, specifica le impostazioni e i modelli Model Armor da utilizzare durante il filtraggio di prompt e risposte corrispondenti a modelli specifici.

      È possibile specificare anche 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 filtrare il traffico di prompt o risposte, 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 sostituire 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, consulta TemplateMetadata.

    2. Importa l'estensione del traffico. Utilizza il gcloud service-extensions lb-traffic-extensions import comando 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 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 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:

      Nel campo metadata, specifica le impostazioni e i modelli Model Armor da utilizzare durante il filtraggio di prompt e risposte corrispondenti a modelli specifici.

      È possibile specificare anche 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 filtrare il traffico di prompt o risposte, 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 sostituire 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, consulta TemplateMetadata.

    3. Applica la configurazione definita nel file traffic_callout_service.yaml al cluster GKE. Questo comando crea la risorsa GCPTrafficExtension, che collega Inference Gateway al servizio Model Armor.

      kubectl apply -f traffic_callout_service.yaml

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

    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 del progetto del bilanciatore del carico

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

  4. 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 LLM all'utente.

Per monitorare il comportamento dell'estensione, utilizza Esplora log. Nel riquadro della query, a seconda della configurazione di Inference Gateway, filtra in base al 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