Incluir uma barreira de proteção com a API Converse

É possível usar uma barreira de proteção para proteger as aplicações de conversação criadas com a API Converse. Por exemplo, se você criar uma aplicação de chat com a API Converse, poderá usar uma barreira de proteção para bloquear conteúdo inadequado inserido pelo usuário e conteúdo inadequado gerado pelo modelo. Para obter informações sobre a API do Converse, consulte Realizar uma conversa com as operações de API Converse.

Chamar a API Converse com barreiras de proteção

Para usar uma barreira de proteção, inclua informações de configuração da barreira de proteção nas chamadas para as operações Converse ou ConverseStream (para obter respostas de streaming). Opcionalmente, é possível selecionar um conteúdo específico na mensagem que deseja que a barreira de proteção avalie. Para ter informações sobre os modelos que podem ser usados com barreiras de proteção e a API Converse, consulte Modelos compatíveis e recursos do modelo.

Configurar uma barreira de proteção para funcionar com a API Converse

Você especifica as informações de configuração da barreira de proteção no parâmetro de entrada guardrailConfig. A configuração inclui o ID e a versão da barreira de proteção que você deseja usar. Você também pode habilitar o rastreamento da barreira de proteção, que fornece informações sobre o conteúdo que a barreira de proteção bloqueou.

Com a operação de Converse, guardrailConfig é um objeto GuardrailConfiguration, conforme mostrado no exemplo a seguir.

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

Se você usar ConverseStream, passará um objeto GuardrailStreamConfiguration. Opcionalmente, é possível usar o campo streamProcessingMode para especificar que deseja que o modelo conclua a avaliação da barreira de proteção, antes de retornar fragmentos da resposta de streaming. Ou é possível fazer com que o modelo responda de forma assíncrona enquanto a barreira de proteção continua sua avaliação em segundo plano. Para obter mais informações, consulte Configurar o comportamento da resposta de streaming para filtrar o conteúdo.

Avaliar somente conteúdo específico em uma mensagem

Ao transmitir uma mensagem para um modelo, a barreira de proteção avalia o conteúdo da mensagem. Você também pode avaliar partes específicas de uma mensagem usando o campo guardContent (GuardrailConverseContentBlock).

Por exemplo, a barreira de proteção a seguir avalia somente o conteúdo no campo guardContent e não no restante da mensagem. Isso é útil para que a barreira de proteção avalie somente as mensagens mais recentes em uma conversa, conforme mostrado no exemplo a seguir.

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

Outro caso de uso de guardContent é fornecer contexto adicional para uma mensagem, sem que a barreira de proteção avalie esse contexto. No exemplo a seguir, a barreira de proteção avalia apenas "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."
                    }
                }
            }
        ]
    }
]

Se o conteúdo não estiver em um bloco guardContent, isso não significa necessariamente que ele não será avaliado. Esse comportamento depende das políticas de filtragem que a barreira de proteção usa.

O exemplo a seguir mostra dois blocos guardContent com verificações de base contextual (com base nos campos qualifiers). As verificações de base contextual na barreira de proteção avaliarão apenas o conteúdo desses blocos. No entanto, se a barreira de proteção também tiver um filtro de palavras que bloqueie a palavra “básicas”, o texto “Algumas informações básicas adicionais” ainda será avaliado, mesmo que não esteja em um bloco 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"]
                }
            }
        }
    ]
}]

Proteger um prompt do sistema enviado à API Converse

É possível usar barreiras de proteção com prompts do sistema que você envia à API Converse. Para proteger um prompt do sistema, especifique o campo guardContent (SystemContentBlock) no prompt do sistema que você passa para a API, conforme mostrado no exemplo a seguir.

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

Se você não fornecer o campo guardContent, a barreira de proteção não avaliará a mensagem do prompt do sistema.

Comportamento da barreira de proteção do prompt do sistema e da mensagem

A forma como a barreira de proteção avalia o campo guardContent se comporta de forma diferente entre os prompts do sistema e de mensagens que você passa na mensagem.

Processar a resposta ao usar a API Converse

Quando você chama a operação Converse, a barreira de proteção avalia a mensagem que você envia. Se a barreira de proteção detectar conteúdo bloqueado, acontecerá o seguinte:

A resposta parcial a seguir mostra o texto do conteúdo bloqueado e o rastreamento da avaliação da barreira de proteção. A barreira de proteção bloqueou o termo Heavy Metal na mensagem.

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

Exemplo de código para usar a API Converse com barreiras de proteção

Este exemplo mostra como proteger uma conversa com as operações Converse e ConverseStream. O exemplo mostra como impedir que um modelo crie uma playlist que inclui músicas do gênero heavy metal.

Converse

O código a seguir usa a barreira de proteção com a operação 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

O código a seguir usa a barreira de proteção com a operação 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()