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.

Incluye una barandilla 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 una Converse API, puede usar una barrera 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 Mantén una conversación con las operaciones de la Converse API.

Llama a la Converse API con barandas

Para usar una barandilla, debes incluir la información de configuración de la barandilla en las llamadas a las operaciones de Converse o ConverseStream(para las respuestas de streaming). Si lo desea, puede seleccionar un contenido específico en el mensaje que desee que evalúe la barrera de protección. Para obtener información sobre los modelos que puedes usar con las barandillas y la API, consulta. Converse Modelos y características del modelo compatibles

Configure una barandilla para que funcione con la API Converse

La información de configuración de la barandilla 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 Converse operación, guardrailConfig es un GuardrailConfigurationobjeto, como se muestra en el siguiente ejemplo.

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

Si lo usasConverseStream, pasas un GuardrailStreamConfigurationobjeto. 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.

Evalúa solo el contenido específico de un mensaje

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

Por ejemplo, la siguiente barandilla evalúa solo el contenido del guardContent campo y no el resto del mensaje. Esto resulta útil para que la barandilla evalúe solo el mensaje más reciente de una conversación, 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 guardContent es proporcionar contexto adicional a un mensaje sin que la barandilla evalúe ese contexto. En el siguiente ejemplo, la barandilla solo evalúa "Create a playlist of heavy metal songs" e ignora el. "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 guardContent bloque, eso no significa necesariamente que no se vaya a evaluar. Este comportamiento depende de las políticas de filtrado que utilice la barandilla.

El siguiente ejemplo muestra dos guardContent bloques con comprobaciones contextuales de base (basadas en los campos). qualifiers Las comprobaciones contextuales de la barandilla solo evaluarán el contenido de estos bloques. Sin embargo, si la barandilla también tiene un filtro de palabras que bloquea la palabra «fondo», el texto «Información de fondo adicional». se seguirá evaluando, aunque no esté en un guardContent bloque.

[{
    "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"]
                }
            }
        }
    ]
}]

Proteger un mensaje del sistema enviado a la Converse API

Puedes usar barandillas con las indicaciones del sistema que envíes a la API. Converse Para proteger un indicador del sistema, especifica el campo guardContent (SystemContentBlock) en el mensaje del sistema que pasas a la API, 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.

Procesar 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 Converse API con barandas

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()