本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 使用具有推論操作的防護機制來評估使用者輸入
您可以搭配基礎推論操作 [InvokeModel](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModel.html) 和 [InvokeModelWithResponseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModelWithResponseStream.html) (串流) 來使用防護機制。本節涵蓋如何選擇性地評估使用者輸入，以及如何設定串流回應行為。請注意，對於對話式應用程式，您可以使用 [Converse API](guardrails-use-converse-api.md) 達成相同的結果。
如需呼叫基礎推論操作的範例程式碼，請參閱 [使用 InvokeModel 提交單一提示](inference-invoke.md)。如需有關搭配基礎推論操作使用防護機制的資訊，請遵循 [測試您的防護機制](guardrails-test.md) 的 API 索引標籤中的步驟。
**Topics**
+ [
# 將標籤套用至使用者輸入以篩選內容
](guardrails-tagging.md)
+ [
# 設定串流回應行為以篩選內容
](guardrails-streaming.md)
+ [
# 包含防護機制與 Converse API
](guardrails-use-converse-api.md)
# 將標籤套用至使用者輸入以篩選內容
輸入標籤可讓您在您要由防護機制處理的輸入文字中標記特定內容。當您想要將防護機制套用至輸入的特定部分，同時讓其他部分處於未處理狀態時，這會很有用。
例如，RAG 應用程式中的輸入提示可能包含系統提示、信任文件來源的搜尋結果，以及使用者查詢。由於系統提示是由開發人員提供，而搜尋結果來自信任的來源，您可能只需要對使用者查詢進行防護機制評估。
在另一個範例中，對話應用程式中的輸入提示可能包含系統提示、對話歷史記錄和目前的使用者輸入。系統提示是開發人員特定的指示，對話歷史記錄包含可能已由防護機制評估的歷史使用者輸入和模型回應。對於這類案例，您可能只需要評估目前的使用者輸入。
透過使用輸入標籤，您可以更妥善控制防護機制應處理及評估輸入提示的哪些部分，確保您的保護措施根據您的使用案例進行自訂。這也有助於改善效能及降低成本，因為您可以靈活地評估相對較短且相關的輸入區段，而不是整個輸入提示。
**標記防護機制的內容**
若要標記要處理的防護機制內容，請使用 XML 標籤，這是預留字首和自訂 `tagSuffix` 的組合。例如：
```
{
"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"
}
}
```
在上述範例中，內容「S3 儲存貯體中有多少物件？」**和「如何從 S3 儲存貯體下載檔案？」** 會針對防護機制處理加上標記以使用標籤 ``。請注意，防護機制會保留字首 `amazon-bedrock-guardrails-guardContent`。
**標籤尾碼**
標籤尾碼 (在上述範例中為 `xyz`) 是您必須在 `amazon-bedrock-guardrailConfig` 的 `tagSuffix` 欄位中提供才能使用輸入標記的動態值。建議針對每個請求使用新的隨機字串做為 `tagSuffix`。這有助於透過使標籤結構無法預測來緩解潛在的提示注入攻擊。靜態標籤可能會導致惡意使用者關閉 XML 標籤，並在標籤關閉後附加惡意內容，進而造成*注入攻擊*。您僅限於英數字元，長度介於 1 到 20 個字元之間。透過範例尾碼 `xyz`，您必須使用 XML 標籤與尾碼括住要保護的所有內容：``*您的內容*``。建議您為每個請求使用動態唯一識別符做為標籤尾碼。
**多個標籤**
您可以在輸入文字中使用相同的標籤結構多次，以標記內容的不同部分來進行防護機制處理。不允許巢狀化標籤。
**未標記的內容**
輸入標籤外部的內容不會透過防護機制處理。這可讓您包含指示、範例對話、知識庫，或您認為安全且不想透過防護機制處理的其他內容。如果輸入提示中沒有標籤，則防護機制會處理完整的提示。唯一的例外是需要有輸入標籤的 [使用 Amazon Bedrock 防護機制偵測提示攻擊](guardrails-prompt-attack.md) 篩選條件。
# 設定串流回應行為以篩選內容
[InvokeModelWithResponseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModelWithResponseStream.html) API 會以串流格式傳回資料。這可讓您存取區塊中的回應，而無需等待整個結果。搭配串流回應使用防護機制時，有兩種操作模式：同步和非同步。
**同步模式**
在預設同步模式中，防護機制會緩衝並套用設定的政策至一或多個回應區塊，再將回應傳回給使用者。同步處理模式會對回應區塊引入一些延遲，因為這表示回應會延遲到防護機制掃描完成為止。不過，它提供了更好的準確性，因為在傳送給使用者之前，防護機制會掃描每個回應區塊。
**非同步模式**
在非同步模式中，防護機制會在使用者可用時，立即將回應區塊傳送給使用者，同時在背景中非同步套用設定的政策。優點是立即提供回應區塊，而不會影響延遲，但回應區塊可能包含不適當的內容，直到防護機制掃描完成為止。一旦發現不適當的內容，後續區塊將遭防護機制封鎖。
**警告**
Amazon Bedrock 防護機制不支援以非同步模式遮罩敏感資訊。
**啟用非同步模式**
若要啟用非同步模式，您需要在 `InvokeModelWithResponseStream` 請求的 `amazon-bedrock-guardrailConfig` 物件中包含 `streamProcessingMode` 參數：
```
{
"amazon-bedrock-guardrailConfig": {
"streamProcessingMode": "ASYNCHRONOUS"
}
}
```
您可以透過了解同步和非同步模式之間的權衡，根據您應用程式對延遲和內容管制準確性的需求，選擇適當的模式。
# 包含防護機制與 Converse API
您可以使用防護機制來保護您使用 Converse API 建立的對話式應用程式。例如，如果您使用 Converse API 建立聊天應用程式，可以使用防護機制來封鎖使用者輸入的不適當內容，以及模型產生的不適當內容。如需 Converse API 的相關資訊，請參閱 [與 Converse API 操作進行對話](conversation-inference.md)。
**Topics**
+ [
## 使用防護機制呼叫 Converse API
](#guardrails-use-converse-api-call)
+ [
## 使用 Converse API 時處理回應
](#guardrails-use-converse-api-response)
+ [
## 搭配防護機制使用 Converse API 的程式碼範例
](#converse-api-guardrail-example)
## 使用防護機制呼叫 Converse API
若要使用防護機制，請在呼叫 [Converse](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Converse.html) 或 [ConverseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseStream.html) (用於串流回應) 操作時，包含防護機制的組態資訊。或者，您可以在您希望防護機制評估的訊息中選取特定內容。如需可與防護機制和 Converse API 搭配使用之模型的相關資訊，請參閱 [支援的模型和模型功能](conversation-inference-supported-models-features.md)。
**Topics**
+ [
### 設定防護機制以使用 Converse API
](#guardrails-use-converse-api-call-configure)
+ [
### 僅評估訊息中的特定內容
](#guardrails-use-converse-api-call-message)
+ [
### 保護傳送至 Converse API 的系統提示
](#guardrails-use-converse-api-call-message-system-guard)
+ [
### 訊息和系統提示防護機制行為
](#guardrails-use-converse-api-call-message-system-message-guard)
### 設定防護機制以使用 Converse API
您可以在 `guardrailConfig` 輸入參數中指定防護機制組態資訊。組態包含您要使用的防護機制 ID 和版本。您也可以啟用防護機制的追蹤，提供防護機制封鎖內容的相關資訊。
使用 `Converse` 操作時，`guardrailConfig` 是 [GuardrailConfiguration](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_GuardrailConfiguration.html) 物件，如下列範例所示。
```
{
"guardrailIdentifier": "Guardrail ID",
"guardrailVersion": "Guardrail version",
"trace": "enabled"
}
```
如果您使用 `ConverseStream`，則會傳遞 [GuardrailStreamConfiguration](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_GuardrailStreamConfiguration.html) 物件。或者，您可以使用 `streamProcessingMode` 欄位指定您希望模型在傳回串流回應區塊之前完成防護機制評估。或者，您可以讓模型以非同步方式回應，同時防護機制在背景繼續其評估。如需詳細資訊，請參閱[設定串流回應行為以篩選內容](guardrails-streaming.md)。
### 僅評估訊息中的特定內容
當您將[訊息](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Message.html)傳遞至模型時，防護機制會評估訊息中的內容。您也可以使用 `guardContent` ([GuardrailConverseContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_GuardrailConverseContentBlock.html)) 欄位來評估訊息的特定部分。
**提示**
使用 `guardContent` 欄位類似於搭配 [InvokeModel](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModel.html) 和 [InvokeModelWithResponseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModelWithResponseStream.html) 使用輸入標籤。如需詳細資訊，請參閱[將標籤套用至使用者輸入以篩選內容](guardrails-tagging.md)。
例如，下列防護機制只會評估 `guardContent` 欄位中的內容，而不會評估訊息的其餘部分。這對於讓防護機制僅評估對話中的最新訊息很有用，如下列範例所示。
```
[
{
"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."
}
}
}
]
}
]
```
`guardContent` 的另一個使用案例是為訊息提供額外的內容，而您的防護機制不會評估該內容。在下列範例中，防護機制只會評估 `"Create a playlist of heavy metal songs"` 而忽略 `"Only answer with a list of songs"`。
```
messages = [
{
"role": "user",
"content": [
{
"text": "Only answer with a list of songs."
},
{
"guardContent": {
"text": {
"text": "Create a playlist of heavy metal songs."
}
}
}
]
}
]
```
如果內容不在 `guardContent` 區塊中，這不一定表示不會進行評估。此行為取決於防護機制使用的篩選政策。
下列範例顯示具有[情境依據檢查](guardrails-contextual-grounding-check.md) (根據 `qualifiers` 欄位) 的兩個 `guardContent` 區塊。防護機制中的情境依據檢查只會評估這些區塊中的內容。不過，如果防護機制也有封鎖「背景」一詞的[字詞篩選條件](guardrails-content-filters.md)，則「某些額外的背景資訊。」文字 仍會進行評估，即使字詞不在 `guardContent` 區塊中也一樣。
```
[{
"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"]
}
}
}
]
}]
```
### 保護傳送至 Converse API 的系統提示
您可以將防護機制與傳送至 Converse API 的系統提示搭配使用。若要保護系統提示，請在您傳遞給 API 的系統提示中指定 `guardContent` ([SystemContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_SystemContentBlock.html)) 欄位，如下列範例所示。
```
[
{
"guardContent": {
"text": {
"text": "Only respond with Welsh heavy metal songs."
}
}
}
]
```
如果您未提供 `guardContent` 欄位，則防護機制不會評估系統提示訊息。
### 訊息和系統提示防護機制行為
防護機制如何評估您在訊息中傳遞的系統提示與訊息之間的 `guardContent` 欄位行為不同。
| | 系統提示具有防護機制區塊 | 系統提示沒有防護機制區塊 |
| --- | --- | --- |
| **訊息具有防護機制區塊** | 系統：防護機制會調查防護機制區塊中的內容 訊息：防護機制會調查防護機制區塊中的內容 | 系統：防護機制不會調查任何內容 訊息：防護機制會調查防護機制區塊中的內容 |
| **訊息沒有防護機制區塊** | 系統：防護機制會調查防護機制區塊中的內容 訊息：防護機制會調查所有內容 | 系統：防護機制不會調查任何內容 訊息：防護機制會調查所有內容 |
## 使用 Converse API 時處理回應
當您呼叫 Converse 操作時，防護機制會評估您傳送的訊息。如果防護機制偵測到封鎖的內容，會發生下列情況。
+ 回應中的 `stopReason` 欄位會設為 `guardrail_intervened`。
+ 如果您啟用追蹤，則追蹤可在 `trace` ([ConverseTrace](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseTrace.html)) 欄位中使用。使用 `ConverseStream`，追蹤位於操作傳回的中繼資料 ([ConverseStreamMetadataEvent](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseStreamMetadataEvent.html)) 中。
+ 您在防護機制中設定的封鎖內容文字會在 `output` ([ConverseOutput](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseOutput.html)) 欄位中傳回。使用 `ConverseStream`，封鎖的內容文字位於串流訊息中。
下列部分回應顯示封鎖的內容文字，以及來自防護機制評估的追蹤。防護機制已封鎖訊息中的*重金屬*一詞。
```
{
"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
}
}
}
}
}
}
}
}
```
## 搭配防護機制使用 Converse API 的程式碼範例
此範例說明如何保護與 `Converse` 和 `ConverseStream` 操作的對話。此範例示範如何防止模型建立播放清單，其中包含重金屬類型的歌曲。
**保護對話**
1. 遵循 [建立防護機制](guardrails-components.md) 中的指示建立防護機制。
+ **名稱** – 輸入*重金屬*。
+ **主題的定義** – 輸入*避免提及來自重金屬音樂類型的歌曲。*
+ **新增範例片語** – 輸入*建立重金屬歌曲的播放清單。*
在步驟 9 中，輸入下列項目：
+ **針對封鎖提示顯示的訊息** – 輸入*抱歉，我無法回答有關重金屬音樂的問題。*
+ **用於封鎖回應的訊息** – 輸入*抱歉，模型產生提及重金屬音樂的答案。*
您可以設定其他防護機制選項，但此範例不需要。
1. 遵循 [建立防護機制的版本](guardrails-versions-create.md) 中的指示建立防護機制的版本。
1. 在下列程式碼範例 ([Converse](#converse-api-guardrail-example-converse) 和 [ConverseStream](#converse-api-guardrail-example-converse-stream)) 中，設定下列變數：
+ `guardrail_id` – 您在步驟 1 中建立的防護機制 ID。
+ `guardrail_version` – 您在步驟 2 中建立的防護機制版本。
+ `text` – 使用 `Create a playlist of heavy metal songs.`
1. 執行程式碼範例。輸出應該會顯示防護機制評估和輸出訊息 `Text: Sorry, I can't answer questions about heavy metal music.`。防護機制輸入評估顯示模型在輸入訊息中偵測到*重金屬*一詞。
1. (選用) 透過將 `text` 的值變更為*列出所有類型的搖滾音樂*，測試防護機制封鎖模型產生的不適當文字。再次執行範例。您應該會在回應中看到輸出評估。
------
#### [ Converse ]
下列程式碼會將防護機制與 `Converse` 操作搭配使用。
```
# 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 ]
下列程式碼會將防護機制與 `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()
```
------