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.

Intégration d’une barrière de protection à l’API Converse

Vous pouvez utiliser une barrière de protection pour protéger les applications conversationnelles que vous créez avec l’API Converse. Par exemple, si vous créez une application de chat avec l’API Converse, vous pouvez utiliser une barrière de protection pour bloquer le contenu inapproprié saisi par l’utilisateur et celui généré par le modèle. Pour plus d’informations sur l’API Converse, consultez Mener une conversation avec les opérations d’API Converse.

Appel de l’API Converse avec des barrières de protection

Pour utiliser une barrière de protection, vous devez inclure ses informations de configuration dans les appels aux opérations Converse ou ConverseStream (pour les réponses en streaming). Vous pouvez éventuellement sélectionner un contenu spécifique dans le message que vous souhaitez faire évaluer par la barrière de protection. Pour plus d’informations sur les modèles que vous pouvez utiliser avec les barrières de protection et l’API Converse, consultez Modèles et fonctionnalités des modèles pris en charge.

Configuration d’une barrière de protection fonctionnant avec l’API Converse

Vous spécifiez les informations de configuration de la barrière de protection dans le paramètre d’entrée guardrailConfig. La configuration inclut l’ID et la version de la barrière de protection que vous souhaitez utiliser. Vous pouvez également activer le traçage de la barrière de protection, qui fournit des informations sur le contenu qu’elle a bloqué.

Avec l’opération Converse, guardrailConfig est un objet GuardrailConfiguration, comme illustré dans l’exemple suivant.

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

Si vous utilisez ConverseStream, vous transmettez un objet GuardrailStreamConfiguration. Vous pouvez éventuellement utiliser le champ streamProcessingMode pour spécifier que vous souhaitez que le modèle termine l’évaluation par la barrière de protection avant de renvoyer les fragments de réponse en streaming. Vous pouvez également faire en sorte que le modèle réponde de manière asynchrone pendant que la barrière de protection poursuit son évaluation en arrière-plan. Pour plus d’informations, consultez Configuration du comportement des réponses en streaming pour filtrer le contenu.

Évaluation du contenu spécifique d’un message uniquement

Lorsque vous transmettez un message à un modèle, votre barrière de protection en évalue le contenu. Vous pouvez également évaluer des parties spécifiques d’un message en utilisant le champ guardContent (GuardrailConverseContentBlock).

Par exemple, la barrière de protection suivante évalue uniquement le contenu du champ guardContent et non le reste du message. Ceci est utile pour que la barrière de protection évalue uniquement le message le plus récent d’une conversation, comme illustré dans 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."
                    }
                }
            }
        ]
    }
]

Un autre cas d’utilisation de guardContent consiste à fournir un contexte supplémentaire pour un message sans que votre barrière de protection ne l’évalue. Dans l’exemple suivant, la barrière de protection évalue "Create a playlist of heavy metal songs" et ignore uniquement "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."
                    }
                }
            }
        ]
    }
]

Si le contenu ne figure pas dans un bloc guardContent, cela ne signifie pas nécessairement qu’il ne sera pas évalué. Ce comportement dépend des stratégies de filtrage utilisées par la barrière de protection.

L’exemple suivant montre deux blocs guardContent avec des contrôles d’ancrage contextuel (basés sur les champs qualifiers). Les contrôles d’ancrage contextuel dans la barrière de protection évaluent uniquement le contenu de ces blocs. Toutefois, si la barrière de protection comporte également un filtre de mots qui bloque le mot « background », le texte « Some additional background information. » sera toujours évalué, même s’il ne figure pas dans un bloc 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"]
                }
            }
        }
    ]
}]

Protection d’une invite système envoyée à l’API Converse

Vous pouvez utiliser des barrières de protection avec les invites système que vous envoyez à l’API Converse. Pour protéger une invite système, spécifiez guardContent (SystemContentBlock) dans l’invite système que vous transmettez à l’API, comme illustré dans l’exemple suivant.

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

Si vous ne renseignez pas le champ guardContent, la barrière de protection n’évalue pas le message d’invite système.

Message et comportement de la barrière de protection d’une invite système

La façon dont la barrière de protection évalue comment le champ guardContent se comporte diffère entre les invites système et les messages que vous transmettez dans le message.

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

Lorsque vous appelez l’opération Converse, la barrière de protection évalue le message que vous envoyez. Si la barrière de protection détecte du contenu bloqué, voici ce qui se passe.

La réponse partielle suivante montre le texte du contenu bloqué et la trace de l’évaluation de la barrière de protection. La barrière de protection 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 l’utilisation de l’API Converse avec des barrières de protection

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

Converse

Le code suivant utilise votre barrière de protection lors de l’opération 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

Le code suivant utilise votre barrière de protection lors de l’opération 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()