Configura políticas de Apigee con el procesador de extensiones

Esta página se aplica a Apigee y Apigee Hybrid.

Consulta la documentación de Apigee Edge.

El procesador de extensiones de Apigee te permite aplicar las capacidades de la puerta de enlace de IA de Apigee al tráfico que no fluye a través de un proxy de Apigee. Por ejemplo, un servicio que se ejecuta en Google Kubernetes Engine, una API administrada por otra puerta de enlace o un servidor de MCP para un agente de IA. Dado que la ruta de tráfico difiere de la de un proxy de API estándar, parte de la configuración de políticas es específica del procesador de extensiones. En esta página, se describen esas consideraciones y se proporcionan ejemplos de configuraciones. Cada sección de la política se vincula al instructivo completo de esa política.

Las políticas de esta página se aplican de la misma manera dondequiera que se adjunte el procesador de extensiones:

Consideraciones clave

Se aplican las siguientes consideraciones cuando adjuntas cualquier política a un proxy del procesador de extensiones. Para saber dónde adjuntarlas, consulta Usa políticas con el procesador de extensiones en la guía de inicio rápido.

Haz coincidir los ejemplos con la API de tu modelo

En los ejemplos de esta página, se usa la forma de solicitud y respuesta de Gemini. Otros proveedores de modelos funcionan de la misma manera: UserPromptSource, LLMTokenUsageSource y LLMModelSource son plantillas de mensajes, por lo que debes establecerlas en la ubicación equivalente en la carga útil de esa API. Las políticas en sí no se modificaron.

Determina el alcance del tráfico que procesas

Con un proxy de API estándar, asignas una ruta base y los clientes llaman a esa URL específica, por lo que el proxy solo recibe el tráfico previsto para él. El procesador de extensiones no tiene una ruta de acceso base, por lo que debes definir el alcance de su tráfico en dos lugares: en la extensión, que decide qué llega a Apigee, y en el proxy, que decide qué se ejecuta en el tráfico que llega. Usa ambas opciones.

Primero, filtra en la extensión para que el tráfico que no deseas controlar nunca se envíe a Apigee:

  • En una extensión de tráfico, establece una condición de coincidencia de CEL en la cadena de extensión, por ejemplo, matchCondition.celExpression: 'request.host == "example.com"'.
  • En una extensión de autorización, haz coincidir los hosts y los prefijos de ruta de acceso en httpRules.to.operations en la política de autorización.

Luego, define el alcance de las políticas individuales dentro del proxy. Un solo proxy del procesador de extensiones recibe todo lo que selecciona la extensión, y eso puede seguir siendo una combinación: las llamadas al modelo de un agente de IA, las llamadas de sesión y de estado, y las llamadas de telemetría pueden compartir un host. Una política que inspecciona la carga útil de un modelo falla en una llamada que no incluye una carga útil, y una política fallida bloquea la solicitud. Adjunta cada política con una condición que la limite al tráfico previsto:

<!-- Run only on the model (generateContent) call -->
<Step>
  <Name>My-Policy</Name>
  <Condition>(request.uri Like "*generateContent*")</Condition>
</Step>

<!-- Or scope by backend host -->
<Step>
  <Name>My-Policy</Name>
  <Condition>(request.header.host = "backend.example.com")</Condition>
</Step>

Usa un proxy sin destino

Los proxies del procesador de extensiones procesan el tráfico interceptado y no tienen un extremo de destino. Implementarlos como proxies extensibles Todos los proxies en un entorno de procesador de extensiones deben ser del mismo tipo.

Leer el cuerpo de la llamada interceptada

Las políticas que inspeccionan la carga útil operan en el mensaje tal como aparece en el cable. En el caso de una llamada al modelo, se trata de la solicitud y la respuesta del modelo. Por ejemplo, la instrucción del usuario se encuentra en $.contents[-1].parts[-1].text y la respuesta del modelo en $.candidates[-1].content.parts[-1].text.

Otorga acceso a una cuenta de servicio para políticas que llaman a servicios de Google

Las políticas que llaman a un servicio de Google (por ejemplo, Model Armor o las búsquedas de incorporaciones y de índices que usa el almacenamiento en caché semántico) requieren una cuenta de servicio de implementación. Implementa el proxy con el parámetro serviceAccount.

Seguridad de la IA con Model Armor

Adjunta las políticas SanitizeUserPrompt y SanitizeModelResponse, con el alcance establecido para la llamada al modelo. Para configurar plantillas, consulta Comienza a usar Model Armor.

<SanitizeUserPrompt name="SUP-sanitize" continueOnError="false">
  <ModelArmor>
    <TemplateName>projects/PROJECT/locations/LOCATION/templates/TEMPLATE</TemplateName>
  </ModelArmor>
  <UserPromptSource>{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}</UserPromptSource>
</SanitizeUserPrompt>

Adjunta SUP-sanitize en el flujo de solicitud con la condición (request.uri Like "*generateContent*"). Cuando la instrucción coincide con la plantilla de Model Armor, la política rechaza la solicitud, por lo que la instrucción nunca llega al modelo.

Almacenamiento en caché semántico

Adjunta la política SemanticCacheLookup en el flujo de solicitud y la política SemanticCachePopulate en el flujo de respuesta, ambas con alcance para la llamada al modelo. Para configurar el índice y las incorporaciones, consulta Comienza a usar el almacenamiento en caché semántico. Cuando una solicitud coincide con una instrucción almacenada en caché, la respuesta se entrega desde la caché sin llamar al modelo.

Límites de tokens para las llamadas al modelo

Dos políticas limitan el uso de tokens de modelos de lenguaje grandes (LLM) en la llamada al modelo. Ambos se deben incluir en el alcance de la llamada al modelo con la condición (request.uri Like "*generateContent*"). Para obtener información sobre la configuración, consulta Comienza a usar las políticas de tokens de LLM.

Limita los tokens de instrucciones

La política PromptTokenLimit limita los tokens según la instrucción del usuario, lo que constituye una protección contra aumentos repentinos para las instrucciones. Se adjunta en el flujo de solicitudes, lee la instrucción de la solicitud interceptada y rechaza la llamada cuando se supera la tasa, por lo que una instrucción demasiado grande nunca llega al modelo. En el siguiente ejemplo, se limitan las instrucciones a 1,000 tokens por minuto:

<PromptTokenLimit continueOnError="false" enabled="true" name="PTL-limit-prompt">
  <Rate>1000pm</Rate>
  <UserPromptSource>{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}</UserPromptSource>
</PromptTokenLimit>

Limita el consumo de tokens de respuesta

La política LLMTokenQuota aplica una cuota de consumo de tokens durante un intervalo, y cuenta los tokens que se devuelven en la respuesta del modelo. Adjunta una instancia de EnforceOnly en el flujo de solicitudes para rechazar llamadas una vez que se exceda la cuota y una instancia de CountOnly en el flujo de respuestas para contar los tokens usados, que se leen desde $.usageMetadata.candidatesTokenCount. Asigna a ambas instancias el mismo SharedName para que actualicen un solo contador. Esta política requiere un proxy extensible. El siguiente par aplica 15,000 tokens cada 30 minutos:

<!-- Request flow: reject when the token quota is exceeded -->
<LLMTokenQuota name="LTQ-enforce" type="rollingwindow">
  <SharedName>llm-token-counter</SharedName>
  <EnforceOnly>true</EnforceOnly>
  <Allow count="15000"/>
  <Interval>30</Interval>
  <TimeUnit>minute</TimeUnit>
  <Distributed>true</Distributed>
</LLMTokenQuota>

<!-- Response flow: count the tokens used in the model response -->
<LLMTokenQuota name="LTQ-count" type="rollingwindow">
  <SharedName>llm-token-counter</SharedName>
  <CountOnly>true</CountOnly>
  <Allow count="15000"/>
  <Interval>30</Interval>
  <TimeUnit>minute</TimeUnit>
  <Distributed>true</Distributed>
  <LLMTokenUsageSource>{jsonPath('$.usageMetadata.candidatesTokenCount',response.content,true)}</LLMTokenUsageSource>
</LLMTokenQuota>

Administración del tráfico: cuota, autorización y protección contra aumentos repentinos

Estas políticas se aplican al tráfico que pasa por el procesador de extensiones hacia cualquier backend, incluidos los backends que no están alojados en Apigee, como una API alojada en GKE o un servidor de herramientas o servidor de MCP al que llama un agente de IA. Define el alcance de cada política para el backend que deseas proteger:

<Step><Name>Verify-API-Key</Name><Condition>(request.header.host = "backend.example.com")</Condition></Step>
<Step><Name>Quota-Limit</Name><Condition>(request.header.host = "backend.example.com")</Condition></Step>
<Step><Name>Spike-Arrest</Name><Condition>(request.header.host = "backend.example.com")</Condition></Step>
  • Autorización: Usa la política VerifyAPIKey o OAuthV2. Las llamadas no autorizadas se rechazan antes de llegar al backend.
  • Quota: Usa la política de Quota para aplicar un límite de llamadas preciso. Configura la política como distribuida y síncrona para que el límite se aplique como un solo recuento compartido en todo el tiempo de ejecución.
  • Spike arrest: Usa la política SpikeArrest para suavizar los aumentos repentinos de tráfico. La protección contra aumentos repentinos se aplica por procesador de mensajes y no garantiza una frecuencia global exacta. Cuando necesites un límite preciso, usa la política de cuota.

Transforma mensajes y extrae variables

Usa la política AssignMessage para agregar, cambiar o quitar partes de un mensaje (encabezados, parámetros de consulta o la carga útil) y la política ExtractVariables para leer valores de un mensaje en variables que las políticas posteriores pueden usar. Con el procesador de extensiones, ambas políticas funcionan en el flujo de solicitud, operando en la solicitud interceptada, y en el flujo de respuesta, operando en la respuesta del backend. Al igual que con cualquier política de procesadores de extensiones, define el alcance de cada adjunto con una condición para que se ejecute solo en el tráfico previsto.

En el siguiente ejemplo, se usa ExtractVariables para leer un campo del cuerpo de la solicitud y, en el flujo de respuesta, para leer un campo del cuerpo de la respuesta:

<!-- Request flow: read a field from the intercepted request -->
<ExtractVariables name="EV-from-request">
  <Source>request</Source>
  <JSONPayload>
    <Variable name="user.prompt">
      <JSONPath>$.contents[-1].parts[-1].text</JSONPath>
    </Variable>
  </JSONPayload>
</ExtractVariables>

<!-- Response flow: read a field from the backend response -->
<ExtractVariables name="EV-from-response">
  <Source>response</Source>
  <JSONPayload>
    <Variable name="model.answer">
      <JSONPath>$.candidates[-1].content.parts[-1].text</JSONPath>
    </Variable>
  </JSONPayload>
</ExtractVariables>

En el siguiente ejemplo, se usa AssignMessage para establecer un encabezado en la solicitud antes de que llegue al backend y en la respuesta antes de que vuelva a la persona que llama:

<!-- Request flow: add a header to the intercepted request -->
<AssignMessage name="AM-set-request-header">
  <Set>
    <Headers>
      <Header name="X-Apigee-Processed">true</Header>
    </Headers>
  </Set>
  <AssignTo createNew="false" type="request"/>
</AssignMessage>

<!-- Response flow: add a header to the backend response -->
<AssignMessage name="AM-set-response-header">
  <Set>
    <Headers>
      <Header name="X-Apigee-Cache">miss</Header>
    </Headers>
  </Set>
  <AssignTo createNew="false" type="response"/>
</AssignMessage>

¿Qué sigue?