翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# Amazon Bedrock ガードレールのユースケース
ガードレールを作成したら、次の機能を使用して適用できます。
+ [モデル推論](inference.md) – モデルで推論を実行する際に、送信されたプロンプトと生成されたレスポンスにガードレールを適用します。
+ [エージェント](agents.md) – ガードレールをエージェントに関連付けて、エージェントに送信されたプロンプトとエージェントから返されたレスポンスに適用します。
+ [ナレッジベース](knowledge-base.md) – ナレッジベースをクエリし、そこからレスポンスを生成する際にガードレールを適用します。
+ [フロー](flows.md) – フロー内のプロンプトノードまたはナレッジベースノードにガードレールを追加して、これらのノードの入力と出力に適用します。
次の表は、 AWS マネジメントコンソール または Amazon Bedrock API を使用して、これらの各機能にガードレールを含める方法を示しています。
****
| ユースケース | コンソール | API |
| --- | --- | --- |
| モデル推論 | [プレイグラウンドを使用する](playgrounds.md)際に、ガードレールを選択する。 | [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](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) リクエストの本文の guardrailConfig フィールドに含めます。 |
| エージェントに関連付ける | エージェントを[作成または更新](agents-build-modify.md)する際に、エージェントビルダーの [ガードレールの詳細] セクションで指定します。 | [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_CreateAgent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_CreateAgent.html) リクエストまたは [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_UpdateAgent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_UpdateAgent.html) リクエストの本文に、guardrailConfiguration フィールドを含めます。 |
| ナレッジベースへのクエリの際に使用する | クエリ設定の [ガードレール](kb-test-config.md#kb-test-config-guardrails) セクションのステップに従います。設定時にガードレールを追加します。 | [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) リクエストの本文に、guardrailConfiguration フィールドを含めます。 |
| フローのプロンプトノードに含める | フローを[作成](flows-create.md)または[更新](flows-modify.md)する際に、[設定] セクションでプロンプトノードを選択し、ガードレールを指定します。 | [CreateFlow](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_CreateFlow.html) リクエストまたは [UpdateFlow](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_UpdateFlow.html) リクエストの nodes フィールドにプロンプトノードを定義する場合は、[PromptFlowNodeConfiguration](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_PromptFlowNodeConfiguration.html) に guardrailConfiguration フィールドを含めます。 |
| フローのナレッジベースノードに含める | フローを[作成](flows-create.md)または[更新](flows-modify.md)する際に、[設定] セクションでナレッジベースノードを選択し、ガードレールを指定します。 | [CreateFlow](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_CreateFlow.html) リクエストまたは [UpdateFlow](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_UpdateFlow.html) リクエストの nodes フィールドにナレッジベースノードを定義する場合は、[KnowledgeBaseFlowNodeConfiguration](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_KnowledgeBaseFlowNodeConfiguration.html) に guardrailConfiguration フィールドを含めます。 |
このセクションでは、モデル推論と Amazon Bedrock API でのガードレールの使用について説明します。基本の推論オペレーション ([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 ([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)) を使用できます。どちらのオペレーションセットでも、同期型とストリーミング型のモデル推論でガードレールを使用できます。また、ユーザー入力の一部を選択して評価し、ストリーミングレスポンスの動作を設定することもできます。
**Topics**
+ [推論オペレーションでガードレールを使用してユーザー入力を評価する](guardrails-input-tagging-base-inference.md)
+ [アプリケーションで ApplyGuardrail API を使用する](guardrails-use-independent-api.md)
# 推論オペレーションでガードレールを使用してユーザー入力を評価する
ガードレールは、基本の推論オペレーションである [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 で 1 つのプロンプトを送信する](inference-invoke.md)」を参照してください。基本の推論オペレーションでガードレールを使用する方法については、「[ガードレールをテストする](guardrails-test.md)」の「API」タブの手順に従ってください。
**Topics**
+ [ユーザー入力にタグを適用してコンテンツをフィルタリングする](guardrails-tagging.md)
+ [ストリーミングレスポンスの動作を設定してコンテンツをフィルタリングする](guardrails-streaming.md)
+ [Converse API にガードレールを含める](guardrails-use-converse-api.md)
# ユーザー入力にタグを適用してコンテンツをフィルタリングする
入力タグを使用して、入力テキスト内の特定のコンテンツをガードレールによる処理対象としてマークすることができます。入力の特定の部分にだけガードレールを適用し、他の部分は未処理のままにする場合に便利です。
例えば、RAG アプリケーションの入力プロンプトには、システムプロンプト、信頼できるドキュメントソースからの検索結果、ユーザークエリが含まれている場合があります。システムプロンプトは開発者、検索結果は信頼できるソースがそれぞれ提供元であるため、この場合、ユーザークエリだけをガードレールで評価すれば十分です。
別の例として、会話型アプリケーションの入力プロンプトに、システムプロンプト、会話履歴、現在のユーザー入力が含まれている場合があります。システムプロンプトは開発者固有の指示であり、会話履歴に含まれている過去のユーザー入力とモデルレスポンスは、既にガードレールで評価されている可能性があります。このような場合は、現在のユーザー入力のみを評価することができます。
入力タグを使用すれば、入力プロンプトのどの部分をガードレールで処理および評価するかを細かく制御し、ユースケースに合わせて保護対策をカスタマイズできます。また、入力プロンプト全体ではなく、入力の比較的短く、関連性の高い部分だけを柔軟に評価できるため、パフォーマンスの向上とコスト削減にも役立ちます。
**ガードレール用にコンテンツにタグを付ける**
ガードレールで処理するコンテンツにタグを付けるには、予約済みのプレフィックスとカスタムの `tagSuffix` を組み合わせた XML タグを使用します。例えば、次のようになります。
```
{
"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"
}
}
```
前の例では、コンテンツ「*How many objects do I have in my S3 bucket?*」と「*How do I download files from my S3 bucket?*」 に、タグ `` を使用して、ガードレール処理用のタグが付いています。プレフィックス `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 は、ストリーミング形式でデータを返します。そのため、結果が全部返されるまで待たなくても、チャンクごとにレスポンスを確認できます。ストリーミングレスポンスでガードレールを使用する場合、同期と非同期の 2 つの処理モードがあります。
**同期モード**
デフォルトの同期モードでは、ガードレールはバッファリングして、設定済みのポリシーを 1 つ以上の応答チャンクに適用してから、レスポンスをユーザに返送します。同期処理モードの場合、ガードレールによるスキャンが終わるまでレスポンスが遅れるため、応答チャンクにある程度のレイテンシーが生じます。ただし、すべての応答チャンクがガードレールによってスキャンされてからユーザーに送信されるため、精度は向上します。
**非同期モード**
非同期モードでは、ガードレールは応答チャンクが利用可能になり次第、ユーザーに送信し、設定済みポリシーはバックグラウンドで非同期に適用します。応答チャンクがレイテンシーへの影響なく即座に提供される点がメリットですが、ガードレールによるスキャンが完了するまでの間に、応答チャンクに不適切なコンテンツが含まれる可能性があります。不適切なコンテンツが特定され次第、後続のチャンクはガードレールによってブロックされます。
**警告**
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` のもう 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()
```
------
# アプリケーションで ApplyGuardrail API を使用する
ガードレールを使用して、責任ある AI ポリシーに則って、ユースケースに合わせてカスタマイズした保護対策を生成 AI アプリケーションに実装できます。ガードレールでは、拒否対象のトピックを設定し、有害なコンテンツをフィルターで除外して、機密情報を削除することができます。
`ApplyGuardrail` API を使用して、基盤モデルを呼び出すことなく、事前設定された Amazon Bedrock ガードレールを使用してテキストを評価できます。
`ApplyGuardrail` API の機能は次のとおりです。
+ **コンテンツ検証** – 任意のテキスト入力または出力を `ApplyGuardrail` API に送信して、定義済みのトピック回避ルール、コンテンツフィルター、PII ディテクター、単語ブロックリストと比較照合できます。ユーザーの入力と、FM が生成した出力を個別に評価できます。
+ **柔軟なデプロイ** - アプリケーションフローの任意の位置に `ApplyGuardrail` API を統合して、結果を処理またはユーザーに提示する前にデータを検証できます。例えば、RAG アプリケーションを使用している場合、最終レスポンスが生成されるまで待たずに、検索の実行前にユーザー入力を評価することができます。
+ **基盤モデルから分離** – `ApplyGuardrail` API は基盤モデルから分離されます。基盤モデルを呼び出すことなく、ガードレールを使用できます。評価結果を使用して、生成 AI アプリケーションのエクスペリエンスを設計できます。
**Topics**
+ [アプリケーションフローで ApplyGuardrail を呼び出す](#guardrails-use-independent-api-call)
+ [ApplyGuardrail で使用するガードレールを指定する](#guardrails-use-indepedent-api-call-configure)
+ [ApplyGuardrail のユースケースの例](#guardrails-use-independent-api-call-message)
+ [ApplyGuardrail レスポンスで完全な出力を返す](#guardrails-use-return-full-assessment)
## アプリケーションフローで ApplyGuardrail を呼び出す
このリクエストを使用して、定義済みのガードレールで保護すべきコンテンツをすべて渡すことができます。評価対象のコンテンツの提供元がユーザーである場合 (通常は LLM への入力プロンプト)、source フィールドを `INPUT` に設定する必要があります。モデル出力のガードレールを適用する必要がある場合 (通常は LLM レスポンス)、source は `OUTPUT` に設定する必要があります。
## ApplyGuardrail で使用するガードレールを指定する
`ApplyGuardrail` を使用する場合は、使用するガードレールの `guardrailVersion` と `guardrailIdentifier` を指定します。また、ガードレールのトレースを有効にして、ガードレールがブロックしたコンテンツに関する情報を得ることもできます。
------
#### [ 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"
}
}
]
}
```
------
## ApplyGuardrail のユースケースの例
`ApplyGuardrail` リクエストの出力は、渡されたコンテンツに対してガードレールが行ったアクションによって異なります。
+ ガードレールが介入し、コンテンツのマスク処理のみが行われた場合は、素のコンテンツがマスク処理を施した状態で返されます。
+ ガードレールが介入し、リクエストコンテンツをブロックした場合は、出力フィールドは 1 つのテキスト (ガードレール設定に基づく定型メッセージ) になります。
+ リクエストコンテンツに対してガードレールが何もアクションを実行しなかった場合、出力配列は空です。
------
#### [ Guardrails takes no action ]
**リクエストの例**
```
{
"source": "OUTPUT",
"content": [
"text": {
"text": "Hi, my name is Zaid. Which car brand is reliable?"
}
]
}
```
**レスポンスの例**
```
{
"usage": {
"topicPolicyUnitsProcessed": 1,
"contentPolicyUnitsProcessed": 1,
"wordPolicyUnitsProcessed": 0,
"sensitiveInformationPolicyFreeUnits": 0
},
"action": "NONE",
"outputs": [],
"assessments": [{}]
}
```
------
#### [ Guardrails blocks content ]
**レスポンスの例**
```
{
"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 ]
**レスポンスの例**
ガードレールは、名前 `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 ]
**入力例**
```
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
```
**出力例 (コンテンツをブロック)**
```
{
"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"
}
]
}
}
]
}
```
------
## ApplyGuardrail レスポンスで完全な出力を返す
コンテンツは、ガードレール設定に違反すると検出されたとみなされます。例えば、グラウンディングスコアまたは関連性スコアが対応するしきい値を下回っている場合、コンテキストグラウンディングは検出されたとみなされます。
デフォルトでは、[ApplyGuardrail](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ApplyGuardrail.html) オペレーションは検出されたコンテンツのみをレスポンスで返します。`outputScope` フィールドに `FULL` 値を指定すると、完全な出力を返すことができます。この場合、レスポンスには、検出されなかったエントリも拡張デバッグ用に含まれます。
トレースを有効フルオプションに設定することで、`Invoke` および `Converse` オペレーションで同じ動作を設定できます。
**注記**
フル出力スコープは、機密情報フィルターのワードフィルターや正規表現には適用されません。これは、個人を特定できる情報 (PII) を検出できるフィルターを含む機密情報など、その他すべてのフィルタリングポリシーに適用されます。