にガードレールを含める Converse API

ガードレールを使用して、Converse で作成した会話型アプリをガードできますAPI。たとえば、 でチャットアプリを作成する場合 Converse APIでは、ガードレールを使用して、ユーザーによって入力された不適切なコンテンツとモデルによって生成された不適切なコンテンツをブロックできます。の詳細については、Converse API、「」を参照してくださいとの会話を実行する Converse API オペレーション。

の呼び出し Converse API ガードレール付き

ガードレールを使用するには、Converse または ConverseStream (ストリーミングレスポンスの場合) オペレーションの呼び出しにガードレールの設定情報を含めます。必要に応じて、メッセージ内の特定のコンテンツをガードレールによる評価対象として選択できます。ガードレールおよび で使用できるモデルの詳細については、Converse API、「」を参照してくださいサポートされているモデルとモデルの機能。

トピック

• を使用するようにガードレールを設定する Converse API

• を使用して有害なコンテンツを評価するためのメッセージの保護 APIs

• に送信されるシステムプロンプトのガード Converse API

• メッセージとシステムプロンプトに対するガードレールの動作

を使用するようにガードレールを設定する Converse API

guardrailConfig 入力パラメータでガードレールの設定情報を指定します。設定情報には、使用するガードレールの ID やバージョンなどが該当します。また、ガードレールのトレースを有効にして、ガードレールがブロックしたコンテンツに関する情報を得ることもできます。

Converse オペレーションでは、次の例に示すように、 guardrailConfigは GuardrailConfiguration オブジェクトです。

{
        "guardrailIdentifier": "Guardrail ID",
        "guardrailVersion": "Guardrail version",
        "trace": "enabled"
}

を使用する場合はConverseStream、 GuardrailStreamConfiguration オブジェクトを渡します。必要に応じて streamProcessingMode フィールドを使用して、ガードレールの評価が完了してから、モデルがストリーミングレスポンスのチャンクを返すように指定できます。または、ガードレールの評価がバックグラウンドで継続している間に、モデルに非同期的に応答させることも可能です。詳細については、「ストリーミングレスポンスの動作を設定してコンテンツをフィルタリングする」を参照してください。

を使用して有害なコンテンツを評価するためのメッセージの保護 APIs

メッセージ (Message) をモデルに渡すと、ガードレールがそのメッセージの内容を評価します。必要に応じて、 guardContent (GuardrailConverseContentBlock) フィールドを指定して、メッセージ内の選択したコンテンツを保護できます。この場合、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."
                    }
                }
            }
        ]
    }
]

もう 1 つの用途は、メッセージの追加のコンテキストを提供し、その追加コンテキストをガードレールの評価の対象にしないようにすることです。

[
    {
        "role": "user",
        "content": [
            {
                "text": "Only answer with a list of songs."
            },
            {
                "guardContent": {
                    "text": {
                        "text": "Create a playlist of heavy metal songs."
                    }
                }
            }
        ]
    }
]

注記

guardContent フィールドの使用は、 InvokeModelおよび での入力タグの使用に似ていますInvokeModelWithResponseStream。詳細については、「ユーザー入力にタグを適用してコンテンツをフィルタリングする」を参照してください。

に送信されるシステムプロンプトのガード Converse API

ガードレールは、 に送信するシステムプロンプトで使用できます。Converse API。 システムプロンプトを保護するには、次の例に示すようにAPI、 に渡すシステムプロンプトで guardContent (SystemContentBlock) フィールドを指定します。

[
    {
        "guardContent": {
            "text": {
                "text": "Only respond with Welsh heavy metal songs."
            }
        }
    }
]
            

guardContent フィールドが指定されていない場合、ガードレールはシステムプロンプトのメッセージを評価しません。

メッセージとシステムプロンプトに対するガードレールの動作

ガードレールが guardContent フィールドをどのように評価するかは、メッセージで渡されたシステムプロンプトとメッセージに応じて異なります。

	システムプロンプトにガードレールブロックがある	システムプロンプトにガードレールブロックがない
メッセージにガードレールブロックがある	システム: ガードレールがガードレールブロック内のコンテンツを調べる メッセージ: ガードレールがガードレールブロック内のコンテンツを調べる	システム: ガードレールは何も調べない メッセージ: ガードレールがガードレールブロック内のコンテンツを調べる
メッセージにガードレールブロックがない	システム: ガードレールがガードレールブロック内のコンテンツを調べる メッセージ: ガードレールがすべてを調べる	システム: ガードレールは何も調べない メッセージ: ガードレールがすべてを調べる

を使用する際のレスポンスの処理 Converse API

Converse オペレーションを呼び出すと、送信したメッセージをガードレールが評価します。コンテンツがブロックされたことが検出された場合は、次のように処理されます。

• レスポンスの stopReason フィールドが guardrail_intervened に設定されます。

• トレースを有効にした場合、トレースは trace (ConverseTrace) フィールドで使用できます。ではConverseStream、トレースはオペレーションが返すメタデータ (ConverseStreamMetadataEvent) にあります。

• ガードレールで設定したブロックされたコンテンツテキストが output (ConverseOutput) フィールドで返されます。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. 「ガードレールを作成する」の手順に従ってガードレールを作成します。手順 6a では、次の情報を入力して拒否トピックを作成します。

   • 名前 – 「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」と入力します。

   他のガードレールオプションも設定できますが、この例では必須ではありません。

2. 「ガードレールのバージョンを作成する」の手順に従って、ガードレールのバージョンを作成します。

3. 次のコード例 (Converse および ConverseStream) で、次の変数を設定します。

   • guardrail_id – 手順 1 で作成したガードレールの ID。

   • guardrail_version – 手順 2 で作成したガードレールのバージョン。

   • text - Create a playlist of heavy metal songs. を使用します。

4. サンプルコードを実行します。出力には、ガードレールの評価と出力メッセージ Text: Sorry, I can't answer questions about heavy metal music. が表示されるはずです。ガードレールによる入力の評価から、モデルが入力メッセージ内で heavy metal という用語を検出したことがわかります。

5. （オプション) 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.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()