Política de SanitizeModelResponse

Política extensible

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

Consulta la documentación de Apigee Edge.

Nota: Esta política es compatible con Apigee y con la versión 1.15.1 y posteriores de Apigee Hybrid.

La política SanitizeModelResponse protege a los clientes de IA del contenido dañino o ofensivo, ya que limpia las respuestas de los modelos de IA generativa. La política usa Model Armor para evaluar las respuestas del modelo en busca de contenido ofensivo o dañino, lo que permite la protección nativa de los clientes y 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 se usa junto con la política SanitizeUserPrompt.

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.

Nota: Si configuraste un proxy de reenvío para tu entorno, las llamadas salientes que realiza esta política a Model Armor se enrutan a través del proxy. No se requiere configuración a nivel de la política. Esto se aplica a Apigee y Apigee Hybrid 1.16.10 y versiones posteriores, y 1.17.0 y versiones posteriores. Para obtener más información, consulta Configura el proxy de reenvío (Apigee) o Configura el proxy de reenvío para los proxies de API (Apigee Hybrid).

Antes de comenzar

Antes de usar la política SanitizeModelResponse, debes completar las siguientes tareas:

• Crear una plantilla de Model Armor Este paso se debe completar antes de crear una política de SanitizeModelResponse.
• Establece el extremo de API para el servicio de Model Armor.

Roles obligatorios

Para obtener los permisos que necesitas para aplicar y usar la política SanitizeModelResponse, 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 las APIs de Model Armor, si aún no están habilitadas.

Roles necesarios para habilitar las APIs

Para habilitar 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 obtener este permiso a través del rol de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin). Obtén más información para otorgar roles.

Habilitar las API

Elemento <SanitizeModelResponse>

Define una política SanitizeModelResponse.

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> <LLMResponseSource>

El elemento <SanitizeModelResponse> usa la siguiente sintaxis:

Sintaxis

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

Política predeterminada

En el siguiente ejemplo, se muestra la configuración predeterminada cuando agregas una política SanitizeModelResponse a tu flujo de solicitudes en la IU de Apigee:

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

Cuando insertas una nueva política SanitizeModelResponse 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 <SanitizeModelResponse>:

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.
<TemplateName>	Obligatorio	Es la plantilla de Model Armor que se usa para sanear la respuesta del LLM. 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>	Obligatorio	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 la plantilla de mensajes de Apigee, incluido el uso de variables o funciones de ruta de acceso de JSON. Por ejemplo: {jsonpath('$.contents[-1].parts[-1].text',request.content,false)}
<LLMResponseSource>	Obligatorio	Es la ubicación de la carga útil para extraer el texto de respuesta del LLM. 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 ruta de acceso JSON. Por ejemplo: {jsonpath('$.input.prompt.text',request.content,false)}
<FunctionCallSource>	Opcional	Es la ubicación de los argumentos de la llamada a función que se extraerán de las respuestas del modelo. Se usa como resguardo cuando <LLMResponseSource> devuelve un valor vacío en los turnos de llamada a función. Valor predeterminado: {jsonPath('$.candidates[-1].content.parts[-1].functionCall.args',response.content,true)}

Referencia del elemento secundario

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

<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	<SanitizeModelResponse>
Elementos secundarios	Ninguno

<TemplateName>

La plantilla de Model Armor.

Valor predeterminado	N/A
¿Es obligatorio?	Obligatorio
Tipo	String
Elemento principal	<SanitizeModelResponse>
Elementos secundarios	Ninguno

El elemento <TemplateName> 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>

<UserPromptSource>

Es la ubicación de la carga útil para extraer el texto de la instrucción del usuario. Solo se admiten valores de texto de cadena.

Este campo admite la sintaxis de la plantilla de mensajes de Apigee, incluido el uso de variables o funciones de ruta de acceso JSON. Por ejemplo:

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

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

<LLMResponseSource>

Es la ubicación de la carga útil de la respuesta del LLM que se extraerá. Solo se admiten valores de texto de cadena.

Este campo admite la sintaxis de la plantilla de mensajes de Apigee, incluido el uso de variables o funciones de ruta de acceso JSON. Por ejemplo:

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

Valor predeterminado	{jsonPath($.candidates[-1].content.parts,response.content,true)}
¿Es obligatorio?	Obligatorio
Tipo	String
Elemento principal	<SanitizeModelResponse>
Elementos secundarios	Ninguno

<FunctionCallSource>

Ubicación de los argumentos de la llamada a función que se extraerán de la respuesta del modelo. Este elemento se usa como resguardo cuando <LLMResponseSource> devuelve un valor vacío, lo que ocurre cuando el modelo devuelve una invocación de llamada a función en lugar de contenido de texto.

Este campo admite la sintaxis de la plantilla de mensajes, incluidas las funciones de ruta de acceso JSON.

Valor predeterminado	{jsonPath('$.candidates[-1].content.parts[-1].functionCall.args',response.content,true)}
¿Es obligatorio?	Opcional
Tipo	String
Elemento principal	<SanitizeModelResponse>
Elementos secundarios	Ninguno

Variables de flujo

Las variables de flujo se pueden usar para configurar 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 del mensaje, o el contexto disponible en el flujo. Para obtener más información sobre las variables de flujo, consulta 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
SanitizeModelResponse.POLICY_NAME.templateUsed	Especifica qué plantilla de Model Armor se usa. Por ejemplo: projects/myproject/locations/us-west1/templates/mytemplate
SanitizeModelResponse.POLICY_NAME.userPrompt	Especifica el contenido de la instrucción que se usa para la llamada a Model Armor para limpiar el contenido.
SanitizeModelResponse.POLICY_NAME.modelResponse	Especifica el contenido de la respuesta del LLM que se usa para la llamada a Model Armor para limpiar el contenido.
SanitizeModelResponse.POLICY_NAME.responseFromModelArmor	Especifica la respuesta en formato JSON de Model Armor. Model Armor
SanitizeModelResponse.POLICY_NAME.filterMatchState	Especifica si se encontró una coincidencia con el filtro. Los valores válidos incluyen MATCH_FOUND y NO_MATCH_FOUND.
SanitizeModelResponse.POLICY_NAME.invocationResult	Es un campo que indica el resultado de la invocación, independientemente del estado de la coincidencia. Puede tener lo siguiente: SUCCESS: Todos los filtros se ejecutaron correctamente. PARCIAL: Se omitieron algunos filtros o falló su ejecución. FAILURE: Se omitieron todos los filtros o no se ejecutaron correctamente.
SanitizeModelResponse.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.
SanitizeModelResponse.POLICY_NAME.raiFilterResult.matchState	Estado de coincidencia del filtro de RAI. Los valores válidos incluyen MATCH_FOUND y NO_MATCH_FOUND.
SanitizeModelResponse.POLICY_NAME.sdpFilterResult.inspectResult.executionState	Es el estado de ejecución del resultado de la inspección del filtro de SDP. Los valores válidos incluyen EXECUTION_SUCCESS y EXECUTION_SKIPPED.
SanitizeModelResponse.POLICY_NAME.sdpFilterResult.inspectResult.matchState	Es el estado de coincidencia del resultado de inspección del filtro de SDP. Los valores válidos incluyen MATCH_FOUND y NO_MATCH_FOUND.
SanitizeModelResponse.POLICY_NAME.sdpFilterResult.deidentifyResult.executionState	Estado de ejecución del resultado de la identificación del filtro de SDP. Los valores válidos incluyen EXECUTION_SUCCESS y EXECUTION_SKIPPED.
SanitizeModelResponse.POLICY_NAME.sdpFilterResult.deidentifyResult.matchState	Estado de coincidencia del resultado de desidentificación del filtro de SDP. Los valores válidos incluyen MATCH_FOUND y NO_MATCH_FOUND.
SanitizeModelResponse.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.
SanitizeModelResponse.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.
SanitizeModelResponse.POLICY_NAME.csamFilterFilterResult.executionState	Es el estado de ejecución del filtro de CSAM. Los valores válidos incluyen EXECUTION_SUCCESS y EXECUTION_SKIPPED.
SanitizeModelResponse.POLICY_NAME.csamFilterFilterResult.matchState	Estado de coincidencia del filtro de CSAM Los valores válidos incluyen MATCH_FOUND y NO_MATCH_FOUND.
SanitizeModelResponse.POLICY_NAME.maliciousUriFilterResult.executionState	Estado de ejecución del filtro de URIs maliciosos. Los valores válidos incluyen EXECUTION_SUCCESS y EXECUTION_SKIPPED.
SanitizeModelResponse.POLICY_NAME.maliciousUriFilterResult.matchState	Estado de coincidencia del filtro de URI malicioso. Los valores válidos incluyen MATCH_FOUND y NO_MATCH_FOUND.
SanitizeModelResponse.POLICY_NAME.sanitizationMetadata.errorCode	Código de error anulado personalizado si está presente en la respuesta de Model Armor.
SanitizeModelResponse.POLICY_NAME.sanitizationMetadata.errorMessage	Código de error anulado personalizado si está presente en la respuesta de Model Armor.
SanitizeModelResponse.POLICY_NAME.csamFilterMatched	Es un valor booleano que indica si se encontró una coincidencia con el filtro de CSAM.
SanitizeModelResponse.POLICY_NAME.maliciousURIs	Es la lista adjunta de URIs maliciosos detectados por el filtro de URIs maliciosos.
SanitizeModelResponse.POLICY_NAME.maliciousURIsDetected	Es un valor booleano que indica si hubo coincidencia con el filtro de URI malicioso.
SanitizeModelResponse.POLICY_NAME.matchesFound	Valor booleano que indica si alguno de los filtros coincidió.
SanitizeModelResponse.POLICY_NAME.promptInjectionDetected	Es un valor booleano que indica si se encontró una coincidencia con el filtro de inyección de instrucciones.
SanitizeModelResponse.POLICY_NAME.promptInjectionConfidence	Es el nivel de confianza de la detección de inyección de instrucciones.
SanitizeModelResponse.POLICY_NAME.raiMatchesFound	Valor booleano que indica si el filtro de RAI coincidió.
SanitizeModelResponse.POLICY_NAME.requestSentToModelArmor	Es un valor booleano que indica si se envió una solicitud a Model Armor.
SanitizeModelResponse.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 se muestran, y las variables de falla que establece Apigee específicas para la política <SanitizeModelResponse>. 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

Código de falla	Estado de HTTP	Causa
steps.sanitize.model.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.model.response.SanitizationResponseParsingFailed	500	Este error se produce si no se puede analizar la respuesta de Model Armor.
steps.sanitize.model.response.FailedToExtractUserPrompt	500	Este error se produce si falló la extracción automática de la instrucción del usuario para el valor predeterminado.
steps.sanitize.model.response.FailedToExtractLLMResponse	500	Este error se produce si falló la extracción automática de la respuesta del modelo para el valor predeterminado.
steps.sanitize.model.response.InternalError	500	Este error se produce si hay un error interno del servidor.
steps.sanitize.model.response.ModelArmorTemplateNameExtractionFailed	500	Este error se produce si no se puede resolver el nombre de la plantilla.
steps.sanitize.model.response.AuthenticationFailure	500	Este error se produce si la cuenta de servicio no tiene permiso para llamar a la API de Model Armor.
steps.sanitize.model.response.ModelArmorAPIFailed	500	Este error se produce si la API de Model Armor arroja un error.
steps.sanitize.model.response.ModelArmorCalloutError	500	Este error ocurre 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 de <TemplateName> está vacío.

Variables con fallas

Estas variables se configuran cuando esta política activa un error en el entorno 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"
SanitizeModelResponse.POLICY_NAME.failed	POLICY_NAME es el nombre especificado por el usuario de la política que generó la falla.	SanitizeModelResponse.sanitize-response.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": "SanitizeModelResponse[sanitize-response]: unable to resolve variable [variable_name]",
    "detail": {
      "errorcode": "steps.sanitizemodelresponse.UnresolvedVariable"
    }
  }
}

Ejemplo de regla de falla

<FaultRule name="SanitizeModelResponse Faults">
    <Step>
        <Name>SMR-CustomSetVariableErrorResponse</Name>
        <Condition>(fault.name = "SetVariableFailed")</Condition>
    </Step>
    <Condition>(sanitizemodelresponse.failed = true)</Condition>
</FaultRule>

Mensajes y códigos de error de la plantilla de Model Armor

La plantilla de Model Armor admite la anulación de códigos de error y mensajes de error que arrojan las solicitudes a la API de la política de SanitizeModelResponse. Si el usuario establece las anulaciones, los códigos de error y los mensajes de error de Model Armor completarán 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.