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. # Anwendungsfälle in Integritätsschutz für Amazon Bedrock Nachdem Sie einen Integritätsschutz erstellt haben, können Sie die folgenden Features anwenden: + [Modellinferenz](inference.md) – Wenden Sie einen Integritätsschutz auf eingereichte Prompts und generierte Antworten an, wenn Sie Inferenzen für ein Modell ausführen. + [Agenten](agents.md) – Ordnen Sie einem Agenten einen Integritätsschutz zu, um diesen auf die an den Agenten gesendeten Prompts und die von ihm zurückgegebenen Antworten anzuwenden. + [Wissensdatenbank](knowledge-base.md) – Wenden Sie einen Integritätsschutz an, wenn Sie eine Wissensdatenbank abfragen und Antworten daraus generieren. + [Flow](flows.md) – Fügen Sie einen Integritätsschutz zu einem Prompt- oder Wissensdatenbankknoten in einem Flow hinzu, um ihn auf Eingaben und Ausgaben dieser Knoten anzuwenden. In der folgenden Tabelle wird beschrieben, wie Sie mithilfe der AWS-Managementkonsole oder der Amazon Bedrock API eine Leitplanke für jede dieser Funktionen hinzufügen können. **** | Anwendungsfall | Konsole | API | | --- | --- | --- | | Modellinferenz | Wählen Sie den Integritätsschutz aus, wenn Sie [einen Spielplatz verwenden](playgrounds.md). | Geben Sie dies in der Kopfzeile einer [InvokeModelWithResponseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModelWithResponseStream.html)OR-Anfrage an [InvokeModel](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModel.html)oder fügen Sie es in das guardrailConfig Feld im Hauptteil einer [Converse](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Converse.html) - oder Anfrage ein. [ConverseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseStream.html) | | Zuordnen zu einem Agenten | Wenn Sie den Agenten [erstellen oder aktualisieren](agents-build-modify.md), geben Sie dies im Abschnitt Integritätsschutzdetails des Agent Builders an. | Fügen Sie ein guardrailConfiguration-Feld im Text einer [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_CreateAgent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_CreateAgent.html)- oder [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_UpdateAgent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_UpdateAgent.html)-Anfrage ein. | | Verwendung bei der Abfrage einer Wissensdatenbank | Folgen Sie den Schritten im [Integritätsschutz](kb-test-config.md#kb-test-config-guardrails)-Abschnitt der Abfragekonfigurationen. Fügen Sie einen Integritätsschutz hinzu, wenn Sie Konfigurationen festlegen. | Fügen Sie ein guardrailConfiguration-Feld im Text einer [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_RetrieveAndGenerate.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_RetrieveAndGenerate.html)-Anfrage ein. | | So fügen Sie einen Prompt-Knoten in einen Flow ein | Wenn Sie einen Flow [erstellen](flows-create.md) oder [aktualisieren](flows-modify.md), wählen Sie den Prompt-Knoten aus und geben Sie den Integritätsschutz im Abschnitt Konfigurieren an. | Wenn Sie den Prompt-Knoten im nodes Feld einer [CreateFlow[UpdateFlow](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_UpdateFlow.html)](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_CreateFlow.html)Oder-Anfrage definieren, fügen Sie ein guardrailConfiguration Feld in die [PromptFlowNodeConfiguration](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_PromptFlowNodeConfiguration.html)ein. | | So fügen Sie einen Wissensdatenbank-Knoten in einen Flow ein | Wenn Sie einen Flow [erstellen](flows-create.md) oder [aktualisieren](flows-modify.md), wählen Sie den Wissensdatenbank-Knoten aus und geben Sie den Integritätsschutz im Abschnitt Konfigurieren an. | Wenn Sie den Knotenpunkt der Wissensdatenbank im nodes Feld einer [CreateFlow[UpdateFlow](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_UpdateFlow.html)](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_CreateFlow.html)OR-Anfrage definieren, fügen Sie ein guardrailConfiguration Feld in den ein [KnowledgeBaseFlowNodeConfiguration](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_KnowledgeBaseFlowNodeConfiguration.html). | In diesem Abschnitt wird die Verwendung eines Integritätsschutzes mit Modellinferenz und der Amazon-Bedrock-API behandelt. Sie können die Basis-Inferenzoperationen ([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)) und die Converse API ([Converse](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Converse.html) und [ConverseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseStream.html)) verwenden. Bei beiden Operationssätzen können Sie einen Integritätsschutz mit synchroner und Streaming-Modellinferenz verwenden. Sie können auch Benutzereingaben selektiv auswerten und das Verhalten der Streaming-Antwort konfigurieren. **Topics** + [So verwenden Sie Ihren Integritätsschutz mit Inferenzoperationen zur Bewertung von Benutzereingaben](guardrails-input-tagging-base-inference.md) + [Verwenden Sie die ApplyGuardrail API in Ihrer Anwendung](guardrails-use-independent-api.md) # So verwenden Sie Ihren Integritätsschutz mit Inferenzoperationen zur Bewertung von Benutzereingaben Sie können Leitplanken mit den Basisinferenzoperationen [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)(Streaming) verwenden. In diesem Abschnitt wird beschrieben, wie Sie Benutzereingaben selektiv auswerten und wie Sie das Verhalten von Streaming-Antworten konfigurieren. Beachten Sie, dass Sie bei Konversationsanwendungen dieselben Ergebnisse mit der [Converse-API](guardrails-use-converse-api.md) erzielen können. Beispiel: Ein Code, der die Grundlageninferenzoperationen aufruft; siehe [Senden Sie eine einzelne Aufforderung mit InvokeModel](inference-invoke.md). Für Informationen zur Verwendung eines Integritätsschutzes mit den Grundlageninferenzoperationen folgen Sie den Schritten auf der Registerkarte API für [So testen Sie Ihren Integritätsschutz](guardrails-test.md). **Topics** + [So wenden Sie Tags für die Inhaltsfilterung auf Benutzereingaben an](guardrails-tagging.md) + [So konfigurieren Sie das Streaming-Antwortverhalten bei der Inhaltsfilterung](guardrails-streaming.md) + [So fügen Sie der Converse-API einen Integritätsschutz hinzu](guardrails-use-converse-api.md) # So wenden Sie Tags für die Inhaltsfilterung auf Benutzereingaben an Eingabe-Tags ermöglichen Ihnen, bestimmte Inhalte innerhalb des Eingabetextes zu markieren, die vom Integritätsschutz verarbeitet werden sollen. Dies ist nützlich, wenn Sie den Integritätsschutz nur auf bestimmte Teile der Eingabe anwenden möchten, während andere Teile unverarbeitet bleiben sollen. Beispielsweise kann der Eingabe-Prompt in RAG-Anwendungen System-Prompts, Suchergebnisse aus vertrauenswürdigen Dokumentationsquellen und Benutzeranfragen enthalten. Da System-Prompts vom Entwickler bereitgestellt werden und Suchergebnisse aus vertrauenswürdigen Quellen stammen, benötigen Sie möglicherweise nur die Integritätsschutzbewertung für die Benutzeranfragen. In einem weiteren Beispiel kann der Eingabe-Prompt in Konversationsanwendungen System-Prompts, Gesprächsverläufe und die aktuelle Benutzereingabe enthalten. System-Prompts sind entwicklerspezifische Anweisungen, und Gesprächsverläufe enthalten historische Benutzereingaben sowie Modellantworten, die möglicherweise bereits vom Integritätsschutz ausgewertet wurden. In einem solchen Szenario möchten Sie möglicherweise nur die aktuelle Benutzereingabe auswerten. Durch die Verwendung von Eingabe-Tags können Sie besser steuern, welche Teile des Eingabe-Prompts vom Integritätsschutz verarbeitet und ausgewertet werden sollen. So stellen Sie sicher, dass Ihre Schutzmechanismen an Ihre Anwendungsfälle angepasst sind. Dies trägt außerdem zur Leistungsverbesserung und Kostensenkung bei, da Sie die Flexibilität haben, einen relativ kürzeren und relevanten Abschnitt der Eingabe auszuwerten, anstatt den gesamten Eingabe-Prompt. **Tag-Inhalte für den Integritätsschutz** Um Inhalte für die Verarbeitung durch den Integritätsschutz zu kennzeichnen, verwenden Sie das XML-Tag, das aus einer Kombination eines reservierten Präfixes und einem benutzerdefinierten `tagSuffix` besteht. Beispiel: ``` { "text": """ You are a helpful assistant. Here is some information about my account: - There are 10,543 objects in an S3 bucket. - There are no active EC2 instances. Based on the above, answer the following question: Question: How many objects do I have in my S3 bucket? ... Here are other user queries: How do I download files from my S3 bucket? """, "amazon-bedrock-guardrailConfig": { "tagSuffix": "xyz" } } ``` Im vorherigen Beispiel ist der Inhalt *„Wie viele Objekte habe ich in meinem S3-Bucket?“* und *„Wie lade ich Dateien aus meinem S3-Bucket herunter?“* mit dem Tag `` für die Verarbeitung durch den Integritätsschutz markiert. Beachten Sie, dass das Präfix `amazon-bedrock-guardrails-guardContent` für den Integritätsschutz reserviert ist. **Tag-Suffix** Das Tag-Suffix (`xyz` im obigen Beispiel) ist ein dynamischer Wert, den Sie in das `tagSuffix`-Feld unter `amazon-bedrock-guardrailConfig` eingeben müssen, um Eingabe-Tagging verwenden zu können. Es wird empfohlen, für jede Anfrage eine neue, zufällige Zeichenfolge als `tagSuffix` zu verwenden. So werden potenzielle Promptinjektions-Angriffe eingedämmt, da die Tag-Struktur unvorhersehbar wird. Ein statisches Tag kann dazu führen, dass ein bösartiger Benutzer das XML-Tag schließt und nach dem Tag-Abschluss schädlichen Inhalt anhängt, was zu einem *Injektionsangriff* führen würde. Es können lediglich alphanumerische Zeichenfolgen mit einer Länge zwischen 1 und 20 Zeichen (insgesamt) angegeben werden. Mit dem Beispielsuffix müssen Sie den gesamten Inhalt`xyz`, der geschützt werden soll, mithilfe der XML-Tags mit Ihrem Suffix einschließen:. `` *your content* `` Es empfiehlt sich, für jede Anfrage eine eindeutige dynamische ID als Tag-Suffix zu verwenden. **Mehrere Tags** Sie können dieselbe Tag-Struktur im Eingabetext mehrmals verwenden, um verschiedene Teile des Inhalts für die Integritätsschutzverarbeitung zu markieren. Eine Verschachtelung von Tags ist nicht zulässig. **Unmarkierte Inhalte** Inhalte außerhalb der Eingabe-Tags werden nicht vom Integritätsschutz verarbeitet. Auf diese Weise können Sie Anweisungen, Beispielkonversationen, Wissensdatenbanken oder andere Inhalte hinzufügen, die Sie für sicher halten und die nicht vom Integritätsschutz verarbeitet werden sollen. Wenn der Prompt keine Tags enthält, wird der gesamte Prompt vom Integritätsschutz verarbeitet. Die einzige Ausnahme sind [So erkennen Sie Prompt-Angriffe im Integritätsschutz für Amazon Bedrock](guardrails-prompt-attack.md)-Filter, für die Eingabe-Tags vorhanden sein müssen. # So konfigurieren Sie das Streaming-Antwortverhalten bei der Inhaltsfilterung Die [InvokeModelWithResponseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModelWithResponseStream.html)API gibt Daten in einem Streaming-Format zurück. Auf diese Weise können Sie blockweise auf Antworten, ohne auf das gesamte Ergebnis warten zu müssen. Bei der Verwendung des Integritätsschutzes für eine Streaming-Antwort gibt es zwei Betriebsmodi: synchron und asynchron. **Synchroner Modus** Im synchronen Standardmodus puffert der Integritätsschutz die konfigurierten Richtlinien und wendet sie auf einen oder mehrere Antwortblöcke an, bevor die Antwort an den Benutzer zurückgesendet wird. Der synchrone Verarbeitungsmodus führt zu einer gewissen Latenz bei den Antwortblöcken, da die Antwort verzögert wird, bis der Integritätsschutz-Scan abgeschlossen ist. Er bietet jedoch eine höhere Genauigkeit, da jeder Antwortblock vom Integritätsschutz gescannt wird, bevor er an den Benutzer gesendet wird. **Asynchroner Modus** Im asynchronen Modus sendet der Integritätsschutz die Antwortblöcke an den Benutzer, sobald sie verfügbar sind, und wendet gleichzeitig die konfigurierten Richtlinien asynchron im Hintergrund an. Der Vorteil besteht darin, dass Antwortblöcke sofort und ohne Auswirkungen auf die Latenz bereitgestellt werden. Antwortblöcke können jedoch unangemessene Inhalte aufweisen, bis der Integritätsschutz-Scan abgeschlossen ist. Sobald unangemessene Inhalte erkannt werden, werden nachfolgende Blöcke durch den Integritätsschutz blockiert. **Warnung** Integritätsschutz für Amazon Bedrock unterstützt nicht die Maskierung sensibler Informationen im asynchronen Modus. **Aktivieren des asynchronen Modus** Um den asynchronen Modus zu aktivieren, müssen Sie den `streamProcessingMode`-Parameter in das `amazon-bedrock-guardrailConfig`-Objekt Ihrer `InvokeModelWithResponseStream`-Anfrage aufnehmen: ``` { "amazon-bedrock-guardrailConfig": { "streamProcessingMode": "ASYNCHRONOUS" } } ``` Wenn Sie die Abwägungen zwischen den synchronen und asynchronen Modi verstehen, können Sie den geeigneten Modus entsprechend den Anforderungen Ihrer Anwendung an Latenz und Genauigkeit der Inhaltsmoderation auswählen. # 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() ``` ------ # Verwenden Sie die ApplyGuardrail API in Ihrer Anwendung Der Integritätsschutz wird verwendet, um Sicherheitsvorkehrungen für Ihre generativen KI-Anwendungen zu implementieren, die auf Ihre Anwendungsfälle zugeschnitten und auf Ihre verantwortungsvolle KI-Richtlinien abgestimmt sind. Mit dem Integritätsschutz können Sie abgelehnte Themen konfigurieren, schädliche Inhalte filtern und vertrauliche Informationen entfernen. Sie können die `ApplyGuardrail`-API verwenden, um jeden Text mit Ihrer vorkonfigurierten Integritätsschutz für Amazon Bedrock zu bewerten, ohne die Basismodelle aufrufen zu müssen. Zu den Features der `ApplyGuardrail`-API gehören: + **Inhaltsvalidierung** – Sie können jede beliebige Textein- oder -ausgabe an die `ApplyGuardrail`-API senden, um sie mit Ihren definierten Themenvermeidungsregeln, Inhaltsfiltern, PII-Detektoren und Wortblockierungslisten zu vergleichen. Sie können Benutzereingaben und FM-generierte Ausgaben unabhängig voneinander auswerten. + **Flexible Bereitstellung** – Sie können die `ApplyGuardrail`-API an einer beliebigen Stelle in Ihren Anwendungsablauf integrieren, um Daten zu validieren, bevor sie verarbeitet oder dem Benutzer als Ergebnisse zur Verfügung gestellt werden. Wenn Sie beispielsweise eine RAG-Anwendung verwenden, können Sie ab sofort die Benutzereingaben vor dem Abruf auswerten, anstatt bis zur endgültigen Antwortgenerierung warten zu müssen. + **Entkoppelt von Basismodellen** – Die `ApplyGuardrail`-API ist von den Basismodellen entkoppelt. Sie können den Integritätsschutz ab sofort verwenden, ohne Basismodelle aufzurufen. Sie können die Bewertungsergebnisse verwenden, um das Erlebnis in Ihrer generativen KI-Anwendung nach Ihren Vorstellungen auszulegen. **Topics** + [Rufen Sie Ihren ApplyGuardrail Anwendungsablauf ein](#guardrails-use-independent-api-call) + [Geben Sie die Leitplanke an, mit der Sie arbeiten möchten ApplyGuardrail](#guardrails-use-indepedent-api-call-configure) + [Beispielhafte Anwendungsfälle von ApplyGuardrail](#guardrails-use-independent-api-call-message) + [Geben Sie als ApplyGuardrail Antwort die vollständige Ausgabe zurück](#guardrails-use-return-full-assessment) ## Rufen Sie Ihren ApplyGuardrail Anwendungsablauf ein Die Anfrage ermöglicht Kunden, ihre zu schützenden Inhalte mithilfe eines definierten Integritätsschutzes weiterzugeben. Das Quellfeld sollte `INPUT` auf gesetzt sein, wenn der auszuwertende Inhalt von einem Benutzer stammt (in der Regel der Prompt für das LLM). Die Quelle sollte auf `OUTPUT` gesetzt sein, wenn der Integritätsschutz für die Modellausgabe durchgesetzt werden soll (in der Regel die LLM-Antwort). ## Geben Sie die Leitplanke an, mit der Sie arbeiten möchten ApplyGuardrail Bei der Verwendung von `ApplyGuardrail` geben Sie den `guardrailIdentifier` und die `guardrailVersion` des Integritätsschutzes an, 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. ------ #### [ ApplyGuardrail API request ] ``` POST /guardrail/{guardrailIdentifier}/version/{guardrailVersion}/apply HTTP/1.1 { "source": "INPUT" | "OUTPUT", "content": [{ "text": { "text": "string", } }, ] } ``` ------ #### [ ApplyGuardrail API response ] ``` { "usage": { "topicPolicyUnits": "integer", "contentPolicyUnits": "integer", "wordPolicyUnits": "integer", "sensitiveInformationPolicyUnits": "integer", "sensitiveInformationPolicyFreeUnits": "integer", "contextualGroundingPolicyUnits": "integer" }, "action": "GUARDRAIL_INTERVENED" | "NONE", "output": [ // if guardrail intervened and output is masked we return request in same format // with masking // if guardrail intervened and blocked, output is a single text with canned message // if guardrail did not intervene, output is empty array { "text": "string", }, ], "assessments": [{ "topicPolicy": { "topics": [{ "name": "string", "type": "DENY", "action": "BLOCKED", }] }, "contentPolicy": { "filters": [{ "type": "INSULTS | HATE | SEXUAL | VIOLENCE | MISCONDUCT |PROMPT_ATTACK", "confidence": "NONE" | "LOW" | "MEDIUM" | "HIGH", "filterStrength": "NONE" | "LOW" | "MEDIUM" | "HIGH", "action": "BLOCKED" }] }, "wordPolicy": { "customWords": [{ "match": "string", "action": "BLOCKED" }], "managedWordLists": [{ "match": "string", "type": "PROFANITY", "action": "BLOCKED" }] }, "sensitiveInformationPolicy": { "piiEntities": [{ // for all types see: https://docs.aws.amazon.com/bedrock/latest/APIReference/API_GuardrailPiiEntityConfig.html#bedrock-Type-GuardrailPiiEntityConfig-type "type": "ADDRESS" | "AGE" | ..., "match": "string", "action": "BLOCKED" | "ANONYMIZED" }], "regexes": [{ "name": "string", "regex": "string", "match": "string", "action": "BLOCKED" | "ANONYMIZED" }], "contextualGroundingPolicy": { "filters": [{ "type": "GROUNDING | RELEVANCE", "threshold": "double", "score": "double", "action": "BLOCKED | NONE" }] }, "invocationMetrics": { "guardrailProcessingLatency": "integer", "usage": { "topicPolicyUnits": "integer", "contentPolicyUnits": "integer", "wordPolicyUnits": "integer", "sensitiveInformationPolicyUnits": "integer", "sensitiveInformationPolicyFreeUnits": "integer", "contextualGroundingPolicyUnits": "integer" }, "guardrailCoverage": { "textCharacters": { "guarded":"integer", "total": "integer" } } } }, "guardrailCoverage": { "textCharacters": { "guarded": "integer", "total": "integer" } } ] } ``` ------ ## Beispielhafte Anwendungsfälle von ApplyGuardrail Die Ergebnisse der `ApplyGuardrail`-Anfrage hängen von der Aktion ab, die der Integritätsschutz für den übergebenen Inhalt ergriffen hat. + Wenn der Integritätsschutz eingegriffen hat, wo der Inhalt nur maskiert ist, wird der exakte Inhalt mit der Maskierung zurückgegeben. + Wenn der Integritätsschutz eingegriffen und den Anforderungsinhalt blockiert hat, wird das Ausgabefeld einen einzigen Text darstellen, nämlich die auf der Integritätsschutzrichtlinie basierende, vorgefertigte Nachricht. + Wenn keine Integritätsschutzaktion für den Anforderungsinhalt ergriffen wurde, ist das Ausgabe-Array leer. ------ #### [ Guardrails takes no action ] **Beispiel anfordern** ``` { "source": "OUTPUT", "content": [ "text": { "text": "Hi, my name is Zaid. Which car brand is reliable?" } ] } ``` **Beispiel für eine Antwort** ``` { "usage": { "topicPolicyUnitsProcessed": 1, "contentPolicyUnitsProcessed": 1, "wordPolicyUnitsProcessed": 0, "sensitiveInformationPolicyFreeUnits": 0 }, "action": "NONE", "outputs": [], "assessments": [{}] } ``` ------ #### [ Guardrails blocks content ] **Beispiel für eine Antwort** ``` { "usage": { "topicPolicyUnitsProcessed": 1, "contentPolicyUnitsProcessed": 1, "wordPolicyUnitsProcessed": 0, "sensitiveInformationPolicyFreeUnits": 0 }, "action": "GUARDRAIL_INTERVENED", "outputs": [{ "text": "Configured guardrail canned message (i.e., can't respond)" }], "assessments": [{ "topicPolicy": { "topics": [{ "name": "Cars", "type": "DENY", "action": "BLOCKED" }] }, "sensitiveInformationPolicy": { "piiEntities": [{ "type": "NAME", "match": "ZAID", "action": "ANONYMIZED" }], "regexes": [] } }] } ``` ------ #### [ Guardrails masks content ] **Beispiel für eine Antwort** Der Integritätsschutz greift ein und maskiert den Namen `ZAID`. ``` { "usage": { "topicPolicyUnitsProcessed": 1, "contentPolicyUnitsProcessed": 1, "wordPolicyUnitsProcessed": 0, "sensitiveInformationPolicyFreeUnits": 0 }, "action": "GUARDRAIL_INTERVENED", "outputs": [{ "text": "Hi, my name is {NAME}. Which car brand is reliable?" }, { "text": "Hello {NAME}, ABC Cars are reliable ..." } ], "assessments": [{ "sensitiveInformationPolicy": { "piiEntities": [{ "type": "NAME", "match": "ZAID", "action": "ANONYMIZED" }], "regexes": [] } }] } ``` ------ #### [ AWS CLI example ] **Eingabebeispiel** ``` aws bedrock-runtime apply-guardrail \ --cli-input-json '{ "guardrailIdentifier": "someGuardrailId", "guardrailVersion": "DRAFT", "source": "INPUT", "content": [ { "text": { "text": "How should I invest for my retirement? I want to be able to generate $5,000 a month" } } ] }' \ --region us-east-1 \ --output json ``` **Ausgabebeispiel (der Inhalt wird blockiert)** ``` { "usage": { "topicPolicyUnits": 1, "contentPolicyUnits": 1, "wordPolicyUnits": 1, "sensitiveInformationPolicyUnits": 1, "sensitiveInformationPolicyFreeUnits": 0 }, "action": "GUARDRAIL_INTERVENED", "outputs": [ { "text": "I apologize, but I am not able to provide fiduciary advice. =" } ], "assessments": [ { "topicPolicy": { "topics": [ { "name": "Fiduciary Advice", "type": "DENY", "action": "BLOCKED" } ] } } ] } ``` ------ ## Geben Sie als ApplyGuardrail Antwort die vollständige Ausgabe zurück Inhalte gelten als erkannt, wenn sie gegen Ihre Integritätsschutzkonfigurationen verstoßen. Beispielsweise gilt die kontextuelle Begründung als erkannt, wenn der Begründungs- oder Relevanzwert kleiner als der entsprechende Schwellenwert ist. Standardmäßig gibt der [ApplyGuardrail](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ApplyGuardrail.html)Vorgang in einer Antwort nur erkannten Inhalt zurück. Sie können das `outputScope`-Feld mit dem Wert `FULL` angeben, um die vollständige Ausgabe zurückzugeben. In diesem Fall würde die Antwort auch unerkannte Einträge für ein verbessertes Debugging einschließen. Sie können dasselbe Verhalten in den Operationen `Invoke` und `Converse` konfigurieren, indem Sie die Ablaufverfolgung auf die Option enabled full setzen. **Anmerkung** Der volle Ausgabebereich gilt nicht für Wortfilter oder Regex in Filtern für sensible Informationen. Er gilt jedoch für alle anderen Filterrichtlinien, einschließlich sensibler Informationen mit Filtern, die persönlich identifizierbare Informationen (PII) erkennen können.