Uso de la API de ApplyGuardrail en la aplicación - Amazon Bedrock
Llamada de la API ApplyGuardrail en el flujo de la aplicaciónEspecificación de la barrera de protección para utilizarla con ApplyGuardrailEjemplos de casos de uso de ApplyGuardrailDevuelve la salida completa en la respuesta de ApplyGuardrail

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Uso de la API de ApplyGuardrail en la aplicación

Las barreras de protección se utilizan para implementar protecciones para las aplicaciones de IA generativa que se personalizan según sus casos de uso y se alinean con sus políticas de IA responsable. Las barreras de protección le permiten configurar los temas denegados, filtrar el contenido dañino y eliminar la información confidencial.

Puede usar la API de ApplyGuardrail para evaluar cualquier texto con sus barreras de protección de Amazon Bedrock preconfiguradas, sin invocar los modelos fundacionales.

Las características de la API ApplyGuardrail son las siguientes:

  • Validación de contenido: puede enviar cualquier entrada o salida de texto a la API ApplyGuardrail para compararla con las reglas definidas para evitar temas, filtros de contenido, detectores de PII y listas de palabras bloqueadas. Puede evaluar las entradas de los usuarios y las salidas generadas por los FM de forma independiente.

  • Implementación flexible: puede integrar la API ApplyGuardrail en cualquier parte del flujo de la aplicación para validar los datos antes de procesar o entregar los resultados al usuario. Por ejemplo, si utiliza una aplicación RAG, ahora puede evaluar la entrada del usuario antes de recuperar el resultado, en lugar de esperar hasta que se genere la respuesta final.

  • Desacoplada de los modelos fundacionales: la API ApplyGuardrail está desacoplada de los modelos fundacionales. Ahora puede usar las barreras de protección sin invocar los modelos fundacionales. Puede utilizar los resultados de la evaluación para diseñar la experiencia en la aplicación de IA generativa.

Llamada de la API ApplyGuardrail en el flujo de la aplicación

La solicitud permite al cliente pasar todo el contenido que debe protegerse mediante las barreras de protección definidas. El campo de origen debe estar establecido en INPUT si el contenido que se va a evaluar proviene de un usuario (normalmente. la petición de entrada al LLM). El origen se debe establecer como OUTPUT si se deben aplicar las barreras de protección de salida del modelo (normalmente la respuesta de LLM).

Especificación de la barrera de protección para utilizarla con ApplyGuardrail

Cuando se usa ApplyGuardrail, se especifica el guardrailIdentifier y guardrailVersion de la barrera de protección que se quiere usar. También se puede activar el seguimiento de la barrera de protección, que proporciona información sobre el contenido que bloquea la barrera de protección.

ApplyGuardrail API request
POST /guardrail/{guardrailIdentifier}/version/{guardrailVersion}/apply HTTP/1.1
{
    "source": "INPUT" | "OUTPUT",
    "content": [{
        "text": {
            "text": "string",
        }
    }, ]
}
ApplyGuardrail API response
{
    "usage": { 
          "topicPolicyUnits": "integer",
          "contentPolicyUnits": "integer",
          "wordPolicyUnits": "integer",
          "sensitiveInformationPolicyUnits": "integer",
          "sensitiveInformationPolicyFreeUnits": "integer",
          "contextualGroundingPolicyUnits": "integer"
     },
    "action": "GUARDRAIL_INTERVENED" | "NONE",
    "output": [
            // if guardrail intervened and output is masked we return request in same format
            // with masking
            // if guardrail intervened and blocked, output is a single text with canned message
            // if guardrail did not intervene, output is empty array
            {
                "text": "string",
            },
    ],
    "assessments": [{
        "topicPolicy": {
                "topics": [{
                    "name": "string",
                    "type": "DENY",
                    "action": "BLOCKED",
                }]
            },
            "contentPolicy": {
                "filters": [{
                    "type": "INSULTS | HATE | SEXUAL | VIOLENCE | MISCONDUCT |PROMPT_ATTACK",
                    "confidence": "NONE" | "LOW" | "MEDIUM" | "HIGH",
                    "filterStrength": "NONE" | "LOW" | "MEDIUM" | "HIGH",
                "action": "BLOCKED"
                }]
            },
            "wordPolicy": {
                "customWords": [{
                    "match": "string",
                    "action": "BLOCKED"
                }],
                "managedWordLists": [{
                    "match": "string",
                    "type": "PROFANITY",
                    "action": "BLOCKED"
                }]
            },
            "sensitiveInformationPolicy": {
                "piiEntities": [{
                    // for all types see: https://docs.aws.amazon.com/bedrock/latest/APIReference/API_GuardrailPiiEntityConfig.html#bedrock-Type-GuardrailPiiEntityConfig-type
                    "type": "ADDRESS" | "AGE" | ...,
                    "match": "string",
                    "action": "BLOCKED" | "ANONYMIZED"
                }],
                "regexes": [{
                    "name": "string",
                    "regex": "string",
                    "match": "string",
                    "action": "BLOCKED" | "ANONYMIZED"
                }],
            "contextualGroundingPolicy": {
                 "filters": [{
                   "type": "GROUNDING | RELEVANCE",
                   "threshold": "double",
                   "score": "double",
                   "action": "BLOCKED | NONE"
                 }]
            },
            "invocationMetrics": {
                "guardrailProcessingLatency": "integer",
                "usage": {
                    "topicPolicyUnits": "integer",
                    "contentPolicyUnits": "integer",
                    "wordPolicyUnits": "integer",
                    "sensitiveInformationPolicyUnits": "integer",
                    "sensitiveInformationPolicyFreeUnits": "integer",
                    "contextualGroundingPolicyUnits": "integer"
                },
                "guardrailCoverage": {
                    "textCharacters": {
                        "guarded":"integer",
                        "total": "integer"
                    }
                }
            }
        },
        "guardrailCoverage": {
            "textCharacters": {
                "guarded": "integer",
                "total": "integer"
            }
        }
    ]
}

Ejemplos de casos de uso de ApplyGuardrail

Los resultados de la solicitud de ApplyGuardrail dependen de la acción que haya realizado la barrera de protección con el contenido transmitido.

  • Si la barrera de protección interviene donde el contenido solo está enmascarado, se devuelve el contenido exacto con el enmascaramiento aplicado.

  • Si la barrera de protección ha intervenido y bloqueado el contenido de la solicitud, el campo de salida será un texto único, que es el mensaje predefinido según la configuración de la barrera de protección.

  • Si no se ha realizado ninguna acción de barrera de protección sobre el contenido de la solicitud, la matriz de salidas estará vacía.

Guardrails takes no action

Ejemplo de solicitud

{
    "source": "OUTPUT",
    "content": [
        "text": {
            "text": "Hi, my name is Zaid. Which car brand is reliable?"
        }
    ]
}

Ejemplo de respuesta

{
    "usage": {
        "topicPolicyUnitsProcessed": 1,
        "contentPolicyUnitsProcessed": 1,
        "wordPolicyUnitsProcessed": 0,
        "sensitiveInformationPolicyFreeUnits": 0
    },
    "action": "NONE",
    "outputs": [],
    "assessments": [{}]
}
Guardrails blocks content

Ejemplo de respuesta

{
    "usage": {
        "topicPolicyUnitsProcessed": 1,
        "contentPolicyUnitsProcessed": 1,
        "wordPolicyUnitsProcessed": 0,
        "sensitiveInformationPolicyFreeUnits": 0
    },
    "action": "GUARDRAIL_INTERVENED",
    "outputs": [{
        "text": "Configured guardrail canned message (i.e., can't respond)"
    }],
    "assessments": [{
        "topicPolicy": {
            "topics": [{
                "name": "Cars",
                "type": "DENY",
                "action": "BLOCKED"
            }]
        },
        "sensitiveInformationPolicy": {
            "piiEntities": [{
                "type": "NAME",
                "match": "ZAID",
                "action": "ANONYMIZED"
            }],
            "regexes": []
        }
    }]
}
Guardrails masks content

Ejemplo de respuesta

Las barreras de protección intervienen ocultando el nombre ZAID.

{
    "usage": {
        "topicPolicyUnitsProcessed": 1,
        "contentPolicyUnitsProcessed": 1,
        "wordPolicyUnitsProcessed": 0,
        "sensitiveInformationPolicyFreeUnits": 0
    },
    "action": "GUARDRAIL_INTERVENED",
    "outputs": [{
            "text": "Hi, my name is {NAME}. Which car brand is reliable?"
        },
        {
            "text": "Hello {NAME}, ABC Cars are reliable ..."
        }
    ],
    "assessments": [{
        "sensitiveInformationPolicy": {
            "piiEntities": [{
                "type": "NAME",
                "match": "ZAID",
                "action": "ANONYMIZED"
            }],
            "regexes": []
        }
    }]
}
AWS CLI example

Ejemplo de entrada

aws bedrock-runtime apply-guardrail \
    --cli-input-json '{
        "guardrailIdentifier": "someGuardrailId",
        "guardrailVersion": "DRAFT",
        "source": "INPUT",
        "content": [
            {
                "text": {
                    "text": "How should I invest for my retirement? I want to be able to generate $5,000 a month"
                }
            }
        ]
    }' \
    --region us-east-1 \
    --output json

Ejemplo de salida (bloquea el contenido)

{
    "usage": {
        "topicPolicyUnits": 1,
        "contentPolicyUnits": 1,
        "wordPolicyUnits": 1,
        "sensitiveInformationPolicyUnits": 1,
        "sensitiveInformationPolicyFreeUnits": 0
    },
    "action": "GUARDRAIL_INTERVENED",
    "outputs": [
        {
            "text": "I apologize, but I am not able to provide fiduciary advice. ="
        }
    ],
    "assessments": [
        {
            "topicPolicy": {
                "topics": [
                    {
                        "name": "Fiduciary Advice",
                        "type": "DENY",
                        "action": "BLOCKED"
                    }
                ]
            }
        }
    ]
}

Devuelve la salida completa en la respuesta de ApplyGuardrail

El contenido se considera detectado si infringe las configuraciones de la barrera de protección. Por ejemplo, el fundamento contextual se considera detectado si la puntuación de fundamento o relevancia es inferior al umbral correspondiente.

De forma predeterminada, la operación ApplyGuardrail solo devuelve el contenido detectado en una respuesta. Puede especificar el campo outputScope con el valor FULL para obtener la salida completa. En este caso, la respuesta también incluirá entradas no detectadas para mejorar la depuración.

Puede configurar este mismo comportamiento en las operaciones Invoke y Converse estableciendo el seguimiento en la opción completa habilitada.

nota

El alcance de salida completa no se aplica a los filtros de palabras ni a las expresiones regulares en los filtros de información confidencial. Se aplica a todas las demás políticas de filtrado, incluida la información confidencial, con filtros que pueden detectar la información de identificación personal (PII).