Utiliser un garde-corps avec l'API Converse - Amazon Bedrock
Appel de l'API ConverseTraitement de la réponseExemple de code

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.

Utiliser un garde-corps avec l'API Converse

Vous pouvez utiliser un garde-corps 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 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 l'API Converse, consultezUtilisez la Converse API.

Appel de l'API Converse

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 l'API Converse, consultez. Modèles pris en charge et caractéristiques des modèles

Configuration du garde-corps

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 il s'agit d'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 plus d’informations, consultez Configurer le comportement de réponse au streaming.

Protéger un message

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

L'utilisation du guardContent champ est analogue à l'utilisation de balises de saisie avec InvokeModelet InvokeModelWithResponseStream. Pour plus d’informations, consultez Évaluez de manière sélective les entrées utilisateur à l'aide de balises.

Protection d'une invite du système

Vous pouvez utiliser des barrières de sécurité avec les instructions système que vous envoyez à l'API Converse. Pour protéger une invite système, spécifiez le champ guardContent (SystemContentBlock) dans l'invite système que vous transmettez à l'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.

L'invite du système contient un bloc de garde-corps L'invite système ne contient pas de bloc Guardrail

Les messages sont bloqués par Guardrail

Système : Guardrail examine le contenu du bloc Guardrail

Messages : Guardrail enquête sur le contenu du bloc Guardrail

Système : Guardrail n'enquête sur rien

Messages : Guardrail enquête sur le contenu du bloc Guardrail

Les messages ne sont pas bloqués par Guardrail

Système : Guardrail examine le contenu du bloc Guardrail

Messages : Guardrail enquête sur tout

Système : Guardrail n'enquête sur rien

Messages : Guardrail enquête sur tout

Traitement de la réponse

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.

  • Le stopReason champ de la réponse est défini surguardrail_intervened.

  • Si vous avez activé le suivi, celui-ci est disponible dans le champ trace (ConverseTrace). AvecConverseStream, la trace se trouve dans les métadonnées (ConverseStreamMetadataEvent) renvoyées par l'opération.

  • Le texte du contenu bloqué que vous avez configuré dans le garde-corps est renvoyé dans le champ output (ConverseOutput). Avec ConverseStream le contenu bloqué, le texte se trouve dans le message diffusé en continu.

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

Exemple de code

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.

Pour protéger une conversation

  1. Créez un garde-corps en suivant les instructions de. Créez un garde-corps À l'étape 6a, entrez les informations suivantes pour créer un sujet refusé :

    • Nom — Entrez Heavy Metal.

    • Définition du sujet — Entrez Évitez de mentionner des chansons issues du genre heavy metal.

    • Ajouter des exemples de phrases — Entrez Créez une playlist de chansons de heavy metal.

    À l'étape 9, entrez les informations suivantes :

    • Message affiché pour les invites bloquées — Entrez Désolé, je ne peux pas répondre aux questions sur la musique heavy metal.

    • Messagerie pour les réponses bloquées — Entrez Désolé, le modèle a généré une réponse mentionnant la musique heavy metal.

    Vous pouvez configurer d'autres options de garde-corps, mais cela n'est pas obligatoire dans cet exemple.

  2. Créez une version du garde-corps en suivant les instructions de. Création et gestion d'une version d'un garde-corps

  3. Dans les exemples de code suivants (Converse et ConverseStream), définissez les variables suivantes :

    • guardrail_id— L'identifiant du garde-corps que vous avez créé à l'étape 1.

    • guardrail_version— La version du garde-corps que vous avez créée à l'étape 2.

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

  4. Exécutez les exemples de code. La sortie doit afficher l'évaluation du garde-corps et le message de sortie. Text: Sorry, I can't answer questions about heavy metal music. L'évaluation des entrées du garde-corps montre que le modèle a détecté le terme « métal lourd » dans le message d'entrée.

  5. (Facultatif) Vérifiez que le garde-corps bloque le texte inapproprié généré par le modèle en modifiant la valeur de text pour répertorier tous les genres de musique rock. . Réexécutez les exemples. Vous devriez voir une évaluation des résultats dans la réponse.

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