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

Inclua uma grade de proteção com o Converse API

Você pode usar uma grade de proteção para proteger os aplicativos de conversação que você cria com o Converse. API Por exemplo, se você criar um aplicativo de bate-papo com o ConverseAPI, 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 o ConverseAPI, consulteConverse com as operações da Converse API.

Chamando o Converse API com grades 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, você pode selecionar conteúdo específico na mensagem que você 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 o ConverseAPI, consulte. Modelos e recursos do modelo compatíveis

Configurando o corrimão para funcionar com o Converse API

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 obter mais informações, consulte Configure o comportamento da resposta de streaming para filtrar o conteúdo.

Protegendo uma mensagem para avaliar o uso de conteúdo nocivo APIs

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

Protegendo um prompt do sistema enviado ao Converse API

Você pode usar grades de proteção com os avisos do sistema que você envia para o Converse. API Para proteger um prompt do sistema, especifique o campo guardContent (SystemContentBlock) no prompt do sistema que você passa para oAPI, 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.

Processando a resposta ao usar o Converse API

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.

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"
                            }
                        ]
                    },
                    "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 exemplo para usar o Converse API com grades de proteção

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.

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