翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# 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` のもう 1 つのユースケースは、ガードレールがメッセージの追加コンテキストを評価せずに、そのコンテキストを提供することです。次の例では、ガードレールは `"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` フィールドに基づく) を含む 2 つの `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` の場合、コンテンツがブロックされた旨のテキストは、ストリーミングされるメッセージ内にあります。
以下は、レスポンスの一部分です。コンテンツがブロックされたことを知らせるテキストと、ガードレール評価のトレースが表示されています。ガードレールは、メッセージ内の *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 を使用する場合のコード例
この例では、`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 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()
```
------