Incluye una barandilla con Converse API - Amazon Bedrock
Llamar a las Converse API con barandasProcesar la respuesta cuando se usa la Converse APICódigo de ejemplo para usar Converse con barandas API

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 Converse API

Puedes usar una barandilla para proteger las aplicaciones de conversación que crees con las Converse. API Por ejemplo, si creas una aplicación de chat con ConverseAPI, puedes usar una barrera para bloquear el contenido inapropiado introducido por el usuario y el contenido inapropiado generado por el modelo. Para obtener información sobre las ConverseAPI, consulte. Mantén una conversación con las operaciones de Converse API

Llamar a las Converse API con barandas

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

Configuración de la barandilla para que funcione con Converse API

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 barandilla que desea utilizar. También puede habilitar el rastreo de la barandilla, que proporciona información sobre el contenido que la barandilla ha bloqueado.

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 streamProcessingMode campo para especificar que desea que el modelo complete la evaluación de la barandilla 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 barandilla continúa su evaluación en segundo plano. Para obtener más información, consulte Configurar el comportamiento de respuesta de streaming para filtrar el contenido.

Proteger un mensaje para evaluar el uso de contenido dañino APIs

Al pasar un mensaje (Mensaje) a un modelo, la barandilla evalúa el contenido del mensaje. Si lo desea, puede proteger el contenido seleccionado del mensaje especificando el campo guardContent () GuardrailConverseContentBlock. La 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 la mayoría de los mensajes 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 uso es proporcionar un contexto adicional para un mensaje, sin que la barandilla evalúe ese contexto adicional. 

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

Usar el guardContent campo es análogo a usar etiquetas de entrada con y. InvokeModelInvokeModelWithResponseStream Para obtener más información, consulte Aplicar etiquetas a la entrada del usuario para filtrar el contenido.

Proteger un mensaje del sistema enviado a la Converse API

Puedes usar barandillas con las indicaciones del sistema que envíes a la Converse. API Para proteger un indicador del sistema, especifique el campo guardContent (SystemContentBlock) en el indicador del sistema que va a enviar alAPI, como se muestra en el siguiente ejemplo.

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

Si no proporciona el guardContent campo, la barandilla no evaluará el mensaje de aviso del sistema.

El mensaje y el sistema indican el comportamiento de la barandilla

La forma en que la barandilla evalúa el guardContent campo se comporta de forma diferente entre las indicaciones del sistema y los mensajes que se transmiten en el mensaje.

El indicador del sistema tiene el bloqueo Guardrail El indicador del sistema no tiene el bloqueo Guardrail

Los mensajes tienen el bloqueo Guardrail

Sistema: Guardrail investiga el contenido del bloque Guardrail

Mensajes: Guardrail investiga el contenido del bloque Guardrail

Sistema: Guardrail no investiga nada

Mensajes: Guardrail investiga el contenido del bloque Guardrail

Los mensajes no tienen el bloqueo Guardrail

Sistema: Guardrail investiga el contenido del bloque Guardrail

Mensajes: Guardrail lo investiga todo

Sistema: Guardrail no investiga nada

Mensajes: Guardrail lo investiga todo

Procesar la respuesta cuando se usa la Converse API

Cuando llamas a la operación Converse, la barandilla evalúa el mensaje que envías. Si la barandilla detecta contenido bloqueado, ocurre lo siguiente.

  • El stopReason campo de la respuesta está establecido en. guardrail_intervened

  • Si ha activado el rastreo, el rastreo estará disponible en el campo trace (ConverseTrace). ConConverseStream, el rastreo está en los metadatos (ConverseStreamMetadataEvent) que devuelve la operación.

  • El texto del contenido bloqueado que ha configurado en la barandilla se devuelve en el campo output (ConverseOutput). Con ConverseStream el contenido bloqueado, el texto aparece en el mensaje transmitido.

La siguiente respuesta parcial muestra el texto del contenido bloqueado y el rastro obtenido de la evaluación de la barandilla. La barandilla 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
                            }
                        }
                    }
                }
            }
        }
    }
}

Código de ejemplo para usar Converse con barandas API

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

Para proteger una conversación

  1. Cree una barandilla siguiendo las instrucciones que se indican en. Crea una barandilla En el paso 6a, introduzca la siguiente información para crear un tema denegado:

    • Nombre: introduzca Heavy metal.

    • Definición del tema: ingrese Evite mencionar canciones que sean del género musical heavy metal.

    • Agrega ejemplos de frases: ingresa Crear una lista de reproducción de canciones de heavy metal.

    En el paso 9, ingresa lo siguiente:

    • Se muestran los mensajes para las indicaciones bloqueadas: introduce Lo siento, no puedo responder a las preguntas sobre la música heavy metal.

    • Mensajes para respuestas bloqueadas: ingresa Lo sentimos, el modelo generó una respuesta que mencionaba música heavy metal.

    Puede configurar otras opciones de barandilla, pero no es obligatorio para este ejemplo.

  2. Cree una versión de la barandilla siguiendo las instrucciones de. Crea una versión de una barandilla

  3. En los siguientes ejemplos de código (Converse y ConverseStream), defina las siguientes variables:

    • guardrail_id— El ID de la barandilla que creó en el paso 1.

    • guardrail_version— La versión de la barandilla que creó en el paso 2.

    • text— Usa Create a playlist of heavy metal songs.

  4. Ejecute los ejemplos de código. El resultado debe mostrar la evaluación de la barandilla y el mensaje de salida. Text: Sorry, I can't answer questions about heavy metal music. La evaluación de la entrada de la barandilla muestra que el modelo detectó el término metal pesado en el mensaje de entrada.

  5. (Opcional) Compruebe que la barandilla bloquea el texto inapropiado que genera el modelo cambiando el valor de text a Listar todos los géneros de música rock. . Vuelva a ejecutar los ejemplos. Deberías ver una evaluación del resultado en la respuesta.

Converse

El siguiente código utiliza su barandilla en la Converse operación.

# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: Apache-2.0
"""
Shows how to use a guardrail with the Converse 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 barandilla 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()