Esta página se ha traducido con Cloud Translation API.

Política SanitizeUserPrompt

Esta página se aplica a Apigee, pero no a Apigee Hybrid.

Consulta la documentación de Apigee Edge.

Información general

La política SanitizeUserPrompt protege las aplicaciones de IA frente al contenido dañino saneando las peticiones de los usuarios enviadas a modelos de IA generativa. La política usa Model Armor para evaluar las peticiones de los usuarios en busca de contenido dañino, lo que permite proteger de forma nativa las cargas de trabajo de IA que usan Apigee. Model Armor es un Google Cloud servicio que ofrece medidas de seguridad de la IA para mitigar los riesgos asociados a los modelos de lenguaje extensos (LLMs).

Esta política funciona junto con la política SanitizeModelResponse.

Esta política es una política extensible y su uso puede tener implicaciones en cuanto a costes o utilización, en función de tu licencia de Apigee. Para obtener información sobre los tipos de políticas y las implicaciones de uso, consulta Tipos de políticas.

Antes de empezar

Antes de usar la política SanitizeUserPrompt, completa las siguientes tareas:

Crea una plantilla de Model Armor. Completa este paso antes de crear una política SanitizeUserPrompt.
Define el endpoint de la API del servicio Model Armor.
Crea una política SanitizeModelResponse. Completa esta tarea antes de implementar la política SanitizeUserPrompt.

Roles obligatorios

Para obtener los permisos que necesitas para aplicar y usar la política SanitizeUserPrompt, pide a tu administrador que te conceda los siguientes roles de gestión de identidades y accesos en la cuenta de servicio que usas para implementar proxies de Apigee:

Usuario de Model Armor (roles/modelarmor.user)
Lector de Model Armor (roles/modelarmor.viewer)

Para obtener más información sobre cómo conceder roles, consulta el artículo Gestionar el acceso a proyectos, carpetas y organizaciones.

También puedes conseguir los permisos necesarios a través de roles personalizados u otros roles predefinidos.

Habilitar APIs

Enable the Model Armor API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

Elemento `<SanitizeUserPrompt>`

Define una política SanitizeUserPrompt.

Valor predeterminado	Consulta la pestaña Política predeterminada que aparece más abajo.
¿Es obligatorio?	Obligatorio
Tipo	Objeto complejo
Elemento principal	N/A
Elementos secundarios	`<DisplayName>` `<IgnoreUnresolvedVariables>` `<TemplateName>` `<UserPromptSource>`

El elemento <SanitizeUserPrompt> utiliza la siguiente sintaxis:

Sintaxis

<SanitizeUserPrompt async="false" continueOnError="false" enabled="true" name="sanitize-text">
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <DisplayName>Sanitize-Text-sample</DisplayName>
  <ModelArmor>
    <TemplateName>projects/{project}/locations/{location}/templates/{template-name}</TemplateName>
  </ModelArmor>
  <UserPromptSource>{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}</UserPromptSource>
</SanitizeUserPrompt>

Política predeterminada

En el siguiente ejemplo se muestran los ajustes predeterminados al añadir una política SanitizeUserPrompt al flujo de solicitudes en la interfaz de usuario de Apigee:

<SanitizeUserPrompt async="false" continueOnError="false" enabled="true" name="sanitize-text">
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <DisplayName>Sanitize-Text-sample</DisplayName>
  <ModelArmor>
    <TemplateName>projects/{project}/locations/{location}/templates/{template-name}</TemplateName>
  </ModelArmor>
  <UserPromptSource>{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}</UserPromptSource>
</SanitizeUserPrompt>

Cuando insertas una política SanitizeUserPrompt mediante la interfaz de usuario de Apigee, la plantilla contiene stubs para todas las operaciones posibles. Consulta la información sobre los elementos obligatorios más abajo.

Este elemento tiene los siguientes atributos, que son comunes a todas las políticas:

Atributo	Predeterminado	¿Es obligatorio?	Descripción
`name`	N/A	Obligatorio	El nombre interno de la política. El valor del atributo `name` puede contener letras, números, espacios, guiones, guiones bajos y puntos. Este valor no puede superar los 255 caracteres. Opcionalmente, usa el elemento `<DisplayName>` para etiquetar la política en el editor de proxy de la interfaz de gestión con un nombre diferente en lenguaje natural.
`continueOnError`	falso	Opcional	Asigna el valor `false` para devolver un error cuando falle una política. Este es el comportamiento esperado de la mayoría de las políticas. Asigna el valor `true` para que la ejecución del flujo continúe incluso después de que falle una política. Consulta también: Las reglas de errores solo se activan cuando hay un error (sobre continueOnError) Gestionar fallos en el flujo actual
`enabled`	true	Opcional	Asigna el valor `true` para aplicar la política. Selecciona `false` para desactivar la política. La política no se aplicará aunque siga adjunta a un flujo.
`async`	falso	Obsoleto	Este atributo está obsoleto.

En la siguiente tabla se ofrece una descripción general de los elementos secundarios de <SanitizeUserPrompt>:

Elemento secundario	¿Es obligatorio?	Descripción
`<DisplayName>`	Opcional	El nombre de la política.
`<IgnoreUnresolvedVariables>`	Opcional	Especifica si el procesamiento se detiene si no se resuelve la variable utilizada para el nombre de la plantilla o la carga útil de Model Armor.
`<ModelArmor>`	Obligatorio	Contiene la información necesaria para especificar la plantilla de Model Armor.
`<UserPromptSource>`	Opcional	Ubicación de la carga útil del texto de la petición del usuario que se va a extraer. Solo se admiten valores de texto de cadena. Este campo admite la sintaxis de las plantillas de mensajes de Apigee, incluido el uso de variables o funciones de ruta JSON. Por ejemplo: {jsonpath('$.input.prompt.text',request.content,false)}

Ejemplo

En esta sección se muestra un ejemplo en el que se usa <SanitizeUserPrompt>.

En este ejemplo se usan todos los valores predeterminados para la detección de modelos y la extracción de peticiones:

<SanitizeUserPrompt async="false" continueOnError="false" enabled="true" name="sanitize-text">
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <DisplayName>Sanitize-Text-sample</DisplayName>
  <ModelArmor>
    <TemplateName>projects/{project}/locations/{location}/templates/{template-name}</TemplateName>
  </ModelArmor>
</SanitizeUserPrompt>

Referencia de elemento secundario

En esta sección se describen los elementos secundarios de <SanitizeUserPrompt>.

`<DisplayName>`

Se usa junto con el atributo name para etiquetar la política en el editor de proxy de la interfaz de usuario de gestión con un nombre diferente que suene más natural.

El elemento <DisplayName> es común a todas las políticas.

Valor predeterminado	N/A
¿Es obligatorio?	Opcional. Si omite `<DisplayName>`, se usará el valor del atributo `name` de la política.
Tipo	Cadena
Elemento principal	<`PolicyElement`>
Elementos secundarios	Ninguno

El elemento <DisplayName> utiliza la siguiente sintaxis:

Sintaxis

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

Ejemplo

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

El elemento <DisplayName> no tiene atributos ni elementos secundarios.

<IgnoreUnresolvedVariables>

Determina si el procesamiento se detiene cuando no se resuelve una variable. Asigna el valor true para ignorar las variables sin resolver y continuar con el procesamiento.

Valor predeterminado	Falso
¿Es obligatorio?	Opcional
Tipo	Booleano
Elemento principal	`<SanitizeUserPrompt>`
Elementos secundarios	Ninguno

`<ModelArmor>`

Contiene la información necesaria para especificar la plantilla de Model Armor.

Valor predeterminado	N/A
¿Es obligatorio?	Obligatorio
Tipo	Cadena
Elemento principal
Elementos secundarios	`<TemplateName>`

El elemento <ModelArmor> utiliza la siguiente sintaxis:

Sintaxis

<ModelArmor>
  <TemplateName>projects/{project}/locations/{location}/templates/{template-name}</TemplateName>
</ModelArmor>

Ejemplo

En este ejemplo se usan variables de flujo de Apigee para rellenar la información necesaria.

<ModelArmor>
  <TemplateName>projects/{organization.name}/locations/{system.region.name}/templates/{id}</TemplateName>
</ModelArmor>

En la siguiente tabla se ofrece una descripción general de los elementos secundarios de <ModelArmor>.

Elemento secundario ¿Es obligatorio? Descripción

Elemento secundario	¿Es obligatorio?	Descripción
`<TemplateName>`	Obligatorio	Cadena La plantilla de Model Armor que se ha usado para sanear la petición del usuario. Este valor se puede crear mediante plantillas con las siguientes variables de flujo de Apigee: projects/{organization.name}/locations/{system.region.name}/templates/{id}

<TemplateName>

Obligatorio

Cadena

La plantilla de Model Armor que se ha usado para sanear la petición del usuario.

Este valor se puede crear mediante plantillas con las siguientes variables de flujo de Apigee:

projects/{organization.name}/locations/{system.region.name}/templates/{id}

`<UserPromptSource>`

Ubicación de la carga útil del texto de la petición del usuario que se va a extraer. Este campo admite la sintaxis de la plantilla de mensaje de Apigee, incluido el uso de variables o funciones de ruta JSON. Por ejemplo:

{jsonpath('$.input.prompt.text',request.content,false)}

Valor predeterminado	{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}
¿Es obligatorio?	Opcional
Tipo	Cadena
Elemento principal	`<SanitizeUserPrompt>`
Elementos secundarios	Ninguno

Variables de flujo

Las variables de flujo configuran el comportamiento dinámico del tiempo de ejecución de las políticas y los flujos en función de los encabezados HTTP, el contenido de los mensajes o el contexto disponible en el flujo. Para obtener más información sobre las variables de flujo, consulta la referencia de variables de flujo.

Esta política proporciona el siguiente conjunto de variables de flujo de solo lectura durante la ejecución. Puede usar estas variables de flujo con la política DataCapture para crear informes analíticos personalizados. Para obtener más información, consulta el artículo Recoger datos de clientes con la política DataCapture.

Nombre de variable	Descripción
`SanitizeUserPrompt.POLICY_NAME.templateUsed`	Especifica qué plantilla de Model Armor se usa. Por ejemplo: `projects/myproject/locations/us-west1/templates/mytemplate`
`SanitizeUserPrompt.POLICY_NAME.userPrompt`	Especifica el contenido de la petición que se usa para llamar a Model Armor y sanear el contenido.
`SanitizeUserPrompt.POLICY_NAME.modelResponse`	Especifica el contenido de la respuesta del LLM que se usa en la llamada a Model Armor para desinfectar el contenido.
`SanitizeUserPrompt.POLICY_NAME.responseFromModelArmor`	Especifica la respuesta JSON de Model Armor.
`SanitizeUserPrompt.POLICY_NAME.filterMatchState`	Especifica si el filtro ha coincidido. Los valores válidos son `MATCH_FOUND` y `NO_MATCH_FOUND`.
`SanitizeUserPrompt.POLICY_NAME.invocationResult`	Campo que indica el resultado de la invocación, independientemente del estado de la coincidencia. Puede tener las siguientes características: SUCCESS: All filters executed successfully. PARCIAL: se han omitido algunos filtros o no se han podido ejecutar. ERROR: Se han omitido todos los filtros o no se han podido ejecutar.
`SanitizeUserPrompt.POLICY_NAME.raiFilterResult.executionState`	Resultado de la ejecución del filtro Rai. Los valores válidos son `EXECUTION_SUCCESS` y `EXECUTION_SKIPPED`.
`SanitizeUserPrompt.POLICY_NAME.raiFilterResult.matchState`	Estado de la coincidencia del filtro de RAI. Los valores válidos son `MATCH_FOUND` y `NO_MATCH_FOUND`.
`SanitizeUserPrompt.POLICY_NAME.sdpFilterResult.inspectResult.executionState`	Estado de ejecución del resultado de la inspección del filtro Sdp. Los valores válidos son `EXECUTION_SUCCESS` y `EXECUTION_SKIPPED`.
`SanitizeUserPrompt.POLICY_NAME.sdpFilterResult.inspectResult.matchState`	Estado de coincidencia del resultado de la inspección del filtro Sdp. Los valores válidos son `MATCH_FOUND` y `NO_MATCH_FOUND`.
`SanitizeUserPrompt.POLICY_NAME.sdpFilterResult.deidentifyResult.executionState`	Filtro de SDP del estado de ejecución del resultado de la identificación. Los valores válidos son `EXECUTION_SUCCESS` y `EXECUTION_SKIPPED`.
`SanitizeUserPrompt.POLICY_NAME.sdpFilterResult.deidentifyResult.matchState`	Filtro de SDP del estado de coincidencia del resultado de la identificación. Los valores válidos son `MATCH_FOUND` y `NO_MATCH_FOUND`.
`SanitizeUserPrompt.POLICY_NAME.piAndJailbreakFilterResult.executionState`	Estado de ejecución de los resultados de los filtros de inyección de peticiones y Jailbreak. Los valores válidos son `EXECUTION_SUCCESS` y `EXECUTION_SKIPPED`.
`SanitizeUserPrompt.POLICY_NAME.piAndJailbreakFilterResult.matchState`	El estado de coincidencia de los resultados de los filtros de inyección de peticiones y Jailbreak. Los valores válidos son `MATCH_FOUND` y `NO_MATCH_FOUND`.
`SanitizeUserPrompt.POLICY_NAME.csamFilterFilterResult.executionState`	Estado de ejecución del filtro de material de abuso sexual infantil. Los valores válidos son `EXECUTION_SUCCESS` y `EXECUTION_SKIPPED`.
`SanitizeUserPrompt.POLICY_NAME.csamFilterFilterResult.matchState`	Estado de la coincidencia del filtro de material de abuso sexual infantil. Los valores válidos son `MATCH_FOUND` y `NO_MATCH_FOUND`.
`SanitizeUserPrompt.POLICY_NAME.maliciousUriFilterResult.executionState`	Estado de ejecución del filtro de URIs maliciosos. Los valores válidos son `EXECUTION_SUCCESS` y `EXECUTION_SKIPPED`.
`SanitizeUserPrompt.POLICY_NAME.maliciousUriFilterResult.matchState`	Estado de coincidencia del filtro de URIs maliciosos. Los valores válidos son `MATCH_FOUND` y `NO_MATCH_FOUND`.
`SanitizeUserPrompt.POLICY_NAME.sanitizationMetadata.errorCode`	Código de error personalizado sustituido si está presente en la respuesta de Model Armor.
`SanitizeUserPrompt.POLICY_NAME.sanitizationMetadata.errorMessage`	Código de error personalizado sustituido si está presente en la respuesta de Model Armor.
`SanitizeUserPrompt.POLICY_NAME.csamFilterMatched/code>`	Valor booleano que indica si se ha encontrado una coincidencia con el filtro de material de abuso sexual infantil.
`SanitizeUserPrompt.POLICY_NAME.maliciousURIs`	Lista añadida de URIs maliciosos detectados por el filtro de URIs maliciosos.
`SanitizeUserPrompt.POLICY_NAME.maliciousURIsDetected`	Valor booleano que indica si se ha encontrado una coincidencia con el filtro de URIs maliciosos.
`SanitizeUserPrompt.POLICY_NAME.matchesFound`	Valor booleano que indica si se ha encontrado alguna coincidencia con los filtros.
`SanitizeUserPrompt.POLICY_NAME.promptInjectionDetected`	Valor booleano que indica si se ha encontrado una coincidencia con el filtro de inyección de peticiones.
`SanitizeUserPrompt.POLICY_NAME.promptInjectionConfidence`	Nivel de confianza de la detección de inyecciones de peticiones.
`SanitizeUserPrompt.POLICY_NAME.raiMatchesFound`	Valor booleano que indica si el filtro de RAI ha coincidido.
`SanitizeUserPrompt.POLICY_NAME.requestSentToModelArmor`	Valor booleano que indica si se ha enviado una solicitud a Model Armor.
`SanitizeUserPrompt.POLICY_NAME.sanitizeOperation`	Especifica la operación que realiza la política. Los valores válidos son `SANITIZE_USER_PROMPT` y `SANITIZE_MODEL_RESPONSE`.

Referencia de errores

En esta sección se describen los códigos de error y los mensajes de error que devuelve Apigee, así como las variables de error que define Apigee para la política SanitizeUserPrompt. Es importante que conozcas esta información si vas a desarrollar reglas de errores para gestionarlos. Para obtener más información, consulta Qué debes saber sobre los errores de políticas y Gestionar errores.

Errores de tiempo de ejecución

Estos errores pueden producirse cuando se ejecuta la política.

Código de fallo	Estado de HTTP	Causa
`steps.sanitize.user.prompt.response.FilterMatched`	`400`	Este error se produce si la petición del usuario no supera la comprobación de la plantilla Model Armor.
`steps.sanitize.user.prompt.SanitizationResponseParsingFailed`	`500`	Este error se produce si no se puede analizar la respuesta de Model Armor.
`steps.sanitize.user.prompt.FailedToExtractUserPrompt`	`500`	Este error se produce si no se ha podido extraer automáticamente la petición del usuario para el valor predeterminado.
`steps.sanitize.user.prompt.InternalError`	`500`	Este error se produce si hay un error interno del servidor.
`steps.sanitize.modelarmor.ModelArmorTemplateNameExtractionFailed`	`500`	Este error se produce si no se puede resolver el nombre de la plantilla.
`steps.sanitize.modelarmor.AuthenticationFailure`	`500`	Este error se produce si la cuenta de servicio no tiene permiso para llamar a la API Model Armor.
`steps.sanitize.modelarmor.ModelArmorAPIFailed`	`500`	Este error se produce si la API Model Armor genera un error.
`steps.sanitize.modelarmor.ModelArmorCalloutError`	`500`	Este error se produce si falla la llamada a la API Model Armor.
`steps.sanitize.modelarmor.ServiceUnavailable`	`500`	Este error se produce si el servicio Model Armor no está disponible.

Errores de implementación

Estos errores pueden producirse al implementar un proxy que contenga esta política.

Nombre del error	Causa
`The ModelArmor/TemplateName element is required.`	Se produce si el elemento <TemplateName> de <ModelArmor> no está presente.
`The TemplateName element value is required.`	Se produce si el valor de <TemplateName> está vacío.

Variables de error

Esta política define estas variables cuando se produce un error durante el tiempo de ejecución. Para obtener más información, consulta Qué debes saber sobre los errores de las políticas.

Variables	Dónde	Ejemplo
`fault.name="FAULT_NAME"`	`FAULT_NAME` es el nombre del fallo, tal como se indica en la tabla Errores de tiempo de ejecución de arriba. El nombre del error es la última parte del código de error.	`fault.name Matches "UnresolvedVariable"`
`SanitizeUserPrompt.POLICY_NAME.failed`	`POLICY_NAME` es el nombre de la política especificado por el usuario que ha provocado el error.	`SanitizeUserPrompt.sanitize-prompt.failed = true`

Ejemplo de respuesta de error

Nota: Para gestionar los errores, la práctica recomendada es interceptar la parte errorcode de la respuesta de error. No te fíes del texto de la faultstring, ya que podría cambiar.

{
  "fault": {
    "faultstring": "SanitizeUserPrompt[sanitize-prompt]: unable to resolve variable [variable_name]",
    "detail": {
      "errorcode": "steps.sanitizeuserprompt.UnresolvedVariable"
    }
  }
}

Regla de fallo de ejemplo

<FaultRule name="SanitizeUserPrompt Faults">
    <Step>
        <Name>SUP-CustomSetVariableErrorResponse</Name>
        <Condition>(fault.name = "SetVariableFailed")</Condition>
    </Step>
    <Condition>(sanitizeuserprompt.failed = true)</Condition>
</FaultRule>

Código y mensajes de error de la plantilla de Model Armor

La plantilla Model Armor permite anular los códigos de error y los mensajes de error que se producen en las solicitudes a la API de la política SanitizeUserPrompt. Si el usuario define las anulaciones, los códigos y mensajes de error de Model Armor se incluirán en las variables de flujo.

Por ejemplo, una respuesta con códigos y mensajes de error de Model Armor podría tener el siguiente aspecto:

{
  "sanitizationResult": {
    "filterMatchState": "MATCH_FOUND",
    "filterResults": {...},
    "sanitizationMetadata": {
      "errorCode": "890",
      "errorMessage": "get out"
      },
    "invocationResult": "SUCCESS"
  }
}

Esquemas

Cada tipo de política se define mediante un esquema XML (.xsd). Puedes consultar los esquemas de políticas en GitHub.

Política SanitizeUserPrompt Organízate con las colecciones Guarda y clasifica el contenido según tus preferencias.

Información general

Antes de empezar

Roles obligatorios

Habilitar APIs

Elemento <SanitizeUserPrompt>

Sintaxis

Política predeterminada

Ejemplo

Referencia de elemento secundario

<DisplayName>

Sintaxis

Ejemplo

<IgnoreUnresolvedVariables>

<ModelArmor>

Sintaxis

Ejemplo

<UserPromptSource>

Variables de flujo

Referencia de errores

Errores de tiempo de ejecución

Errores de implementación

Variables de error

Ejemplo de respuesta de error

Regla de fallo de ejemplo

Código y mensajes de error de la plantilla de Model Armor

Esquemas

Política SanitizeUserPrompt

Elemento `<SanitizeUserPrompt>`

`<DisplayName>`

`<ModelArmor>`

`<UserPromptSource>`