Use uma grade de proteção com a API Converse - Amazon Bedrock
Chamando a API ConverseProcessando a respostaCódigo de exemplo

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á.

Use uma grade de proteção com a API Converse

Você pode usar uma grade de proteção para proteger os aplicativos de conversação que você cria com a API Converse. Por exemplo, se você criar um aplicativo de bate-papo com a API Converse, poderá usar uma grade de proteção para bloquear conteúdo impróprio inserido pelo usuário e conteúdo impróprio gerado pelo modelo. Para obter informações sobre a API Converse, consulteUse a API Converse.

Chamando a API Converse

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, você pode selecionar conteúdo específico na mensagem que deseja que a grade de proteção avalie. Para obter informações sobre os modelos que você pode usar com grades de proteção e a API Converse, consulte. Modelos e recursos do modelo compatíveis

Configurando o corrimão

Você especifica as informações de configuração para a grade de proteção no parâmetro guardrailConfig de entrada. A configuração inclui o ID e a versão do guarda-corpo que você deseja usar. Você também pode ativar o rastreamento da grade de proteção, que fornece informações sobre o conteúdo que a grade 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, você pode usar o streamProcessingMode campo para especificar que deseja que o modelo conclua a avaliação do guardrail, antes de retornar partes da resposta de streaming. Ou você pode fazer com que o modelo responda de forma assíncrona enquanto a grade de proteção continua sua avaliação em segundo plano. Para ter mais informações, consulte Configurar o comportamento da resposta de streaming.

Protegendo uma mensagem

Quando você passa uma mensagem (Mensagem) para um modelo, a grade de proteção avalia o conteúdo da mensagem. Opcionalmente, você pode proteger o conteúdo selecionado na mensagem especificando o campo guardContent (GuardrailConverseContentBlock). O guardrail avalia somente o conteúdo no guardContent campo e não o resto da mensagem. Isso é útil para que o guardrail avalie somente a maioria das mensagens 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 uso é fornecer contexto adicional para uma mensagem, sem que a grade de proteção avalie esse 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 o guardContent campo é análogo ao uso de tags de entrada com InvokeModele. InvokeModelWithResponseStream Para ter mais informações, consulte Avalie seletivamente a entrada do usuário com tags.

Protegendo um prompt do sistema

Você pode usar grades de proteção com solicitações do sistema que você envia para a 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 guardContent campo, a grade de proteção não avaliará a mensagem de alerta do sistema.

Comportamento imediato da mensagem e do sistema

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

O prompt do sistema tem um bloco Guardrail O prompt do sistema não tem bloqueio Guardrail

As mensagens têm bloqueio de guardrail

Sistema: o Guardrail investiga o conteúdo no bloco do Guardrail

Mensagens: o Guardrail investiga o conteúdo no bloco do Guardrail

Sistema: o Guardrail não investiga nada

Mensagens: o Guardrail investiga o conteúdo no bloco do Guardrail

As mensagens não têm bloqueio de guardrail

Sistema: o Guardrail investiga o conteúdo no bloco do Guardrail

Mensagens: Guardrail investiga tudo

Sistema: o Guardrail não investiga nada

Mensagens: Guardrail investiga tudo

Processando a resposta

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

  • O stopReason campo na resposta está definido comoguardrail_intervened.

  • Se você ativou o rastreamento, o rastreamento estará disponível no campo trace (ConverseTrace). ComConverseStream, o rastreamento está nos metadados (ConverseStreamMetadataEvent) que a operação retorna.

  • O texto do conteúdo bloqueado que você configurou na grade de proteção é retornado no campo output (ConverseOutput). Com ConverseStream o conteúdo bloqueado, o texto está na mensagem transmitida.

A resposta parcial a seguir mostra o texto do conteúdo bloqueado e o traço da avaliação do guardrail. A grade 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"
                            }
                        ]
                    }
                }
            }
        }
    }
}

Código de exemplo

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

Para proteger uma conversa

  1. Crie uma grade de proteção seguindo as instruções em. Crie uma grade de proteção Na etapa 6a, insira as seguintes informações para criar um tópico negado:

    • Nome — Digite Heavy metal.

    • Definição de tópico - Digite Evite mencionar músicas do gênero musical heavy metal.

    • Adicione exemplos de frases — Digite Crie uma playlist de músicas de heavy metal.

    Na etapa 9, insira o seguinte:

    • Mensagens mostradas para solicitações bloqueadas — Digite Desculpe, não consigo responder perguntas sobre música heavy metal.

    • Mensagens para respostas bloqueadas — Digite Desculpe, o modelo gerou uma resposta que mencionava música heavy metal.

    Você pode configurar outras opções de guardrail, mas isso não é necessário neste exemplo.

  2. Crie uma versão do guarda-corpo seguindo as instruções em. Crie e gerencie uma versão de um guardrail

  3. Nos exemplos de código a seguir (Converse e ConverseStream), defina as seguintes variáveis:

    • guardrail_id— O ID da grade de proteção que você criou na etapa 1.

    • guardrail_version— A versão do guarda-corpo que você criou na etapa 2.

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

  4. Execute os exemplos de código. A saída deve exibir a avaliação da grade de proteção e a mensagem de saída. Text: Sorry, I can't answer questions about heavy metal music. A avaliação da entrada do guardrail mostra que o modelo detectou o termo heavy metal na mensagem de entrada.

  5. (Opcional) Teste se a grade de proteção bloqueia o texto impróprio que o modelo gera alterando o valor de text para Listar todos os gêneros de rock. . Execute os exemplos novamente. Você deve ver uma avaliação de saída na resposta.

Converse

O código a seguir usa sua grade de proteção com a Converse operação.

# 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

O código a seguir usa sua grade de proteção com a ConverseStream operação.

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