本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 随附护栏 Converse API
<a name="guardrails-use-converse-api"></a>

您可以使用护栏来保护您通过 Converse API 创建的对话应用程序。例如，如果您通过 Converse API 创建聊天应用程序，则可以使用护栏来阻止用户输入的不当内容以及模型生成的不当内容。有关 Converse API 的信息，请参阅[使用匡威 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
<a name="guardrails-use-converse-api-call"></a>

要使用护栏，请在调用 C [onverse](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 配合使用的模型的信息，请参阅[模型概览](model-cards.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
<a name="guardrails-use-converse-api-call-configure"></a>

您需要在 `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)。

### 仅评估消息中的特定内容
<a name="guardrails-use-converse-api-call-message"></a>

当您将[消息](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` 字段中的内容，而不评估消息的其余部分。这有助于让护栏仅评测对话中最近的消息（如以下示例所示）。

**重要**  
一旦你在消息中的任何地方添加了`guardContent`方块，护栏就会*只*评估区块内的内容。`guardContent`所有其他未封装的内容块都将被完全跳过，并且不会由护栏进行评估。`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. \"Blinding Lights\" by The Weeknd\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
<a name="guardrails-use-converse-api-call-message-system-guard"></a>

您可以使用护栏来保护发送到 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` 字段，护栏不会评估系统提示消息。

### 护栏在保护消息和系统提示时的行为
<a name="guardrails-use-converse-api-call-message-system-message-guard"></a>

护栏在处理系统提示和您传递的消息时，评估 `guardContent` 字段的方式有会有所不同。


|  | 系统提示包含护栏块 | 系统提示不包含护栏块 | 
| --- | --- | --- | 
| **消息包含护栏块** | 系统：护栏调查护栏块中的内容<br />消息：护栏调查护栏块中的内容 | 系统：护栏不评估任何内容<br />消息：护栏调查护栏块中的内容 | 
| **消息不包含护栏块** | 系统：护栏调查护栏块中的内容<br />消息：护栏评估所有内容 | 系统：护栏不评估任何内容<br />消息：防护机制评估所有内容 | 

## 使用时处理响应 Converse API
<a name="guardrails-use-converse-api-response"></a>

当您调用 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`，被屏蔽的内容文本会显示在流式传输消息中。

以下提供了部分响应，展示了被屏蔽的内容文本和来自护栏评估的跟踪信息。护栏屏蔽了消息中的 *Heavy metal* 这一词汇。

```
{
    "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
<a name="converse-api-guardrail-example"></a>

以下示例展示了如何使用 `Converse` 和 `ConverseStream` 操作来保护对话，还展示了如何防止模型创建包含重金属歌曲的播放列表。

**保护对话**

1. 按照[创建护栏](guardrails-components.md)中的说明创建护栏。
   + **名称** – 输入 *Heavy metal*。
   + **主题定义** – 输入 *Avoid mentioning songs that are from the heavy metal genre of music*。
   + **添加示例短语** – 输入 *Create a playlist of heavy metal songs*。

   在步骤 9 中，输入以下内容：
   + **对于被屏蔽的提示，系统显示的消息** – 输入 *Sorry, I can't answer questions about heavy metal music*。
   + **对于被屏蔽的响应，系统显示的消息** – 输入 *Sorry, the model generated an answer that mentioned heavy metal music*。

   您可以配置其他护栏选项，但在本示例中不是必填项。

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.`。护栏输入评估表明，模型在输入消息中检测到了 *heavy metal* 这一词汇。

1. 通过将 `text` 的值改为 *List all genres of rock music.*，测试护栏能否屏蔽模型生成的不当文本内容。再次运行示例代码。您应该会在响应中看到输出评估。

------
#### [ 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 <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 ]

以下代码将您的护栏与 `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.nova-micro-v1:0"

    # 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()
```

------