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 l'API Converse

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

Chiama l'API con Converse guardrails

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 che è possibile utilizzare con i guardrail e l'ConverseAPI, consulta. Modelli e caratteristiche del modello supportati

Configura un guardrail per funzionare con l'API Converse

Le informazioni di configurazione di guardrai vengono specificate 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.

Valuta solo il contenuto specifico di un messaggio

Quando passi un messaggio a un modello, il guardrail valuta il contenuto del messaggio. Puoi anche valutare parti specifiche di un messaggio utilizzando il campo guardContent (GuardrailConverseContentBlock).

Ad esempio, il guardrail seguente valuta solo il contenuto del guardContent campo e non il resto del messaggio. Ciò è utile per fare in modo che il guardrail valuti solo 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 guardContent consiste nel fornire un contesto aggiuntivo per un messaggio senza che il guardrail valuti tale contesto. Nell'esempio seguente, il guardrail valuta e ignora solo il. "Create a playlist of heavy metal songs" "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 guardContent blocco, ciò non significa necessariamente che non verrà valutato. Questo comportamento dipende dai criteri di filtraggio utilizzati dal guardrail.

L'esempio seguente mostra due guardContent blocchi con controlli di messa a terra contestuali (basati sui campi). qualifiers I controlli contestuali di messa a terra nel guardrail valuteranno solo il contenuto di questi blocchi. Tuttavia, se il guardrail ha anche un filtro di parole che blocca la parola «sfondo», il testo «Alcune informazioni di base aggiuntive». verrà comunque valutato, anche se non si trova in un guardContent blocco.

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

Puoi usare guardrails con i prompt di sistema che invii all'API. Converse Per proteggere un prompt di sistema, specificate il campo guardContent (SystemContentBlock) nel prompt di sistema che passate all'API, 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.

Elaborazione della risposta quando si utilizza l'API Converse

Quando richiami l'operazione Converse, il guardrail valuta il messaggio che invii. Se il guardrail rileva contenuti bloccati, accade 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'ConverseAPI con guardrail

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

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