Inclure un garde-corps dans l'API Converse - Amazon Bedrock
Appelez l'ConverseAPI avec des glissièresTraitement de la réponse lors de l'utilisation de l'ConverseAPIExemple de code pour l'utilisation de l'ConverseAPI avec des garde-corps

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.

Inclure un garde-corps dans 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 Converse API, 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 de plus amples informations sur l'API Converse, veuillez consulter Mener une conversation avec les opérations de l'ConverseAPI.

Appelez l'ConverseAPI avec des glissières

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

Configurer un garde-corps pour qu'il fonctionne avec l'API Converse

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 de plus amples informations, veuillez consulter Configurer le comportement de réponse au streaming pour filtrer le contenu.

Évaluer uniquement le contenu spécifique d'un message

Lorsque vous transmettez un message à un modèle, votre garde-corps évalue le contenu du message. Vous pouvez également évaluer des parties spécifiques d'un message en utilisant le champ guardContent (GuardrailConverseContentBlock).

Astuce

L'utilisation du guardContent champ est similaire à l'utilisation de balises de saisie avec InvokeModelet InvokeModelWithResponseStream. Pour de plus amples informations, veuillez consulter Appliquer des balises aux entrées utilisateur pour filtrer le contenu.

Par exemple, le garde-corps suivant évalue uniquement le contenu du guardContent champ et non le reste du message. Cela est utile pour que le garde-corps évalue uniquement le message le plus récent 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."
                    }
                }
            }
        ]
    }
]

Un autre cas d'utilisation guardContent consiste à fournir un contexte supplémentaire à un message sans que votre garde-fou n'évalue ce contexte. Dans l'exemple suivant, le garde-corps évalue "Create a playlist of heavy metal songs" et ignore uniquement le. "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 guardContent bloc, cela ne signifie pas nécessairement qu'il ne sera pas évalué. Ce comportement dépend des politiques de filtrage utilisées par le garde-corps.

L'exemple suivant montre deux guardContent blocs avec des vérifications contextuelles de mise à la terre (basées sur les qualifiers champs). Les vérifications contextuelles de mise à la terre effectuées dans le garde-corps évalueront uniquement le contenu de ces blocs. Toutefois, si le garde-corps comporte également un filtre de mots qui bloque le mot « arrière-plan », le texte « Quelques informations générales supplémentaires ». sera toujours évalué, même s'il ne figure pas dans un guardContent bloc.

[{
    "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'ConverseAPI

Vous pouvez utiliser des barrières de sécurité avec les instructions du 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 du garde-corps

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 comporte un garde-corps L'invite du système ne comporte pas de garde-corps

Les messages sont bloqués par un garde-corps

Système : Guardrail examine le contenu du bloc de garde-corps

Messages : Guardrail enquête sur le contenu d'un bloc de garde-corps

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

Messages : Guardrail enquête sur le contenu d'un bloc de garde-corps

Les messages ne sont pas protégés par un garde-corps

Système : Guardrail examine le contenu du bloc de garde-corps

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 lors de l'utilisation de l'ConverseAPI

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"
                            }
                        ]
                    },
                    "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'ConverseAPI avec des garde-corps

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 votre garde-corps

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