Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

Sertakan pagar pembatas dengan API Converse

Anda dapat menggunakan pagar pembatas untuk menjaga aplikasi percakapan yang Anda buat dengan Converse API. Misalnya, jika Anda membuat aplikasi obrolan dengan Converse API, Anda dapat menggunakan pagar pembatas untuk memblokir konten yang tidak pantas yang dimasukkan oleh pengguna dan konten tidak pantas yang dihasilkan oleh model. Untuk informasi tentang Converse API, lihatMelakukan percakapan dengan operasi Converse API.

Panggil Converse API dengan pagar pembatas

Untuk menggunakan pagar pembatas, Anda menyertakan informasi konfigurasi untuk pagar pembatas dalam panggilan ke operasi Converse atau ConverseStream(untuk respons streaming). Secara opsional, Anda dapat memilih konten tertentu dalam pesan yang ingin dinilai pagar pembatas. Untuk informasi tentang model yang dapat Anda gunakan dengan pagar pembatas dan Converse API, lihat. Model dan fitur model yang didukung

Konfigurasikan pagar pembatas untuk bekerja dengan API Converse

Anda menentukan informasi konfigurasi guardrai dalam parameter guardrailConfig input. Konfigurasi mencakup ID dan versi pagar pembatas yang ingin Anda gunakan. Anda juga dapat mengaktifkan penelusuran untuk pagar pembatas, yang memberikan informasi tentang konten yang diblokir pagar pembatas.

Dengan Converse operasi, guardrailConfig adalah GuardrailConfigurationobjek, seperti yang ditunjukkan pada contoh berikut.

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

Jika Anda menggunakanConverseStream, Anda melewati GuardrailStreamConfigurationobjek. Secara opsional, Anda dapat menggunakan streamProcessingMode bidang untuk menentukan bahwa Anda ingin model menyelesaikan penilaian pagar pembatas, sebelum mengembalikan potongan respons streaming. Atau, Anda dapat meminta model merespons secara asinkron sementara pagar pembatas melanjutkan penilaiannya di latar belakang. Untuk informasi selengkapnya, lihat Konfigurasikan perilaku respons streaming untuk memfilter konten.

Mengevaluasi hanya konten tertentu dalam pesan

Saat Anda meneruskan Pesan ke model, pagar pembatas menilai konten dalam pesan. Anda juga dapat menilai bagian tertentu dari pesan dengan menggunakan bidang guardContent (GuardrailConverseContentBlock).

Misalnya, pagar pembatas berikut hanya mengevaluasi konten di guardContent lapangan dan bukan sisa pesan. Ini berguna untuk membuat pagar pembatas hanya menilai pesan terbaru dalam percakapan, seperti yang ditunjukkan pada contoh berikut.

[
    {
        "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."
                    }
                }
            }
        ]
    }
]

Kasus penggunaan lainnya guardContent adalah menyediakan konteks tambahan untuk pesan tanpa pagar pembatas Anda menilai konteks itu. Dalam contoh berikut, pagar pembatas hanya menilai "Create a playlist of heavy metal songs" dan mengabaikan. "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."
                    }
                }
            }
        ]
    }
]

Jika konten tidak berada dalam guardContent blok, itu tidak berarti itu tidak akan dievaluasi. Perilaku ini tergantung pada kebijakan penyaringan apa yang digunakan pagar pembatas.

Contoh berikut menunjukkan dua guardContent blok dengan pemeriksaan grounding kontekstual (berdasarkan bidang). qualifiers Pemeriksaan grounding kontekstual di pagar pembatas hanya akan mengevaluasi konten di blok ini. Namun, jika pagar pembatas juga memiliki filter kata yang memblokir kata “latar belakang”, teks “Beberapa informasi latar belakang tambahan.” masih akan dievaluasi, meskipun tidak dalam satu guardContent blok.

[{
    "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"]
                }
            }
        }
    ]
}]

Menjaga prompt sistem yang dikirim ke API Converse

Anda dapat menggunakan pagar pembatas dengan prompt sistem yang Anda kirim ke API. Converse Untuk menjaga prompt sistem, tentukan bidang guardContent (SystemContentBlock) di prompt sistem yang Anda teruskan ke API, seperti yang ditunjukkan pada contoh berikut.

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

Jika Anda tidak memberikan guardContent bidang, pagar pembatas tidak menilai pesan prompt sistem.

Pesan dan perilaku pagar pembatas prompt sistem

Bagaimana pagar pembatas menilai guardContent bidang berperilaku berbeda antara prompt sistem dan pesan yang Anda kirimkan dalam pesan.

Memproses respons saat menggunakan Converse API

Saat Anda memanggil operasi Converse, pagar pembatas menilai pesan yang Anda kirim. Jika pagar pembatas mendeteksi konten yang diblokir, hal berikut terjadi.

Respons sebagian berikut menunjukkan teks konten yang diblokir dan jejak dari penilaian pagar pembatas. Pagar pembatas telah memblokir istilah Heavy metal dalam pesan.

{
    "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
                            }
                        }
                    }
                }
            }
        }
    }
}

Contoh kode untuk menggunakan Converse API dengan pagar pembatas

Contoh ini menunjukkan bagaimana menjaga percakapan dengan Converse dan ConverseStream operasi. Contoh tersebut menunjukkan cara mencegah model membuat daftar putar yang menyertakan lagu-lagu dari genre heavy metal.

Converse

Kode berikut menggunakan pagar pembatas Anda dengan operasi. 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

Kode berikut menggunakan pagar pembatas Anda dengan operasi. 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()