Google utiliza tecnología de IA para traducir contenido a tu idioma preferido. Las traducciones realizadas con IA pueden contener errores.

Política SanitizeUserPrompt

Política extensible

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

Consulta la documentación de Apigee Edge.

La política SanitizeUserPrompt protege las aplicaciones de IA del contenido dañino limpiando las instrucciones de los usuarios que se envían a los modelos de IA generativa. La política usa Model Armor para evaluar las instrucciones del usuario en busca de contenido dañino, lo que permite la protección nativa de las cargas de trabajo de IA con Apigee. Model Armor es un servicio de Google Cloud que ofrece medidas de seguridad de la IA para mitigar los riesgos asociados con los modelos de lenguaje grandes (LLM).

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

Esta política es una política extensible, y el uso de esta política puede tener implicaciones de costo o uso, según tu licencia de Apigee. Para obtener información sobre los tipos de políticas y sus implicaciones de uso, consulta Tipos de políticas.

Antes de comenzar

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

Crear una plantilla de Model Armor Completa este paso antes de crear una política SanitizeUserPrompt.
Establece el extremo de API para el servicio de 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, pídele a tu administrador que te otorgue los siguientes roles de IAM en la cuenta de servicio que usas para implementar proxies de Apigee:

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

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Habilita las APIs

Habilita la API de Model Armor si aún no está habilitada.

Roles necesarios para habilitar las APIs

Para habilitar las APIs, necesitas el permiso serviceusage.services.enable. Si creaste el proyecto, es probable que ya tengas este permiso a través del rol de propietario (roles/owner). De lo contrario, puedes obtenerlo a través del rol de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin). Obtén más información para otorgar roles.

Habilitar la API

Elemento `<SanitizeUserPrompt>`

Define una política SanitizeUserPrompt.

Valor predeterminado	Consulta la pestaña Política predeterminada, a continuación
¿Es obligatorio?	Obligatorio
Tipo	Objeto complejo
Elemento principal	N/A
Elementos secundarios	`<DisplayName>` `<IgnoreUnresolvedVariables>` `<TemplateName>` `<UserPromptSource>`

El elemento <SanitizeUserPrompt> usa 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>
  <FunctionResponseSource>{jsonPath('$.contents[-1].parts[-1].functionResponse.response',request.content,true)}</FunctionResponseSource>
</SanitizeUserPrompt>

Política predeterminada

En el siguiente ejemplo, se muestra la configuración predeterminada cuando agregas una política SanitizeUserPrompt a tu flujo de solicitud en la IU 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>
  <FunctionResponseSource>{jsonPath('$.contents[-1].parts[-1].functionResponse.response',request.content,true)}</FunctionResponseSource>
</SanitizeUserPrompt>

Cuando insertas una nueva política SanitizeUserPrompt con la IU de Apigee, la plantilla contiene stubs para todas las operaciones posibles. Consulta la información que aparece a continuación sobre los elementos obligatorios.

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

Atributo	Predeterminada	(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. De forma opcional, usa el elemento `<DisplayName>` para etiquetar la política en el editor de proxy de la IU de administración con un nombre de lenguaje natural diferente.
`continueOnError`	falso	Opcional	Configúralo como `false` para mostrar un error cuando una política falla. Este es el comportamiento previsto para la mayoría de las políticas. Configúralo como `true` para continuar con la ejecución del flujo incluso después de que una política falle. También consulta: Las reglas de fallas se activan SOLAMENTE en un estado de error (sobre el continueOnError) Controla fallas dentro del flujo actual
`enabled`	true	Opcional	Configúralo como `true` para aplicar la política. Configúralo como `false` para desactivar la política. La política no se aplicará, incluso si permanece conectada a un flujo.
`async`	falso	Obsoleta	Este atributo dejó de estar disponible.

En la siguiente tabla, se proporciona una descripción de alto nivel de los elementos secundarios de <SanitizeUserPrompt>:

Elemento secundario	¿Es obligatorio?	Descripción
`<DisplayName>`	Opcional	Es el nombre de la política.
`<IgnoreUnresolvedVariables>`	Opcional	Especifica si el procesamiento se detiene si la variable que se usa para el nombre de la plantilla o la carga útil de Model Armor no se resuelve.
`<ModelArmor>`	Obligatorio	Contiene la información requerida para especificar la plantilla de Model Armor.
`<UserPromptSource>`	Opcional	Ubicación de la carga útil del texto de la instrucción del usuario que se extraerá. Solo se admiten valores de texto de cadena. Este campo admite la sintaxis de plantillas de mensajes de Apigee, incluido el uso de variables o funciones de JSON Path. Por ejemplo: {jsonpath('$.input.prompt.text',request.content,false)}
`<FunctionResponseSource>`	Opcional	Es la ubicación de los datos de respuesta de la función o herramienta que se extraerán. Se usa como resguardo cuando `<UserPromptSource>` devuelve un valor vacío en los turnos de llamada a función. Valor predeterminado: `{jsonPath('$.contents[-1].parts[-1].functionResponse.response',request.content,true)}`

Ejemplo

En esta sección, se proporciona un ejemplo del uso de <SanitizeUserPrompt>.

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

<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 del elemento secundario

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

`<DisplayName>`

Se usan además del atributo name para etiquetar la política en el editor de proxy de la IU de administración con un nombre de lenguaje natural diferente.

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

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

El elemento <DisplayName> usa 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 una variable no se resuelve. Configúralo como 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	String
Elemento principal
Elementos secundarios	`<TemplateName>`

El elemento <ModelArmor> usa 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 completar la información requerida.

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

En la siguiente tabla, se proporciona una descripción de alto nivel de los elementos secundarios de <ModelArmor>.

Elemento secundario ¿Es obligatorio? Descripción

Elemento secundario	¿Es obligatorio?	Descripción
`<TemplateName>`	Obligatorio	String Es la plantilla de Model Armor que se usó para limpiar la instrucción del usuario. Este valor se puede usar como plantilla con las siguientes variables de flujo de Apigee: projects/{organization.name}/locations/{system.region.name}/templates/{id}

<TemplateName>

Obligatorio

String

Es la plantilla de Model Armor que se usó para limpiar la instrucción del usuario.

Este valor se puede usar como plantilla con las siguientes variables de flujo de Apigee:

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

`<UserPromptSource>`

Es la ubicación de la carga útil para extraer el texto de la instrucción del usuario. Este campo admite la sintaxis de plantillas de mensajes de Apigee, incluido el uso de variables o funciones de JSON Path. Por ejemplo:

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

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

<FunctionResponseSource>

Ubicación de los datos de respuesta de la función o herramienta que se extraerán de la solicitud. Este elemento se usa como alternativa cuando <UserPromptSource> devuelve un valor vacío, lo que ocurre en los turnos de llamadas a funciones en los que la última entrada de contenido contiene una respuesta de función en lugar de texto. Los datos de respuesta de la función se deben limpiar porque contienen datos externos no confiables de APIs y bases de datos.

Este campo admite la sintaxis de plantillas de mensajes, incluidas las funciones de JSON Path.

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

Variables de flujo

Las variables de flujo configuran el comportamiento dinámico del entorno de ejecución para las políticas y los flujos, en función de los encabezados HTTP o 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. Puedes usar estas variables de flujo con la política DataCapture para crear informes de estadísticas personalizados. Para obtener más información, consulta Recopila datos de clientes con la política de captura de datos.

Nombre de la 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 instrucción que se usa para la llamada a Model Armor para limpiar el contenido.
`SanitizeUserPrompt.POLICY_NAME.modelResponse`	Especifica el contenido de la respuesta del LLM que se usa para la llamada a Model Armor para limpiar el contenido.
`SanitizeUserPrompt.POLICY_NAME.responseFromModelArmor`	Especifica la respuesta en formato JSON de Model Armor.
`SanitizeUserPrompt.POLICY_NAME.filterMatchState`	Especifica si el filtro coincidió. Los valores válidos incluyen `MATCH_FOUND` y `NO_MATCH_FOUND`.
`SanitizeUserPrompt.POLICY_NAME.invocationResult`	Es un campo que indica el resultado de la invocación, independientemente del estado de coincidencia. Puede tener lo siguiente: SUCCESS: Todos los filtros se ejecutaron correctamente. PARCIAL: Se omitieron algunos filtros o no se ejecutaron. FAILURE: Se omitieron todos los filtros o no se ejecutaron correctamente.
`SanitizeUserPrompt.POLICY_NAME.raiFilterResult.executionState`	Es el resultado de la ejecución del filtro de RAI. Los valores válidos incluyen `EXECUTION_SUCCESS` y `EXECUTION_SKIPPED`.
`SanitizeUserPrompt.POLICY_NAME.raiFilterResult.matchState`	Es el estado de coincidencia del filtro de RAI. Los valores válidos incluyen `MATCH_FOUND` y `NO_MATCH_FOUND`.
`SanitizeUserPrompt.POLICY_NAME.sdpFilterResult.inspectResult.executionState`	Estado de ejecución del resultado de la inspección del filtro de SDP. Los valores válidos incluyen `EXECUTION_SUCCESS` y `EXECUTION_SKIPPED`.
`SanitizeUserPrompt.POLICY_NAME.sdpFilterResult.inspectResult.matchState`	Estado de coincidencia del resultado de la inspección del filtro de SDP. Los valores válidos incluyen `MATCH_FOUND` y `NO_MATCH_FOUND`.
`SanitizeUserPrompt.POLICY_NAME.sdpFilterResult.deidentifyResult.executionState`	Estado de ejecución del resultado de desidentificación del filtro de SDP. Los valores válidos incluyen `EXECUTION_SUCCESS` y `EXECUTION_SKIPPED`.
`SanitizeUserPrompt.POLICY_NAME.sdpFilterResult.deidentifyResult.matchState`	Es el estado de coincidencia del resultado de la identificación del filtro de SDP. Los valores válidos incluyen `MATCH_FOUND` y `NO_MATCH_FOUND`.
`SanitizeUserPrompt.POLICY_NAME.piAndJailbreakFilterResult.executionState`	Estado de ejecución de los resultados del filtro de inyección de instrucciones y jailbreak. Los valores válidos incluyen `EXECUTION_SUCCESS` y `EXECUTION_SKIPPED`.
`SanitizeUserPrompt.POLICY_NAME.piAndJailbreakFilterResult.matchState`	Estado de coincidencia de los resultados del filtro de inyección de instrucciones y jailbreak. Los valores válidos incluyen `MATCH_FOUND` y `NO_MATCH_FOUND`.
`SanitizeUserPrompt.POLICY_NAME.csamFilterFilterResult.executionState`	Es el estado de ejecución del filtro de CSAM. Los valores válidos incluyen `EXECUTION_SUCCESS` y `EXECUTION_SKIPPED`.
`SanitizeUserPrompt.POLICY_NAME.csamFilterFilterResult.matchState`	Estado de coincidencia del filtro de CSAM Los valores válidos incluyen `MATCH_FOUND` y `NO_MATCH_FOUND`.
`SanitizeUserPrompt.POLICY_NAME.maliciousUriFilterResult.executionState`	Estado de ejecución del filtro de URIs maliciosos. Los valores válidos incluyen `EXECUTION_SUCCESS` y `EXECUTION_SKIPPED`.
`SanitizeUserPrompt.POLICY_NAME.maliciousUriFilterResult.matchState`	Es el estado de coincidencia del filtro de URI malicioso. Los valores válidos incluyen `MATCH_FOUND` y `NO_MATCH_FOUND`.
`SanitizeUserPrompt.POLICY_NAME.sanitizationMetadata.errorCode`	Es el código de error personalizado anulado si está presente en la respuesta de Model Armor.
`SanitizeUserPrompt.POLICY_NAME.sanitizationMetadata.errorMessage`	Código de error anulado personalizado si está presente en la respuesta de Model Armor.
`SanitizeUserPrompt.POLICY_NAME.csamFilterMatched`	Es un valor booleano que indica si se encontró una coincidencia con el filtro de CSAM.
`SanitizeUserPrompt.POLICY_NAME.maliciousURIs`	Es la lista adjunta de URIs maliciosos detectados por el filtro de URIs maliciosos.
`SanitizeUserPrompt.POLICY_NAME.maliciousURIsDetected`	Valor booleano que indica si el filtro de URI malicioso coincidió.
`SanitizeUserPrompt.POLICY_NAME.matchesFound`	Es un valor booleano que indica si alguno de los filtros coincidió.
`SanitizeUserPrompt.POLICY_NAME.promptInjectionDetected`	Es un valor booleano que indica si se encontró una coincidencia con el filtro de inyección de instrucciones.
`SanitizeUserPrompt.POLICY_NAME.promptInjectionConfidence`	Es el nivel de confianza de la detección de inyección de instrucciones.
`SanitizeUserPrompt.POLICY_NAME.raiMatchesFound`	Es un valor booleano que indica si se encontró una coincidencia con el filtro de RAI.
`SanitizeUserPrompt.POLICY_NAME.requestSentToModelArmor`	Es un valor booleano que indica si se envió una solicitud a Model Armor.
`SanitizeUserPrompt.POLICY_NAME.sanitizeOperation`	Especifica la operación que realiza la política. Los valores válidos incluyen `SANITIZE_USER_PROMPT` y `SANITIZE_MODEL_RESPONSE`.

Referencia de errores

En esta sección, se describen los códigos de falla y los mensajes de error que devuelve Apigee, y las variables de falla que establece Apigee para la política SanitizeUserPrompt. Esta información es importante para saber si estás desarrollando reglas de fallas con el propósito de manejar fallas. Para obtener más información, consulta Lo que necesitas saber sobre los errores de políticas y Controla fallas.

Errores de tiempo de ejecución

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

Código de falla	Estado de HTTP	Causa
`steps.sanitize.user.prompt.response.FilterMatched`	`400`	Este error se produce si la instrucción del usuario no pasa la verificación de la plantilla de 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 falla la extracción automática de la instrucció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 de Model Armor.
`steps.sanitize.modelarmor.ModelArmorAPIFailed`	`500`	Este error se produce si la API de Model Armor arroja un error.
`steps.sanitize.modelarmor.ModelArmorCalloutError`	`500`	Este error se produce si falla la llamada a la API de Model Armor.
`steps.sanitize.modelarmor.ServiceUnavailable`	`500`	Este error se produce si el servicio de Model Armor no está disponible.

Errores en la implementación

Estos errores pueden generarse cuando implementas un proxy que contiene esta política.

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

Variables con fallas

Esta política establece estas variables cuando activa un error en el tiempo de ejecución. Para obtener más información, consulta Qué debes saber sobre los errores de la política.

Variables	Donde	Ejemplo
`fault.name="FAULT_NAME"`	`FAULT_NAME` es el nombre de la falla, como se indica en la tabla de errores de tiempo de ejecución anterior. El nombre de la falla es la última parte del código de la falla.	`fault.name Matches "UnresolvedVariable"`
`SanitizeUserPrompt.POLICY_NAME.failed`	`POLICY_NAME` es el nombre especificado por el usuario de la política que generó la falla.	`SanitizeUserPrompt.sanitize-prompt.failed = true`

Ejemplo de respuesta de error

Nota: Para el manejo de errores, la mejor práctica es capturar la parte errorcode de la respuesta de error. No dependas del texto en la faultstring, ya que podría cambiar.

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

Ejemplo de regla de falla

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

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

La plantilla de Model Armor admite la anulación de los códigos de error y los mensajes de error que arrojan las solicitudes a la API de la política SanitizeUserPrompt. Si el usuario establece las anulaciones, los códigos de error y los mensajes de error de Model Armor propagan las variables de flujo.

Por ejemplo, una respuesta con códigos y mensajes de error de Model Armor podría verse de la siguiente manera:

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

Esquemas

Un esquema XML (.xsd) define cada tipo de política. Como referencia, los esquemas de políticas están disponibles en GitHub.

Política SanitizeUserPrompt Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Antes de comenzar

Roles obligatorios

Habilita las APIs

Elemento <SanitizeUserPrompt>

Sintaxis

Política predeterminada

Ejemplo

Referencia del elemento secundario

<DisplayName>

Sintaxis

Ejemplo

<IgnoreUnresolvedVariables>

<ModelArmor>

Sintaxis

Ejemplo

<UserPromptSource>

<FunctionResponseSource>

Variables de flujo

Referencia de errores

Errores de tiempo de ejecución

Errores en la implementación

Variables con fallas

Ejemplo de respuesta de error

Ejemplo de regla de falla

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

Esquemas

Política SanitizeUserPrompt

Elemento `<SanitizeUserPrompt>`

`<DisplayName>`

`<ModelArmor>`

`<UserPromptSource>`