Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.

So fügen Sie der Converse-API einen Integritätsschutz hinzu

Sie können einen Integritätsschutz verwenden, um Konversations-Apps zu schützen, die Sie mit der Converse-API erstellen. Wenn Sie beispielsweise eine Chat-Anwendung mit der Converse-API erstellen, können Sie einen Integritätsschutz verwenden, um vom Benutzer eingegebene unangemessene Inhalte und vom Modell generierte unangemessene Inhalte zu blockieren. Informationen über die Converse-API finden Sie unter Führen einer Konversation mit den Converse-API-Operationen.

Rufen Sie die Converse-API mit dem Integritätsschutz auf

Um eine Guardrail zu verwenden, fügen Sie Konfigurationsinformationen für die Guardrail in Aufrufe der Converse oder ConverseStream(für Streaming-Antworten) Operationen ein. Optional können Sie bestimmte Inhalte in der Nachricht auswählen, die vom Integritätsschutz ausgewertet werden sollen. Informationen zu den Modellen, die Sie mit dem Integritätsschutz und der Converse-API verwenden können, finden Sie unter Unterstützte Modelle und Modellfeatures.

So konfigurieren Sie einen Integritätsschutz so, dass er mit der Converse-API funktioniert

Sie geben Informationen zur Konfiguration des Integritätsschutzes im Eingabeparameter guardrailConfig an. Die Konfiguration umfasst die ID und die Version des Integritätsschutzes, den Sie verwenden möchten. Sie können die Ablaufverfolgung auch für den Integritätsschutz aktivieren, wodurch Informationen über den Inhalt bereitgestellt werden, den der Integritätsschutz 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 Integritätsschutzbewertung abschließen soll, bevor Streaming-Antwortblöcke zurückgegeben werden. Oder Sie können das Modell asynchron antworten lassen, während der Integritätsschutz die Bewertung im Hintergrund fortsetzt. Weitere Informationen finden Sie unter So konfigurieren Sie das Streaming-Antwortverhalten bei der Inhaltsfilterung.

So werten Sie nur bestimmte Inhalte in einer Nachricht aus

Wenn Sie eine Nachricht an ein Model weitergeben, wertet Ihr Integritätsschutz den Inhalt der Nachricht aus. Sie können auch bestimmte Teile einer Nachricht bewerten, indem Sie das Feld guardContent (GuardrailConverseContentBlock) verwenden.

Beispielsweise wertet der folgende Integritätsschutz nur der Inhalt im Feld guardContent und nicht den Rest der Nachricht aus. Dies ist nützlich, wenn der Integritätsschutz nur die neueste Nachricht einer Konversation auswerten soll, 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."
                    }
                }
            }
        ]
    }
]

Ein weiterer Anwendungsfall für guardContent ist die Bereitstellung von zusätzlichem Kontext für eine Nachricht, ohne dass Ihr Integritätsschutz diesen Kontext auswertet. Im folgenden Beispiel wertet der Integritätsschutz lediglich "Create a playlist of heavy metal songs" aus und ignoriert "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."
                    }
                }
            }
        ]
    }
]

Wenn sich der Inhalt nicht in einem guardContent-Block befindet, bedeutet das nicht unbedingt, dass er nicht ausgewertet wird. Dieses Verhalten hängt davon ab, welche Filterrichtlinien der Integritätsschutz verwendet.

Das folgende Beispiel zeigt zwei guardContent-Blöcke mit kontextuellen Begründungsprüfungen (auf Basis der qualifiers-Felder). Bei den kontextuellen Begründungsprüfungen im Integritätsschutz wird nur der Inhalt dieser Blöcke ausgewertet. Wenn der Integritätsschutz jedoch auch über einen Wortfilter verfügt, der das Wort „Hintergrund“ blockiert, dann wird der Text „Einige zusätzliche Hintergrundinformationen.“ trotzdem ausgewertet, auch wenn er sich nicht in einem guardContent-Block befindet.

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

So schützen Sie einen an die Converse-API gesendeten System-Prompt

Sie können den Integritätsschutz mit System-Prompts verwenden, die Sie an die Converse-API senden. Um eine Systemaufforderung zu schützen, geben Sie das Feld guardContent (SystemContentBlock) in der Systemaufforderung an, die Sie an die API übergeben, wie im folgenden Beispiel gezeigt.

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

Wenn Sie das guardContent-Feld nicht angeben, bewertet der Integritätsschutz den System-Prompt nicht.

Verhalten des Integritätsschutzes in der Meldung und im System-Prompt

Das Verhalten des Integritätsschutzes bei der Bewertung des Felds guardContent ist bei System-Prompts und Nachrichten, die Sie in der Nachricht weitergeben, unterschiedlich.

So verarbeiten Sie die Antwort bei Verwendung der Converse-API

Wenn Sie die Converse-Operation aufrufen, wertet der Integritätsschutz die von Ihnen gesendete Nachricht aus. Wenn der Integritätsschutz blockierte Inhalte erkennt, passiert Folgendes:

Die folgende Teilantwort zeigt den blockierten Inhaltstext und die Ablaufverfolgung aus der Integritätsschutzbewertung. Der Integritätsschutz hat den Begriff Heavy Metal 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"
                            }
                        ]
                    },
                    "invocationMetrics": {
                        "guardrailProcessingLatency": 240,
                        "usage": {
                            "topicPolicyUnits": 1,
                            "contentPolicyUnits": 0,
                            "wordPolicyUnits": 0,
                            "sensitiveInformationPolicyUnits": 0,
                            "sensitiveInformationPolicyFreeUnits": 0,
                            "contextualGroundingPolicyUnits": 0
                        },
                        "guardrailCoverage": {
                            "textCharacters": {
                                "guarded": 39,
                                "total": 72
                            }
                        }
                    }
                }
            }
        }
    }
}

Codebeispiel für die Verwendung der Converse-API mit dem Integritätsschutz

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

Converse

Der folgende Code verwendet Ihren Integritätsschutz 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 <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

Der folgende Code verwendet Ihren Integritätsschutz bei der ConverseStream-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 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()