Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Incluez un garde-corps avec Converse API

Vous pouvez utiliser un garde-corps pour protéger les applications conversationnelles que vous créez avec les Converse. API Par exemple, si vous créez une application de chat avec ConverseAPI, vous pouvez utiliser un garde-fou pour bloquer le contenu inapproprié saisi par l'utilisateur et le contenu inapproprié généré par le modèle. Pour plus d'informations sur les ConverseAPI, consultezMener une conversation avec les opérations de Converse API.

Appelez les Converse API avec des rambardes

Pour utiliser un garde-corps, vous devez inclure les informations de configuration du garde-corps dans les appels aux Converse ou ConverseStream(pour les réponses en streaming) dans les opérations. Vous pouvez éventuellement sélectionner un contenu spécifique dans le message que vous souhaitez que le garde-corps évalue. Pour plus d'informations sur les modèles que vous pouvez utiliser avec les garde-corps et les ConverseAPI, consultez. Modèles pris en charge et caractéristiques des modèles

Configuration du garde-corps pour qu'il fonctionne avec Converse API

Vous spécifiez les informations de configuration du garde-corps dans le paramètre guardrailConfig d'entrée. La configuration inclut l'ID et la version du garde-corps que vous souhaitez utiliser. Vous pouvez également activer le suivi du garde-corps, qui fournit des informations sur le contenu bloqué par le garde-corps.

Avec l'Converseopération, guardrailConfig c'est un GuardrailConfigurationobjet, comme indiqué dans l'exemple suivant.

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

Si vous utilisezConverseStream, vous transmettez un GuardrailStreamConfigurationobjet. Vous pouvez éventuellement utiliser le streamProcessingMode champ pour spécifier que vous souhaitez que le modèle termine l'évaluation du garde-corps, avant de renvoyer des segments de réponse au streaming. Vous pouvez également faire en sorte que le modèle réponde de manière asynchrone pendant que le garde-corps poursuit son évaluation en arrière-plan. Pour de plus amples informations, veuillez consulter Configurer le comportement de réponse au streaming pour filtrer le contenu.

Protection d'un message pour évaluer le contenu préjudiciable en utilisant APIs

Lorsque vous transmettez un message (Message) à un modèle, le garde-corps évalue le contenu du message. Vous pouvez éventuellement protéger le contenu sélectionné dans le message en spécifiant le champ guardContent (GuardrailConverseContentBlock). Le garde-corps évalue uniquement le contenu du guardContent champ et non le reste du message. Cela est utile pour que le garde-corps n'évalue que le plus grand nombre de messages d'une conversation, comme le montre l'exemple suivant.

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

Une autre utilisation consiste à fournir un contexte supplémentaire à un message, sans que le garde-corps n'évalue ce contexte supplémentaire.

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

Protection d'une invite système envoyée à la Converse API

Vous pouvez utiliser des rambardes avec les instructions du système que vous envoyez aux Converse. API Pour protéger une invite système, spécifiez le champ guardContent (SystemContentBlock) dans l'invite système que vous transmettez àAPI, comme indiqué dans l'exemple suivant.

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

Si vous ne fournissez pas le guardContent champ, le garde-corps n'évalue pas le message d'invite du système.

Le message et le système indiquent le comportement de la rambarde

La façon dont le garde-corps évalue le guardContent champ se comporte différemment entre les invites du système et les messages que vous transmettez dans le message.

Traitement de la réponse lors de l'utilisation de la Converse API

Lorsque vous appelez l'opération Converse, le garde-corps évalue le message que vous envoyez. Si le garde-corps détecte un contenu bloqué, voici ce qui se passe.

La réponse partielle suivante montre le texte du contenu bloqué et la trace de l'évaluation du garde-corps. Le garde-corps a bloqué le terme « heavy metal » dans le message.

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

Exemple de code pour utiliser Converse API avec des rambardes

Cet exemple montre comment protéger une conversation à l'aide des ConverseStream opérations Converse et. L'exemple montre comment empêcher un mannequin de créer une liste de lecture contenant des chansons du genre heavy metal.

Converse

Le code suivant utilise votre garde-corps lors de l'Converseopération.

# 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

Le code suivant utilise votre garde-corps lors de l'ConverseStreamopération.

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