Includere un guardrail con l’API Converse

È possibile utilizzare un guardrail per proteggere le app conversazionali create con l’API Converse. Ad esempio, se viene creata un’app di chat con l’API Converse, è possibile utilizzare un guardrail per bloccare i contenuti inappropriati inseriti dall’utente e quelli generati dal modello. Per informazioni sull’API Converse, consultare Avvio di una conversazione con le operazioni dell’API Converse.

Chiamare l’API Converse con i guardrail

Per utilizzare un guardrail, è necessario includere le informazioni di configurazione del guardrail nelle chiamate alle operazioni Converse o ConverseStream (per le risposte in streaming). Facoltativamente, è possibile selezionare contenuti specifici nel messaggio che il guardrail deve valutare. Per informazioni sui modelli che è possibile utilizzare con i guardrail e l’API Converse, consultare Modelli e funzionalità del modello supportati.

Configurare un guardrail da utilizzare con l’API Converse

Specificare le informazioni di configurazione del guardrail nel parametro di input guardrailConfig. La configurazione include l’ID e la versione del guardrail da utilizzare. È possibile anche abilitare il tracciamento del guardrail, che fornisce informazioni sui contenuti bloccati dal guardrail.

Con l’operazione Converse, guardrailConfig è un oggetto GuardrailConfiguration, come mostrato nell’esempio seguente.

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

Se utilizzi ConverseStream, specifica un oggetto GuardrailStreamConfiguration. Facoltativamente, è possibile utilizzare il campo streamProcessingMode per specificare che il modello deve completare la valutazione del guardrail, prima di restituire blocchi di risposta in streaming. In alternativa, è possibile fare in modo che il modello risponda in modo asincrono mentre il guardrail continua la sua valutazione in background. Per ulteriori informazioni, consulta Configurare il comportamento delle risposta in streaming per filtrare i contenuti.

Valutare solo contenuti specifici di un messaggio

Se viene specificato un messaggio in un modello, il guardrail valuta il contenuto del messaggio. È possibile anche valutare parti specifiche di un messaggio utilizzando il campo guardContent (GuardrailConverseContentBlock).

Ad esempio, il seguente guardrail valuta solo il contenuto del campo guardContent e non il resto del messaggio. Ciò risulta utile quando si vuole che il guardrail valuti esclusivamente il messaggio più recente di una conversazione, come mostrato nell’esempio seguente.

[
    {
        "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 altro caso d’uso di guardContent consiste nel fornire contesto aggiuntivo per un messaggio senza che il guardrail lo valuti. Nell’esempio seguente, il guardrail valuta "Create a playlist of heavy metal songs" e ignora solo il "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."
                    }
                }
            }
        ]
    }
]

Se il contenuto non si trova in un blocco guardContent, non significa necessariamente che non verrà valutato. Questo comportamento dipende dalle policy dei filtri utilizzate dal guardrail.

L’esempio seguente mostra due blocchi guardContent con controlli di correlazione contestuale (basati sui campi qualifiers). I controlli di correlazione contestuale nel guardrail valuteranno solo il contenuto di questi blocchi. Tuttavia, se il guardrail contiene anche un filtro per parole che blocca la parola “sfondo”, il testo “Alcune informazioni di base aggiuntive.” verrà comunque valutato, anche se non si trova in un blocco 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"]
                }
            }
        }
    ]
}]

Protezione di un prompt di sistema inviato all’API Converse

È possibile utilizzare i guardrail con i prompt di sistema inviati all’API Converse. Per proteggere un prompt di sistema, specificare il campo guardContent (SystemContentBlock) nel prompt di sistema inviato all’API, come mostrato nell’esempio seguente.

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

Se non viene specificato il campo guardContent, il guardrail non valuta il messaggio del prompt di sistema.

Comportamento del guardrail per messaggi e prompt di sistema

Il modo in cui il guardrail valuta il campo guardContent è diverso a seconda che si tratti di prompt di sistema o di messaggi specificati nel messaggio.

Elaborazione della risposta quando si utilizza l’API Converse

Durante la chiamata dell’operazione Converse, il guardrail valuta il messaggio inviato. Se il guardrail rileva contenuti bloccati, si verifica quanto segue.

La seguente risposta parziale mostra il testo del contenuto bloccato e la traccia della valutazione del guardrail. Il guardrail ha bloccato il termine Heavy metal nel messaggio.

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

Esempio di codice per l’utilizzo dell’API Converse con i guardrail

Questo esempio mostra come proteggere una conversazione con le operazioni Converse e ConverseStream. L’esempio mostra come impedire a un modello di creare una playlist che include brani di genere heavy metal.

Converse

Il codice seguente utilizza il guardrail con l’operazione 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

Il codice seguente utilizza il guardrail con l’operazione 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()