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.

Inclusión de una barrera de protección con la API Converse

Puede usar una barrera de protección para proteger las aplicaciones conversacionales que cree con la API de Converse. Por ejemplo, si crea una aplicación de chat con la API Converse, puede usar una barrera de protección para bloquear el contenido inapropiado introducido por el usuario y el contenido inapropiado generado por el modelo. Para obtener información acerca de la API de Converse, consulte Cómo mantener una conversación con las operaciones de la API Converse.

Llamada a la API Converse con barreras de protección

Para usar una barrera de protección, debe incluir la información de configuración de la barrera de protección en las llamadas a las operaciones de Converse o ConverseStream (para transmitir respuestas). Si lo desea, puede seleccionar un contenido específico en el mensaje que desee que evalúe la barrera de protección. Para obtener más información acerca de los modelos que puede utilizar con barreras de protección y la API Converse, consulte Modelos y características del modelo compatibles.

Configuración de una barrera de protección para que funcione con la API Converse

La información de configuración de la barrera de protección se especifica en el parámetro de entrada guardrailConfig. La configuración incluye el ID y la versión de la barrera de protección que se desea utilizar. También se puede activar el seguimiento de la barrera de protección, que proporciona información sobre el contenido que ha bloqueado la barrera de protección.

Con la operación Converse, guardrailConfig es un objeto GuardrailConfiguration, como se muestra en el siguiente ejemplo.

{
        "guardrailIdentifier": "Guardrail ID",
        "guardrailVersion": "Guardrail version",
        "trace": "enabled"
}

Si usa ConverseStream, pasa un objeto GuardrailStreamConfiguration. Si lo desea, puede usar el campo streamProcessingMode para especificar que desea que el modelo complete la evaluación de la barrera de protección antes de devolver los fragmentos de respuesta de la transmisión. O bien, puede hacer que el modelo responda de forma asíncrona mientras la barrera de protección continúa con la evaluación en segundo plano. Para obtener más información, consulte Configuración del comportamiento de respuesta de transmisión para filtrar el contenido.

Evaluación de solo el contenido específico de un mensaje

Al pasar un mensaje (Message) a un modelo, la barrera de protección evalúa el contenido del mensaje. También puede evaluar partes específicas de un mensaje mediante el campo guardContent (GuardrailConverseContentBlock).

Por ejemplo, la barrera de protección evalúa solo el contenido del campo guardContent y no el resto del mensaje. Esto es útil para que la barrera de protección solo evalúe el mensaje más reciente de una conversación, tal como se muestra en el siguiente ejemplo.

[
    {
        "role": "user",
        "content": [
            {
                "text": "Create a playlist of 2 pop songs."
            }
        ]
    },
    {
        "role": "assistant",
        "content": [
            {
                "text": "Sure! Here are two pop songs:\n1. \"Bad Habits\" by Ed Sheeran\n2. \"All Of The Lights\" by Kanye West\n\nWould you like to add any more songs to this playlist?"
            }
        ]
    },
    {
        "role": "user",
        "content": [
            {
                "guardContent": {
                    "text": {
                        "text": "Create a playlist of 2 heavy metal songs."
                    }
                }
            }
        ]
    }
]

Otro caso de uso de guardContent es proporcionar un contexto adicional para un mensaje, sin que la barrera de protección evalúe ese contexto. En el siguiente ejemplo, la barrera de protección solo evalúa "Create a playlist of heavy metal songs" e ignora "Only answer with a list of songs".

messages = [
    {
        "role": "user",
        "content": [
            {
                "text": "Only answer with a list of songs."
            },
            {
                "guardContent": {
                    "text": {
                        "text": "Create a playlist of heavy metal songs."
                    }
                }
            }
        ]
    }
]

Si el contenido no está en un bloque guardContent, eso no significa necesariamente que no se vaya a evaluar. Este comportamiento depende de las políticas de filtrado que utilice la barrera de protección.

El siguiente ejemplo muestra dos bloques guardContent con verificaciones de fundamento contextual (basadas en los campos qualifiers). Las verificaciones de fundamento contextual de la barrera de protección solo evaluarán el contenido de estos bloques. Sin embargo, si la barrera de protección también tiene un filtro de palabras que bloquea la palabra “background”, el texto “Some additional background information.” se seguirá evaluando, aunque no esté en un bloque guardContent.

[{
    "role": "user",
    "content": [{
            "guardContent": {
                "text": {
                    "text": "London is the capital of UK. Tokyo is the capital of Japan.",
                    "qualifiers": ["grounding_source"]
                }
            }
        },
        {
            "text": "Some additional background information."
        },
        {
            "guardContent": {
                "text": {
                    "text": "What is the capital of Japan?",
                    "qualifiers": ["query"]
                }
            }
        }
    ]
}]

Protección de una petición del sistema enviada a la API Converse

Puede usar barreras de protección con las peticiones del sistema que envíe a la API Converse. Para proteger una petición del sistema, especifique el campo guardContent (SystemContentBlock) en la petición del sistema que transfiera a la API, tal como se muestra en el siguiente ejemplo.

[
    {
        "guardContent": {
            "text": {
                "text": "Only respond with Welsh heavy metal songs."
            }
        }
    }
]
            

Si no proporciona el campo guardContent, la barrera de protección no evaluará la petición del sistema.

Comportamiento de la barrera de protección de mensajes y peticiones del sistema

La forma en que la barrera de protección evalúa el campo guardContent es diferente entre las peticiones del sistema y los mensajes que se transmiten en el mensaje.

Procesamiento de la respuesta cuando se usa la API Converse

Al llamar a la operación Converse, la barrera de protección evalúa el mensaje que envía. Si la barrera de protección detecta contenido bloqueado, ocurrirá lo siguiente.

La siguiente respuesta parcial muestra el texto del contenido bloqueado y el seguimiento obtenido de la evaluación de la barrera de protección. La barrera de protección ha bloqueado el término Heavy metal en el mensaje.

{
    "output": {
        "message": {
            "role": "assistant",
            "content": [
                {
                    "text": "Sorry, I can't answer questions about heavy metal music."
                }
            ]
        }
    },
    "stopReason": "guardrail_intervened",
    "usage": {
        "inputTokens": 0,
        "outputTokens": 0,
        "totalTokens": 0
    },
    "metrics": {
        "latencyMs": 721
    },
    "trace": {
        "guardrail": {
            "inputAssessment": {
                "3o06191495ze": {
                    "topicPolicy": {
                        "topics": [
                            {
                                "name": "Heavy metal",
                                "type": "DENY",
                                "action": "BLOCKED"
                            }
                        ]
                    },
                    "invocationMetrics": {
                        "guardrailProcessingLatency": 240,
                        "usage": {
                            "topicPolicyUnits": 1,
                            "contentPolicyUnits": 0,
                            "wordPolicyUnits": 0,
                            "sensitiveInformationPolicyUnits": 0,
                            "sensitiveInformationPolicyFreeUnits": 0,
                            "contextualGroundingPolicyUnits": 0
                        },
                        "guardrailCoverage": {
                            "textCharacters": {
                                "guarded": 39,
                                "total": 72
                            }
                        }
                    }
                }
            }
        }
    }
}

Ejemplo de código para usar la API Converse con barreras de protección

En este ejemplo, se muestra cómo proteger una conversación con las operaciones Converse y ConverseStream. El ejemplo muestra cómo evitar que una modelo cree una lista de reproducción que incluya canciones del género heavy metal.

Converse

El siguiente código utiliza la barrera de protección en la operación Converse.

# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: Apache-2.0
"""
Shows how to use a guardrail with the <noloc>Converse</noloc> API.
"""

import logging
import json
import boto3


from botocore.exceptions import ClientError


logger = logging.getLogger(__name__)
logging.basicConfig(level=logging.INFO)


def generate_conversation(bedrock_client,
                          model_id,
                          messages,
                          guardrail_config):
    """
    Sends a message to a model.
    Args:
        bedrock_client: The Boto3 Bedrock runtime client.
        model_id (str): The model ID to use.
        messages JSON): The message to send to the model.
        guardrail_config : Configuration for the guardrail.

    Returns:
        response (JSON): The conversation that the model generated.

    """

    logger.info("Generating message with model %s", model_id)

    # Send the message.
    response = bedrock_client.converse(
        modelId=model_id,
        messages=messages,
        guardrailConfig=guardrail_config
    )

    return response


def main():
    """
    Entrypoint for example.
    """

    logging.basicConfig(level=logging.INFO,
                        format="%(levelname)s: %(message)s")

    # The model to use.
    model_id="meta.llama3-8b-instruct-v1:0"

    # The ID and version of the guardrail.
    guardrail_id = "Your guardrail ID"
    guardrail_version = "DRAFT"

    # Configuration for the guardrail.
    guardrail_config = {
        "guardrailIdentifier": guardrail_id,
        "guardrailVersion": guardrail_version,
        "trace": "enabled"
    }

    text = "Create a playlist of 2 heavy metal songs."
    context_text = "Only answer with a list of songs."

    # The message for the model and the content that you want the guardrail to assess.
    messages = [
        {
            "role": "user",
            "content": [
                {
                    "text": context_text,
                },
                {
                    "guardContent": {
                        "text": {
                            "text": text
                        }
                    }
                }
            ]
        }
    ]

    try:

        print(json.dumps(messages, indent=4))

        bedrock_client = boto3.client(service_name='bedrock-runtime')

        response = generate_conversation(
            bedrock_client, model_id, messages, guardrail_config)

        output_message = response['output']['message']

        if response['stopReason'] == "guardrail_intervened":
            trace = response['trace']
            print("Guardrail trace:")
            print(json.dumps(trace['guardrail'], indent=4))

        for content in output_message['content']:
            print(f"Text: {content['text']}")

    except ClientError as err:
        message = err.response['Error']['Message']
        logger.error("A client error occurred: %s", message)
        print(f"A client error occured: {message}")

    else:
        print(
            f"Finished generating text with model {model_id}.")


if __name__ == "__main__":
    main()

ConverseStream

El siguiente código utiliza la barrera de protección en la operación ConverseStream.

# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: Apache-2.0
"""
Shows how to use a guardrail with the ConverseStream operation.
"""

import logging
import json
import boto3


from botocore.exceptions import ClientError


logger = logging.getLogger(__name__)
logging.basicConfig(level=logging.INFO)


def stream_conversation(bedrock_client,
                    model_id,
                    messages,
                    guardrail_config):
    """
    Sends messages to a model and streams the response.
    Args:
        bedrock_client: The Boto3 Bedrock runtime client.
        model_id (str): The model ID to use.
        messages (JSON) : The messages to send.
        guardrail_config : Configuration for the guardrail.


    Returns:
        Nothing.

    """

    logger.info("Streaming messages with model %s", model_id)

    response = bedrock_client.converse_stream(
        modelId=model_id,
        messages=messages,
        guardrailConfig=guardrail_config
    )

    stream = response.get('stream')
    if stream:
        for event in stream:

            if 'messageStart' in event:
                print(f"\nRole: {event['messageStart']['role']}")

            if 'contentBlockDelta' in event:
                print(event['contentBlockDelta']['delta']['text'], end="")

            if 'messageStop' in event:
                print(f"\nStop reason: {event['messageStop']['stopReason']}")

            if 'metadata' in event:
                metadata = event['metadata']
                if 'trace' in metadata:
                    print("\nAssessment")
                    print(json.dumps(metadata['trace'], indent=4))


def main():
    """
    Entrypoint for streaming message API response example.
    """

    logging.basicConfig(level=logging.INFO,
                        format="%(levelname)s: %(message)s")

    # The model to use.
    model_id = "amazon.titan-text-express-v1"

    # The ID and version of the guardrail.
    guardrail_id = "Change to your guardrail ID"
    guardrail_version = "DRAFT"

    # Configuration for the guardrail.
    guardrail_config = {
        "guardrailIdentifier": guardrail_id,
        "guardrailVersion": guardrail_version,
        "trace": "enabled",
        "streamProcessingMode" : "sync"
    }

    text = "Create a playlist of heavy metal songs."
  
    # The message for the model and the content that you want the guardrail to assess.
    messages = [
        {
            "role": "user",
            "content": [
                {
                    "text": text,
                },
                {
                    "guardContent": {
                        "text": {
                            "text": text
                        }
                    }
                }
            ]
        }
    ]

    try:
        bedrock_client = boto3.client(service_name='bedrock-runtime')

        stream_conversation(bedrock_client, model_id, messages,
                        guardrail_config)

    except ClientError as err:
        message = err.response['Error']['Message']
        logger.error("A client error occurred: %s", message)
        print("A client error occured: " +
              format(message))

    else:
        print(
            f"Finished streaming messages with model {model_id}.")


if __name__ == "__main__":
    main()