Verwende eine Leitplanke mit der Converse API für deine Chat-App

Du kannst eine Leitplanke verwenden, um Konversations-Apps zu schützen, die du mit dem Converse erstellst. API Wenn du beispielsweise eine Chat-App mit Converse erstellst, kannst du eine Leitplanke verwendenAPI, um unangemessene Inhalte, die vom Nutzer eingegeben wurden, und unangemessene Inhalte, die vom Model generiert wurden, zu blockieren. Informationen zur Converse API finden Sie unter. Führe ein Gespräch mit Converse

Die Converse mit Leitplanken API anrufen

Um eine Leitplanke zu verwenden, müssen Sie bei Aufrufen der Converse oder ConverseStreambei Vorgängen (bei Streaming-Antworten) die Konfigurationsinformationen für die Leitplanke angeben. Optional können Sie bestimmte Inhalte in der Nachricht auswählen, die von der Guardrail bewertet werden sollen. Informationen zu den Modellen, die Sie für Leitplanken und Converse verwenden können, finden Sie unter. API Unterstützte Modelle und Modellfunktionen

Themen

• Konfiguration der Leitplanke für die Verwendung mit Converse API
• Schutz einer Nachricht zur Bewertung schädlicher Inhalte mithilfe von APIs
• Bewachen einer Systemaufforderung, die an den Converse gesendet wird API
• Verhalten der Leitplanke in der Meldung und in der Systemaufforderung

Konfiguration der Leitplanke für die Verwendung mit Converse API

Sie geben die Konfigurationsinformationen für die Leitplanke im Eingabeparameter an. guardrailConfig Die Konfiguration umfasst die ID und die Version der Leitplanke, die Sie verwenden möchten. Sie können die Ablaufverfolgung auch für die Leitplanke aktivieren, wodurch Informationen über den Inhalt bereitgestellt werden, den die Leitplanke blockiert hat.

Bei der Converse Operation guardrailConfig handelt es sich um ein GuardrailConfigurationObjekt, wie im folgenden Beispiel gezeigt.

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

Wenn Sie verwendenConverseStream, übergeben Sie ein GuardrailStreamConfigurationObjekt. Optional können Sie das streamProcessingMode Feld verwenden, um anzugeben, dass das Modell die Guardrail-Assessment abschließen soll, bevor Streaming-Antwort-Chunks zurückgegeben werden. Oder Sie können das Modell asynchron reagieren lassen, während die Guardrail ihre Bewertung im Hintergrund fortsetzt. Weitere Informationen finden Sie unter Konfigurieren Sie das Streaming-Antwortverhalten, um Inhalte zu filtern.

Schutz einer Nachricht zur Bewertung schädlicher Inhalte mithilfe von APIs

Wenn Sie eine Nachricht (Message) an ein Model übergeben, bewertet die Leitplanke den Inhalt der Nachricht. Optional können Sie den ausgewählten Inhalt der Nachricht schützen, indem Sie das Feld guardContent () GuardrailConverseContentBlockangeben. Die Leitplanke bewertet nur den Inhalt des guardContent Felds und nicht den Rest der Nachricht. Dies ist nützlich, damit die Leitplanke nur die meisten Nachrichten in einer Konversation bewertet, wie im folgenden Beispiel gezeigt.

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

Eine weitere Möglichkeit besteht darin, zusätzlichen Kontext für eine Nachricht bereitzustellen, ohne dass die Leitplanke diesen zusätzlichen Kontext bewertet.

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

Anmerkung

Die Verwendung des guardContent Felds entspricht der Verwendung von Eingabe-Tags mit und. InvokeModelInvokeModelWithResponseStream Weitere Informationen finden Sie unter Wenden Sie Tags auf Benutzereingaben an, um Inhalte zu filtern.

Bewachen einer Systemaufforderung, die an den Converse gesendet wird API

Sie können Leitplanken mit Systemaufforderungen verwenden, die Sie an den Converse senden. API Um eine Systemaufforderung zu schützen, geben Sie das Feld guardContent (SystemContentBlock) in der Systemeingabeaufforderung an, die Sie an die übergebenAPI, wie im folgenden Beispiel gezeigt.

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

Wenn Sie das guardContent Feld nicht angeben, bewertet die Leitplanke die Systemaufforderungsmeldung nicht.

Verhalten der Leitplanke in der Meldung und in der Systemaufforderung

Die Art und Weise, wie die Schutzplanke guardContent das Feld bewertet, unterscheidet sich zwischen Systemaufforderungen und Meldungen, die Sie in der Nachricht weitergeben.

	In der Systemeingabeaufforderung ist die Schutzplanke blockiert	Die Systemeingabeaufforderung enthält keinen Guardrail-Block
Bei Nachrichten ist die Guardrail-Blockierung	System: Guardrail untersucht Inhalte im Guardrail-Block Nachrichten: Guardrail untersucht Inhalte im Guardrail-Block	System: Guardrail untersucht nichts Nachrichten: Guardrail untersucht Inhalte im Guardrail-Block
Für Nachrichten gibt es keinen Guardrail-Block	System: Guardrail untersucht Inhalte im Guardrail-Block Nachrichten: Guardrail untersucht alles	System: Guardrail untersucht nichts Nachrichten: Guardrail untersucht alles

Verarbeitung der Antwort bei Verwendung des Converse API

Wenn Sie die Converse Operation aufrufen, bewertet die Leitplanke die von Ihnen gesendete Nachricht. Wenn die Leitplanke blockierte Inhalte erkennt, passiert Folgendes.

• Das stopReason Feld in der Antwort ist auf eingestellt. guardrail_intervened

• Wenn Sie die Ablaufverfolgung aktiviert haben, ist die Ablaufverfolgung im Feld trace (ConverseTrace) verfügbar. MitConverseStream, die Ablaufverfolgung befindet sich in den Metadaten (ConverseStreamMetadataEvent), die von der Operation zurückgegeben werden.

• Der Text für blockierte Inhalte, den Sie in der Leitplanke konfiguriert haben, wird im Feld output (ConverseOutput) zurückgegeben. Bei ConverseStream dem blockierten Inhalt befindet sich der Text in der gestreamten Nachricht.

Die folgende Teilantwort zeigt den Text des blockierten Inhalts und den Trace aus der Guardrail-Bewertung. Die Leitplanke hat den Begriff Schwermetall in der Nachricht blockiert.

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

Beispielcode für die Verwendung von Converse mit Leitplanken API

Dieses Beispiel zeigt, wie man eine Konversation mit den ConverseStream Operationen Converse und überwacht. Das Beispiel zeigt, wie verhindert werden kann, dass ein Model eine Playlist erstellt, die Songs aus dem Heavy-Metal-Genre enthält.

Um eine Konversation zu schützen

1. Erstellen Sie eine Leitplanke, indem Sie den Anweisungen unter folgen. Erstellen Sie eine Leitplanke in der AWS Konsole Geben Sie in Schritt 6a die folgenden Informationen ein, um ein abgelehntes Thema zu erstellen:

   • Name — Geben Sie Heavy Metal ein.

   • Definition für das Thema — Geben Sie ein Vermeiden Sie es, Songs aus dem Heavy-Metal-Musikgenre zu erwähnen.

   • Beispielsätze hinzufügen — Enter Erstellen Sie eine Playlist mit Heavy-Metal-Songs.

   Geben Sie in Schritt 9 Folgendes ein:

   • Bei blockierten Eingabeaufforderungen werden Nachrichten angezeigt — Eingabe Entschuldigung, ich kann keine Fragen zu Heavy-Metal-Musik beantworten.

   • Nachrichten für blockierte Antworten — Geben Sie ein Es tut uns leid, das Modell hat eine Antwort generiert, in der Heavy-Metal-Musik erwähnt wurde.

   Sie können andere Leitplankenoptionen konfigurieren, dies ist für dieses Beispiel jedoch nicht erforderlich.

2. Erstellen Sie eine Version der Leitplanke, indem Sie den Anweisungen unter folgen. Eine Version einer Leitplanke erstellen

3. Legen Sie in den folgenden Codebeispielen (Converse und ConverseStream) die folgenden Variablen fest:

   • guardrail_id— Die ID der Leitplanke, die Sie in Schritt 1 erstellt haben.

   • guardrail_version— Die Version der Leitplanke, die Sie in Schritt 2 erstellt haben.

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

4. Führen Sie die Codebeispiele aus. Die Ausgabe sollte die Bewertung der Leitplanke und die Ausgabenachricht enthalten. Text: Sorry, I can't answer questions about heavy metal music. Die Bewertung der Leitplankeneingabe zeigt, dass das Modell den Begriff Schwermetall in der Eingabemeldung erkannt hat.

5. (Optional) Testen Sie, ob die Leitplanke unangemessenen Text blockiert, den das Modell generiert, indem Sie den Wert von auf Alle Genres der text Rockmusik auflisten ändern. . Führen Sie die Beispiele erneut aus. In der Antwort sollte eine Leistungsbeurteilung angezeigt werden.

Converse

Der folgende Code verwendet Ihre Leitplanke bei der Converse Operation.

# 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

Der folgende Code verwendet Ihre Leitplanke bei der Operation. 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()