Includi un guardrail con Converse API - Amazon Bedrock
Chiamare le Converse API con parapettiElaborazione della risposta quando si utilizza Converse APICodice di esempio per usare Converse con guardrail API

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Includi un guardrail con Converse API

Puoi usare un guardrail per proteggere le app di conversazione che crei con Converse. API Ad esempio, se crei un'app di chat con ConverseAPI, puoi utilizzare un guardrail per bloccare i contenuti inappropriati inseriti dall'utente e i contenuti inappropriati generati dal modello. Per informazioni su Converse, consulta. API Effettua una conversazione con le operazioni di Converse API

Chiamare le Converse API con parapetti

Per utilizzare un guardrail, includi le informazioni di configurazione del guardrail nelle chiamate alle Converse o ConverseStream(per le risposte in streaming) nelle operazioni. Facoltativamente, puoi selezionare contenuti specifici del messaggio che desideri vengano valutati dal guardrail. Per informazioni sui modelli utilizzabili con i guardrail e le Converse, consulta. API Modelli e caratteristiche del modello supportati

Configurazione del guardrail per funzionare con Converse API

Si specificano le informazioni di configurazione per il guardrail nel parametro di guardrailConfig input. La configurazione include l'ID e la versione del guardrail che si desidera utilizzare. Puoi anche abilitare il tracciamento per il guardrail, che fornisce informazioni sul contenuto bloccato dal guardrail.

Con l'Converseoperazione, guardrailConfig è un GuardrailConfigurationoggetto, come illustrato nell'esempio seguente.

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

Se lo usiConverseStream, passi un GuardrailStreamConfigurationoggetto. Facoltativamente, è possibile utilizzare il streamProcessingMode campo per specificare che si desidera che il modello completi la valutazione del guardrail, prima di restituire blocchi di risposta in streaming. In alternativa, potete fare in modo che il modello risponda in modo asincrono mentre il guardrail continua la sua valutazione in background. Per ulteriori informazioni, consulta Configura il comportamento di risposta in streaming per filtrare i contenuti.

Proteggere un messaggio per valutare i contenuti dannosi utilizzando APIs

Quando si passa un messaggio (Message) a un modello, il guardrail valuta il contenuto del messaggio. Facoltativamente, puoi proteggere il contenuto selezionato nel messaggio specificando il campo (). guardContent GuardrailConverseContentBlock Il guardrail valuta solo il contenuto del guardContent campo e non il resto del messaggio. Ciò è utile per fare in modo che il guardrail valuti solo la maggior parte dei messaggi in 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 uso è fornire un contesto aggiuntivo per un messaggio, senza che il guardrail valuti quel contesto aggiuntivo. 

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

L'uso del guardContent campo è analogo all'utilizzo dei tag di input con InvokeModele. InvokeModelWithResponseStream Per ulteriori informazioni, consulta Applica tag all'input dell'utente per filtrare i contenuti.

Protezione di un prompt di sistema inviato a Converse API

Puoi usare i guardrail con i prompt di sistema che invii a Converse. API Per proteggere un prompt di sistema, specifica il campo guardContent (SystemContentBlock) nel prompt di sistema che passi aAPI, come mostrato nell'esempio seguente.

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

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

Comportamento del guardrail del messaggio e del prompt del sistema

Il modo in cui il guardContent campo guardrail valuta si comporta in modo diverso tra i prompt di sistema e i messaggi trasmessi nel messaggio.

Il prompt di sistema ha il blocco Guardrail Il prompt di sistema non ha il blocco Guardrail

I messaggi hanno il blocco Guardrail

Sistema: Guardrail esamina il contenuto del blocco Guardrail

Messaggi: Guardrail esamina il contenuto del blocco Guardrail

Sistema: Guardrail non indaga su nulla

Messaggi: Guardrail esamina i contenuti nel blocco Guardrail

I messaggi non hanno il blocco Guardrail

Sistema: Guardrail analizza il contenuto del blocco Guardrail

Messaggi: Guardrail indaga su tutto

Sistema: Guardrail non indaga su nulla

Messaggi: Guardrail indaga su tutto

Elaborazione della risposta quando si utilizza Converse API

Quando richiami l'operazione Converse, il guardrail valuta il messaggio che invii. Se il guardrail rileva contenuti bloccati, accade quanto segue.

  • Il stopReason campo nella risposta è impostato su. guardrail_intervened

  • Se hai abilitato la traccia, la traccia è disponibile nel campo trace (ConverseTrace). ConConverseStream, la traccia si trova nei metadati (ConverseStreamMetadataEvent) restituiti dall'operazione.

  • Il testo del contenuto bloccato che hai configurato nel guardrail viene restituito nel campo output (ConverseOutput). Con ConverseStream il contenuto bloccato, il testo viene inserito nel messaggio in streaming.

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

Codice di esempio per usare Converse con guardrail API

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

Per proteggere una conversazione

  1. Crea un guardrail seguendo le istruzioni inCrea un guardrail. Nel passaggio 6a, inserisci le seguenti informazioni per creare un argomento negato:

    • Nome: inserisci Heavy metal.

    • Definizione per argomento: inserisci Evita di menzionare canzoni che appartengono al genere musicale heavy metal.

    • Aggiungi frasi di esempio: entra Crea una playlist di canzoni heavy metal.

    Nel passaggio 9, inserisci quanto segue:

    • Messaggi visualizzati per le richieste bloccate: inserisci Mi dispiace, non posso rispondere a domande sulla musica heavy metal.

    • Messaggi per risposte bloccate: inserisci Scusa, il modello ha generato una risposta che menzionava la musica heavy metal.

    È possibile configurare altre opzioni di guardrail, ma non è necessario per questo esempio.

  2. Crea una versione del guardrail seguendo le istruzioni riportate in. Crea una versione di un guardrail

  3. Nei seguenti esempi di codice (Converse e ConverseStream), imposta le seguenti variabili:

    • guardrail_id— L'ID del guardrail che hai creato nel passaggio 1.

    • guardrail_version— La versione del guardrail che hai creato nel passaggio 2.

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

  4. Esegui gli esempi di codice. L'output dovrebbe mostrare la valutazione del guardrail e il messaggio Text: Sorry, I can't answer questions about heavy metal music. di output. La valutazione dell'input del guardrail mostra che il modello ha rilevato il termine metallo pesante nel messaggio di input.

  5. (Facoltativo) Verifica che il guardrail blocchi il testo inappropriato generato dal modello modificando il valore di Elenca tutti i generi di text musica rock. . Esegui nuovamente gli esempi. Dovresti vedere una valutazione dell'output nella risposta.

Converse

Il codice seguente utilizza il guardrail con l'Converseoperazione.

# 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

Il codice seguente utilizza il guardrail con l'ConverseStreamoperazione.

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