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](conversation-inference.md). **Topics** + [ ## Rufen Sie die Converse-API mit dem Integritätsschutz auf ](#guardrails-use-converse-api-call) + [ ## So verarbeiten Sie die Antwort bei Verwendung der Converse-API ](#guardrails-use-converse-api-response) + [ ## Codebeispiel für die Verwendung der Converse-API mit dem Integritätsschutz ](#converse-api-guardrail-example) ## 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](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Converse.html) oder [ConverseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseStream.html)(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](conversation-inference-supported-models-features.md). **Topics** + [ ### So konfigurieren Sie einen Integritätsschutz so, dass er mit der Converse-API funktioniert ](#guardrails-use-converse-api-call-configure) + [ ### So werten Sie nur bestimmte Inhalte in einer Nachricht aus ](#guardrails-use-converse-api-call-message) + [ ### So schützen Sie einen an die Converse-API gesendeten System-Prompt ](#guardrails-use-converse-api-call-message-system-guard) + [ ### Verhalten des Integritätsschutzes in der Meldung und im System-Prompt ](#guardrails-use-converse-api-call-message-system-message-guard) ### 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 [GuardrailConfiguration](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_GuardrailConfiguration.html)Objekt, wie im folgenden Beispiel gezeigt. ``` { "guardrailIdentifier": "Guardrail ID", "guardrailVersion": "Guardrail version", "trace": "enabled" } ``` Wenn Sie verwenden`ConverseStream`, übergeben Sie ein [GuardrailStreamConfiguration](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_GuardrailStreamConfiguration.html)Objekt. 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](guardrails-streaming.md). ### So werten Sie nur bestimmte Inhalte in einer Nachricht aus Wenn Sie eine [Nachricht](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Message.html) 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](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_GuardrailConverseContentBlock.html)) verwenden. **Tipp** Die Verwendung des `guardContent` Felds ähnelt der Verwendung von Eingabe-Tags mit [InvokeModel](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModel.html)und [InvokeModelWithResponseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModelWithResponseStream.html). Weitere Informationen finden Sie unter [So wenden Sie Tags für die Inhaltsfilterung auf Benutzereingaben an](guardrails-tagging.md). 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](guardrails-contextual-grounding-check.md) (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](guardrails-content-filters.md) 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](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_SystemContentBlock.html)) 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. | | Der System-Prompt wird vom Integritätsschutz blockiert | Der System-Prompt wird nicht vom Integritätsschutz blockiert | | --- | --- | --- | | **Nachrichten mit einer Integritätsschutzblockierung** | System: Der Integritätsschutz untersucht Inhalte im Integritätsschutzblock Nachrichten: Der Integritätsschutz untersucht Inhalte im Integritätsschutzblock | System: Der Integritätsschutz stellt keine Untersuchung an Nachrichten: Der Integritätsschutz untersucht Inhalte im Integritätsschutzblock | | **Nachrichten mit keiner Integritätsschutzblockierung** | System: Der Integritätsschutz untersucht Inhalte im Integritätsschutzblock Nachrichten: Der Integritätsschutz untersucht alles | System: Der Integritätsschutz stellt keine Untersuchung an Nachrichten: Der Integritätsschutz untersucht alles | ## 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: + Das `stopReason`-Feld in der Antwort ist auf `guardrail_intervened` gesetzt. + Wenn Sie die Ablaufverfolgung aktiviert haben, ist die Ablaufverfolgung im Feld `trace` ([ConverseTrace](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseTrace.html)) verfügbar. Mit`ConverseStream`, die Ablaufverfolgung befindet sich in den Metadaten ([ConverseStreamMetadataEvent](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseStreamMetadataEvent.html)), 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](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseOutput.html)) zurückgegeben. Bei `ConverseStream` ist der blockierte Inhaltstext in der gestreamten Nachricht. 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. **So schützen Sie eine Konversation** 1. Erstellen Sie einen Integritätsschutz, indem Sie den Anweisungen unter [So erstellen Sie Ihren Integritätsschutz](guardrails-components.md) folgen. + **Name** – Geben Sie *Heavy Metal* ein. + **Themendefinition** – Geben Sie ein: *Das Erwähnen von Songs aus dem Musikgenre Heavy Metal vermeiden.* + **Beispielwortgruppen hinzufügen** – Geben Sie ein: *Erstellen einer Playlist mit Heavy-Metal-Songs.* Geben Sie in Schritt 9 Folgendes ein: + **Bei blockierten Prompts angezeigte Meldungen** – Geben Sie ein: *Tut mir leid, ich kann keine Fragen zu Heavy-Metal-Musik beantworten*. + **Bei blockierten Antworten angezeigte Meldungen** – Geben Sie ein: *Tut mir leid, das Modell hat eine Antwort generiert, in der Heavy-Metal-Musik erwähnt wurde*. Sie können noch weitere Integritätsschutzoptionen konfigurieren, jedoch sind diese bei diesem Beispiel nicht erforderlich. 1. Erstellen Sie eine Integritätsschutzversion, indem Sie den Anweisungen unter [So erstellen Sie eine Integritätsschutzversion](guardrails-versions-create.md) folgen. 1. Legen Sie in den folgenden Codebeispielen ([Converse](#converse-api-guardrail-example-converse) und [ConverseStream](#converse-api-guardrail-example-converse-stream)) die folgenden Variablen fest: + `guardrail_id` – Die ID des Integritätsschutzes, den Sie in Schritt 1 erstellt haben. + `guardrail_version` – Die Version des Integritätsschutzes, den Sie in Schritt 2 erstellt haben. + `text` – Verwenden Sie `Create a playlist of heavy metal songs.` 1. Führen Sie die Codebeispiele aus. Die Ausgabe sollte die Integritätsschutzbewertung und die Ausgabemeldung `Text: Sorry, I can't answer questions about heavy metal music.` enthalten. Die Bewertung der Integritätsschutzeingabe zeigt, dass das Modell den Begriff *Heavy Metal* in der Eingabemeldung erkannt hat. 1. (Optional) Testen Sie, ob der Integritätsschutz unangemessenen Text blockiert, den das Modell generiert, indem Sie den Wert von `text` auf *Alle Genres der Rockmusik auflisten* ändern. Führen Sie die Beispiele erneut aus. In der Antwort sollte eine Leistungsbeurteilung angezeigt werden. ------ #### [ 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 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 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() ``` ------