Esta página se aplica a Apigee y Apigee Hybrid.
Consulta la documentación de
Apigee Edge.
La política de SanitizeModelResponse protege a los clientes de IA del contenido ofensivo o dañino, ya que depura 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 para los clientes y las cargas de trabajo de IA que usan Apigee. Model Armor es una Google Cloud oferta de servicios que proporciona medidas de seguridad de la IA para mitigar los riesgos asociados a los modelos de lenguaje grandes (LLM).
Esta política se usa junto con la política de 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 SanitizeModelResponse, debes completar las siguientes tareas:
- Crea una plantilla de Model Armor. Se debe completar este paso antes de crear una política de SanitizeModelResponse.
- Establece el extremo de API para el servicio de Model Armor.
Roles requeridos
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
Enable the Model Armor APIs.
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> </SanitizeModelResponse>
Política predeterminada
En el siguiente ejemplo, se muestra la configuración predeterminada cuando agregas una política de 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> </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 De forma opcional, usa el elemento |
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:
|
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 no se resuelve la variable que se usa para el nombre de la plantilla o la carga útil de Model Armor. |
<TemplateName> |
Obligatorio | Es la plantilla de Model Armor que se usó para limpiar la respuesta del LLM.
Este valor se puede generar 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 plantillas de mensajes de Apigee, incluido el uso de variables o funciones de ruta de acceso JSON. {jsonpath('$.contents[-1].parts[-1].text',request.content,false)} |
<LLMResponseSource> |
Obligatorio | Ubicación de la carga útil del texto de respuesta del LLM 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 ruta de acceso JSON. {jsonpath('$.input.prompt.text',request.content,false)} |
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>
Es 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>
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)}
Valor predeterminado | {jsonPath($.contents[-1].parts[-1].text,request.content,true)} |
¿Es obligatorio? | Obligatorio |
Tipo | String |
Elemento principal |
<SanitizeModelResponse>
|
Elementos secundarios | Ninguno |
<LLMResponseSource>
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 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($.candidates[-1].content.parts,response.content,true)} |
¿Es obligatorio? | Obligatorio |
Tipo | String |
Elemento principal |
<SanitizeModelResponse>
|
Elementos secundarios | Ninguno |
Variables de flujo
Las variables de flujo se pueden usar a fin de configurar el comportamiento del entorno de ejecución dinámico de las políticas y los flujos, según los encabezados HTTP, 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.
La política puede establecer estas variables de solo lectura durante la ejecución.
Nombre de la variable | Descripción |
---|---|
SanitizeModelResponse.POLICY_NAME.templateUsed |
Especifica qué plantilla de protección del modelo 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 sanear el contenido. |
SanitizeModelResponse.POLICY_NAME.modelResponse |
Especifica el contenido de la respuesta del LLM que se usa para la llamada a Model Armor para sanear el contenido. |
SanitizeModelResponse.POLICY_NAME.responseFromModelArmor |
Especifica la respuesta JSON de Model Armor. Model Armor |
SanitizeModelResponse.POLICY_NAME.filterMatchState |
Especifica si se encontró una coincidencia para 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 los siguientes valores:
|
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 |
Es el 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 la inspección del filtro de SDP. Los valores válidos incluyen MATCH_FOUND y NO_MATCH_FOUND . |
SanitizeModelResponse.POLICY_NAME.sdpFilterResult.deidentifyResult.executionState |
Es el filtro de SDP para identificar el estado de ejecución del resultado. Los valores válidos incluyen EXECUTION_SUCCESS y EXECUTION_SKIPPED . |
SanitizeModelResponse.POLICY_NAME.sdpFilterResult.deidentifyResult.matchState |
Es el filtro de SDP del estado de coincidencia del resultado de identificación. Los valores válidos incluyen MATCH_FOUND y NO_MATCH_FOUND . |
SanitizeModelResponse.POLICY_NAME.piAndJailbreakFilterResult.executionState |
Es el 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 |
Es el estado de coincidencia de los resultados del filtro de jailbreak y de inyección de instrucciones. 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 |
Es el estado de ejecución del filtro de URI malicioso. Los valores válidos incluyen EXECUTION_SUCCESS y EXECUTION_SKIPPED . |
SanitizeModelResponse.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 . |
SanitizeModelResponse.POLICY_NAME.sanitizationMetadata.errorCode |
Es el código de error personalizado anulado si está presente en la respuesta de Model Armor. |
SanitizeModelResponse.POLICY_NAME.sanitizationMetadata.errorMessage |
Es el código de error personalizado anulado si está presente en la respuesta de Model Armor. |
SanitizeModelResponse.POLICY_NAME.csamFilterMatched/code> |
Es un valor booleano que indica si se encontró una coincidencia con el filtro de CSAM. |
SanitizeModelResponse.POLICY_NAME.maliciousURIs |
Lista anexada de URIs maliciosos detectados por el filtro de URI malicioso. |
SanitizeModelResponse.POLICY_NAME.maliciousURIsDetected |
Es un valor booleano que indica si hubo una coincidencia con el filtro de URI malicioso. |
SanitizeModelResponse.POLICY_NAME.matchesFound |
Es un valor booleano que indica si coincidió alguno de los filtros. |
SanitizeModelResponse.POLICY_NAME.promptInjectionDetected |
Es un valor booleano que indica si se encontró una coincidencia en 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 |
Es un valor booleano que indica si se encontró una coincidencia con el filtro de RAI. |
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 Qué debes saber sobre los errores de políticas y Cómo solucionar fallas.
Errores de entorno 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 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 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 del entorno 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
{ "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>
Código y mensajes de error de la plantilla de Model Armor
La plantilla de Model Armor admite la anulación de códigos 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 y 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.