As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

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 grade de proteção, você inclui informações de configuração da grade de proteção em chamadas para o Converse ou ConverseStream(para respostas de streaming) em operações. 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 Converse operação, guardrailConfig é um GuardrailConfigurationobjeto, conforme mostrado no exemplo a seguir.

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

Se você usarConverseStream, você passa um GuardrailStreamConfigurationobjeto. 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()