Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Configura una extensión para llamar a un servicio de Google

Las extensiones de servicio permiten que los balanceadores de cargas de aplicaciones compatibles configuren extensiones con llamadas a los servicios de Google. En esta página, se muestra cómo configurar esas extensiones.

Para obtener una descripción general, consulta Integración con los servicios de Google.

Configura una extensión de tráfico para llamar al servicio de Model Armor

Puedes configurar una extensión de tráfico para llamar a Model Armor y aplicar de manera uniforme las políticas de seguridad en el tráfico de inferencia de IA generativa a los balanceadores de cargas de aplicaciones, incluida la GKE Inference Gateway.

Una extensión de tráfico agrupa los servicios de extensión relacionados en una o más cadenas. Puedes configurar complementos y textos destacados en la misma cadena de extensiones. Cada cadena de extensión selecciona el tráfico en el que se actuará con las condiciones de coincidencia de Common Expression Language (CEL). El balanceador de cargas evalúa una solicitud en función de la condición de coincidencia de cada cadena de forma secuencial. Cuando una solicitud coincide con las condiciones definidas por una cadena, todas las extensiones de la cadena actúan sobre la solicitud. Solo una cadena coincide con una solicitud determinada.

Cada extensión de una cadena puede tener su propio conjunto de eventos admitidos. Las modificaciones que realiza una extensión en el contenido de la solicitud y la respuesta son visibles para las demás extensiones de la cadena. En el caso de las extensiones configuradas para admitir eventos de respuesta, la secuencia de extensiones se invierte en la ruta de respuesta.

La extensión de tráfico se adjunta a una regla de reenvío del balanceador de cargas que se crea con la puerta de enlace de inferencia. Después de configurar el recurso, las solicitudes coincidentes se envían al servicio de Model Armor.

Antes de comenzar

Identifica un proyecto adecuado en el que tengas una función de propietario o de editor del proyecto o las siguientes funciones de IAM de Compute Engine:
- Para crear instancias: Administrador de instancias de Compute (v1) (roles/compute.instanceAdmin.v1)
- Para crear componentes de Cloud Load Balancing: Administrador de red de Compute (roles/compute.networkAdmin)
Habilita las APIs necesarias.
Console
1. En la consola de Google Cloud , ve a la página Habilita el acceso a las APIs.
  
  Ir a Habilita el acceso a las APIs
2. Sigue las instrucciones para habilitar las APIs requeridas, que incluyen la API de Compute Engine, la API de Model Armor y la API de Network Services.
gcloud
Usa el comando gcloud services enable:
gcloud services enable compute.googleapis.com modelarmor.googleapis.com networkservices.googleapis.com
Crea las plantillas de Model Armor necesarias.
Configura tu infraestructura de Google Kubernetes Engine implementando una puerta de enlace de inferencia. Para probarlo, envía una solicitud de inferencia.

Sujetos a algunas limitaciones, se admiten los siguientes extremos de la API de OpenAI: Assistants, Chat Completions, Completions (legacy), Messages y Threads.

Limitaciones al configurar un extremo de API de OpenAI

Cuando configures un extremo de API de OpenAI para tu infraestructura de GKE, ten en cuenta las siguientes limitaciones relacionadas con el saneamiento de instrucciones y respuestas:

Las respuestas de la API de transmisión no se admiten para ninguna API. Model Armor limpia las respuestas sin transmisión y descarta las respuestas de transmisión.
Cuando se sanitizan las instrucciones y las respuestas, solo se admiten las siguientes operaciones. Cualquier otra operación se ignora y se permite que continúe sin sanitización:
- API de Assistants: Create, Delete, List, Modify y Retrieve
- API de Chat Completions: Create, Delete, Get Chat Completion, Get Chat Message, List y Update
- API de Completions (legado): Create
- API de Messages: Create, Delete, List, Modify y Retrieve
- API de Responses: Create, Delete y Get
- API de Threads: Create, Delete, Modify y Retrieve
En el caso de las llamadas a la API que devuelven varias opciones en la respuesta (como POST https://api.openai.com/v1/chat/completions), solo se sanitiza el primer elemento de la lista de opciones.

Configura la extensión de tráfico

Verifica el comportamiento antes de configurar la extensión enviando una solicitud de inferencia al balanceador de cargas y especificando la dirección IP expuesta del balanceador de cargas:

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 solicitud genera un código de estado HTTP 200 OK, aunque se hayan enviado datos sensibles al LLM.

Para que Model Armor bloquee las instrucciones que contienen datos sensibles, configura una extensión de tráfico.
Console
1. En la consola de Google Cloud , ve a la página Extensiones de servicio.
  
  Ir a Extensiones del servicio
2. Haz clic en Crear extensión. Se abrirá un asistente que te guiará por algunos pasos iniciales.
3. En el producto, selecciona Load Balancing. Luego, haz clic en Continuar. Aparecerá una lista de los balanceadores de cargas de aplicaciones admitidos.
4. Selecciona un tipo de balanceador de cargas.
5. Especifica la región como us-central1. Haga clic en Continuar.
6. En el tipo de extensión, selecciona Extensiones de Tráfico y, luego, haz clic en Continuar.
7. Para abrir el formulario Crear extensión, haz clic en Continuar. En el formulario Crear extensión, observa que las selecciones anteriores no se pueden editar.
8. En la sección Básicos, haz lo siguiente:
  
  Especifica un nombre único para la extensión.
  
  El nombre debe comenzar con una letra minúscula seguida por un máximo de 62 letras minúsculas, números o guiones, y no puede terminar con un guion.
  
  Opcional: Ingresa una breve descripción de la extensión con hasta 1,024 caracteres.
9. Opcional: En la sección Etiquetas, haz clic en Agregar etiqueta. Luego, en la fila que aparece, haz lo siguiente:
  
  En Clave, ingresa un nombre de clave.
  
  En Valor, ingresa un valor para la clave.
  
  Para agregar más pares clave-valor, haz clic en Agregar etiqueta. Puedes agregar un máximo de 64 pares clave-valor.
  
  Para obtener más información sobre las etiquetas, consulta Crea y actualiza etiquetas para proyectos.
10. En Reglas de reenvío, selecciona una o más reglas de reenvío para asociarlas con la extensión. Elige una regla de reenvío que se genere como parte de la implementación de Inference Gateway. No se pueden seleccionar las reglas de reenvío que ya están asociadas con otra extensión y aparecen como no disponibles.
11. En el caso de Extension, para agregar una extensión que se ejecutará para una solicitud coincidente, haz lo siguiente:
  
  Para que coincidan las solicitudes en las que se ejecuta la cadena de extensión, en Condición de coincidencia, especifica una expresión de Common Expression Language (CEL), por ejemplo, request.path == "/v1/chat/completions".
  
  Para obtener más información sobre las expresiones de CEL, haz clic en Obtener ayuda con la sintaxis o consulta la referencia del lenguaje del comparador de CEL.
  
  Agrega una o más extensiones para ejecutar una solicitud coincidente.
  
  Para cada extensión, en Extensiones, haz lo siguiente y, luego, haz clic en Listo:
  
  En Tipo de programabilidad, selecciona Servicios de Google y, luego, selecciona un extremo de servicio de Model Armor, por ejemplo, modelarmor.us-central1.rep.googleapis.com.
  
  En Tiempo de espera, especifica un valor entre 10 y 1,000 milisegundos después de que se agote el tiempo de espera de un mensaje en la transmisión. Ten en cuenta que Model Armor tiene una latencia de aproximadamente 250 milisegundos.
  
  En Eventos, selecciona todos los tipos de eventos HTTP.
  
  En Forward headers, haz clic en Add header y, luego, agrega encabezados HTTP para reenviar a la extensión (desde el cliente o el backend). Si no se especifica un encabezado, se envían todos.
  
  Opcional: Si la extensión agota el tiempo de espera o falla, y deseas que continúe el procesamiento de la solicitud o la respuesta, selecciona Habilitado en Fail open. También se ejecutan las extensiones posteriores de la cadena.
  
  De forma predeterminada, la opción Fail open no está seleccionada. En este caso, cuando se produce un error, se detiene el procesamiento de la solicitud o la respuesta. Si no se entregaron los encabezados de respuesta al cliente de nivel inferior, se devuelve un código de estado HTTP 500 genérico al cliente. Si se entregaron los encabezados de respuesta, se restablece el flujo HTTP al cliente.
  
  La opción predeterminada de no seleccionar Fail open es preferible cuando se prioriza la seguridad o la integridad. Habilitar Fail open, en especial para las operaciones no críticas, ayuda a priorizar la disponibilidad.
  
  En Metadatos, haz clic en Agregar metadatos para especificar las plantillas de Model Armor que se usarán para filtrar los prompts y las respuestas correspondientes a modelos específicos.
  
  En Clave, especifica model_armor_settings. En Value, especifica las plantillas como una cadena JSON, como la siguiente:
  
  [{ "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" }]
  
  Reemplaza lo siguiente:
  
  MODEL_NAME: El nombre del modelo configurado con el recurso InferenceModel, por ejemplo, meta-llama/Llama-3.1-8B-Instruct
  
  TEMPLATE_PROJECT_ID: El ID del proyecto de las plantillas de Model Armor
  
  LOCATION: La ubicación de la plantilla de Model Armor, por ejemplo, us-central1
  
  RESPONSE_TEMPLATE: Es la plantilla de respuesta que usará el modelo.
  
  PROMPT_TEMPLATE: Es la plantilla de instrucciones que usará el modelo.
  
  También se puede especificar una plantilla predeterminada para usarla cuando una solicitud no coincide exactamente con un modelo. Para configurar una plantilla predeterminada, especifica MODEL_NAME como default.
  
  Si no deseas filtrar el tráfico de instrucciones o respuestas, crea e incluye una plantilla de filtro vacía.
  
  El tamaño total de metadata debe ser inferior a 1 KiB. La cantidad total de claves en los metadatos debe ser inferior a 20. La longitud de cada clave debe ser inferior a 64 caracteres. La longitud de cada valor debe ser inferior a 1,024 caracteres. Todos los valores deben ser cadenas.
  
  Cuando se bloquea una solicitud, Model Armor devuelve un código de estado 403 Forbidden estándar. Puedes anular el estado definiendo parámetros de configuración de respuesta personalizados (incluidos un código de estado y un mensaje personalizados) en la política de seguridad de la plantilla de Model Armor. Para obtener más detalles, consulta TemplateMetadata.
  
  Si deseas especificar más de una extensión o cadenas de extensiones en lugar de una sola extensión, haz clic en el botón Cambiar al modo avanzado al final del formulario y especifica las extensiones y cadenas requeridas. Las extensiones se ejecutan en la secuencia en la que se enumeran.
  
  Especifica nombres únicos para cada extensión y cadena de extensión. Los nombres deben cumplir con la RFC-1034, usar solo letras minúsculas, números y guiones, y tener una longitud máxima de 63 caracteres. Además, el primer carácter debe ser una letra y el último debe ser una letra o un número.
12. Haz clic en Crear extensión.
gcloud
1. Define la nota en un archivo YAML y asóciala con la regla de reenvío que se genera cuando se implementa Inference Gateway. Usa los valores de muestra proporcionados.
  
  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
  
  Reemplaza lo siguiente:
  
  TEMPLATE_PROJECT_ID: El ID del proyecto de las plantillas de Model Armor
  
  LB_PROJECT_ID: El ID del proyecto de la regla de reenvío del balanceador de cargas
  
  FORWARDING_RULE: Son una o más reglas de reenvío para asociar con la extensión. Elige una regla de reenvío que se genere como parte de la implementación de Inference Gateway.
  
  No se pueden seleccionar las reglas de reenvío que ya están asociadas con otra extensión y aparecen como no disponibles.
  
  MODEL_NAME: El nombre del modelo configurado con el recurso InferenceModel, por ejemplo, meta-llama/Llama-3.1-8B-Instruct
  
  LOCATION: La ubicación de la plantilla de Model Armor, por ejemplo, us-central1
  
  RESPONSE_TEMPLATE: Es la plantilla de respuesta que usará el modelo.
  
  PROMPT_TEMPLATE: Es la plantilla de instrucciones que usará el modelo.
  
  En el campo metadata, especifica la configuración y las plantillas de Model Armor que se usarán durante el análisis de las instrucciones y las respuestas correspondientes a modelos específicos.
  
  También se puede especificar una plantilla predeterminada para usarla cuando una solicitud no coincide exactamente con un modelo. Para configurar una plantilla predeterminada, especifica MODEL_NAME como default.
  
  Si no deseas filtrar el tráfico de instrucciones o respuestas, crea e incluye una plantilla de filtro vacía.
  
  El tamaño total de metadata debe ser inferior a 1 KiB. La cantidad total de claves en los metadatos debe ser inferior a 16. La longitud de cada clave debe ser inferior a 64 caracteres. La longitud de cada valor debe ser inferior a 1,024 caracteres. Todos los valores deben ser cadenas.
  
  Cuando se bloquea una solicitud, Model Armor devuelve un código de estado 403 Forbidden estándar. Puedes anular el estado definiendo parámetros de configuración de respuesta personalizados (incluidos un código de estado y un mensaje personalizados) en la política de seguridad de la plantilla de Model Armor. Para obtener más detalles, consulta TemplateMetadata.
2. Importa la extensión de tráfico. Usa el comando gcloud service-extensions lb-traffic-extensions import con los siguientes valores de muestra.
  
  gcloud service-extensions lb-traffic-extensions import traffic-ext \ --source=traffic_callout_service.yaml \ --location=us-central1
kubectl
1. Si usas una versión de GKE anterior a la v1.32.2-gke.1182001, instala el CRD de la extensión de tráfico:
  
  kubectl apply -f https://raw.githubusercontent.com/GoogleCloudPlatform/gke-gateway-api/refs/heads/main/config/crd/networking.gke.io_gcptrafficextensions.yaml
2. Define la extensión en un archivo YAML. Este recurso personalizado vincula tu Inference Gateway al servicio de Model Armor. Usa los valores de muestra proporcionados.
  
  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
  
  Reemplaza lo siguiente:
  
  MODEL_NAME: El nombre del modelo configurado con el recurso InferenceModel, por ejemplo, meta-llama/Llama-3.1-8B-Instruct
  
  TEMPLATE_PROJECT_ID: El ID del proyecto de las plantillas de Model Armor
  
  LOCATION: La ubicación de la plantilla de Model Armor, por ejemplo, us-central1
  
  RESPONSE_TEMPLATE: Es la plantilla de respuesta que usará el modelo.
  
  PROMPT_TEMPLATE: Es la plantilla de instrucciones que usará el modelo.
  
  En el campo metadata, especifica la configuración y las plantillas de Model Armor que se usarán durante el análisis de las instrucciones y las respuestas correspondientes a modelos específicos.
  
  También se puede especificar una plantilla predeterminada para usarla cuando una solicitud no coincide exactamente con un modelo. Para configurar una plantilla predeterminada, especifica MODEL_NAME como default.
  
  Si no deseas filtrar el tráfico de instrucciones o respuestas, crea e incluye una plantilla de filtro vacía.
  
  El tamaño total de metadata debe ser inferior a 1 KiB. La cantidad total de claves en los metadatos debe ser inferior a 16. La longitud de cada clave debe ser inferior a 64 caracteres. La longitud de cada valor debe ser inferior a 1,024 caracteres. Todos los valores deben ser cadenas.
  
  Cuando se bloquea una solicitud, Model Armor devuelve un código de estado 403 Forbidden estándar. Puedes anular el estado definiendo parámetros de configuración de respuesta personalizados (incluidos un código de estado y un mensaje personalizados) en la política de seguridad de la plantilla de Model Armor. Para obtener más detalles, consulta TemplateMetadata.
3. Aplica la configuración definida en el archivo traffic_callout_service.yaml a tu clúster de GKE. Este comando crea el recurso GCPTrafficExtension, que vincula tu Inference Gateway al servicio de Model Armor.
  
  kubectl apply -f traffic_callout_service.yaml

Otorga los roles necesarios a la cuenta de servicio de Service Extensions. Usa el comando gcloud projects add-iam-policy-binding:

gcloud projects add-iam-policy-binding LB_PROJECT_NUMBER \
    --member=serviceAccount:service-LB_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
    --role=roles/container.admin
gcloud projects add-iam-policy-binding LB_PROJECT_NUMBER \
    --member=serviceAccount:service-LB_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
    --role=roles/modelarmor.calloutUser
gcloud projects add-iam-policy-binding LB_PROJECT_NUMBER \
    --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

Reemplaza lo siguiente:

TEMPLATE_PROJECT_ID: ID del proyecto de las plantillas de Model Armor
LB_PROJECT_NUMBER: Es el número del proyecto del balanceador de cargas.

Estos valores se enumeran en el panel Información del proyecto en la consola deGoogle Cloud para tu proyecto.

Para verificar que la extensión de tráfico funcione según lo esperado, ejecuta el mismo 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 la extensión de servicio configurada, una solicitud con datos sensibles genera un código de estado HTTP 403 Forbidden, registra un mensaje de error según se configuró en la plantilla y cierra la conexión.

Cuando la solicitud es segura, genera un código de estado HTTP 200 OK y devuelve la respuesta del LLM al usuario.

Para supervisar el comportamiento de la extensión, usa el Explorador de registros. En el panel de consultas, según la configuración de tu Inference Gateway, filtra por el tipo de recurso del balanceador de cargas adecuado.

Las entradas de registro del balanceador de cargas de aplicaciones contienen información que te ayuda a depurar tu tráfico HTTP o HTTPS.

Para realizar un análisis más detallado de las evaluaciones de seguridad, habilita el registro de auditoría de Model Armor.

¿Qué sigue?

Administrar extensiones

Configura una extensión para llamar a un servicio de Google Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.