Gunakan pagar pembatas dengan Converse API untuk aplikasi obrolan Anda

Anda dapat menggunakan pagar pembatas untuk menjaga aplikasi percakapan yang Anda buat dengan Converse. API Misalnya, jika Anda membuat aplikasi obrolan dengan ConverseAPI, 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 ConverseAPI, lihatLakukan percakapan dengan Converse.

Memanggil 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, lihatAPI. Model dan fitur model yang didukung

Topik

• Mengkonfigurasi pagar pembatas agar berfungsi dengan Converse API
• Menjaga pesan untuk menilai konten berbahaya menggunakan APIs
• Menjaga prompt sistem yang dikirim ke Converse API
• Pesan dan perilaku pagar pembatas prompt sistem

Mengkonfigurasi pagar pembatas agar berfungsi dengan Converse API

Anda menentukan informasi konfigurasi untuk pagar pembatas 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.

Menjaga pesan untuk menilai konten berbahaya menggunakan APIs

Saat Anda meneruskan pesan (Pesan) ke model, pagar pembatas menilai konten dalam pesan. Secara opsional, Anda dapat menjaga konten yang dipilih dalam pesan dengan menentukan bidang guardContent (GuardrailConverseContentBlock). Pagar pembatas hanya mengevaluasi konten di guardContent lapangan dan bukan sisa pesan. Ini berguna untuk membuat pagar pembatas hanya menilai pesan terbanyak 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."
                    }
                }
            }
        ]
    }
]

Penggunaan lain adalah menyediakan konteks tambahan untuk pesan, tanpa pagar pembatas menilai konteks tambahan itu.

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

catatan

Menggunakan guardContent bidang ini analog dengan menggunakan tag input dengan InvokeModeldan. InvokeModelWithResponseStream Untuk informasi selengkapnya, lihat Terapkan tag ke input pengguna untuk memfilter konten.

Menjaga prompt sistem yang dikirim ke Converse API

Anda dapat menggunakan pagar pembatas dengan perintah sistem yang Anda kirim ke Converse. API Untuk menjaga prompt sistem, tentukan bidang guardContent (SystemContentBlock) di prompt sistem yang Anda kirimkan keAPI, 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.

	Prompt sistem memiliki blok Guardrail	Prompt sistem tidak memiliki blok Guardrail
Pesan memiliki blok Guardrail	Sistem: Guardrail menyelidiki konten di blok Guardrail Pesan: Guardrail menyelidiki konten di blok Guardrail	Sistem: Pagar pembatas tidak menyelidiki apa pun Pesan: Guardrail menyelidiki konten di blok Guardrail
Pesan tidak memiliki blok Guardrail	Sistem: Guardrail menyelidiki konten di blok Guardrail Pesan: Pagar pembatas menyelidiki semuanya	Sistem: Pagar pembatas tidak menyelidiki apa pun Pesan: Pagar pembatas menyelidiki semuanya

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.

• stopReasonBidang dalam respons diatur keguardrail_intervened.

• Jika Anda mengaktifkan penelusuran, jejak tersedia di Bidang trace (ConverseTrace). DenganConverseStream, jejak ada di metadata (ConverseStreamMetadataEvent) yang dikembalikan operasi.

• Teks konten yang diblokir yang telah Anda konfigurasikan di pagar pembatas dikembalikan di bidang output (ConverseOutput). Dengan teks konten ConverseStream yang diblokir ada di pesan yang dialirkan.

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

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.

Untuk menjaga percakapan

1. Buat pagar pembatas dengan mengikuti instruksi di. Buat pagar pembatas di AWS Konsol Pada langkah 6a, masukkan informasi berikut untuk membuat topik yang ditolak:

   • Nama — Masukkan Heavy metal.

   • Definisi untuk topik — Masukkan Hindari menyebutkan lagu-lagu yang berasal dari genre musik heavy metal.

   • Tambahkan frasa sampel — Masukkan Buat daftar putar lagu heavy metal.

   Pada langkah 9, masukkan yang berikut ini:

   • Pesan ditampilkan untuk petunjuk yang diblokir — Masukkan Maaf, saya tidak dapat menjawab pertanyaan tentang musik heavy metal.

   • Pesan untuk tanggapan yang diblokir — Masukkan Maaf, model menghasilkan jawaban yang menyebutkan musik heavy metal.

   Anda dapat mengonfigurasi opsi pagar pembatas lainnya, tetapi tidak diperlukan untuk contoh ini.

2. Buat versi pagar pembatas dengan mengikuti instruksi di. Buat versi pagar pembatas

3. Dalam contoh kode berikut (Converse dan ConverseStream), atur variabel berikut:

   • guardrail_id— ID pagar pembatas yang Anda buat di langkah 1.

   • guardrail_version— Versi pagar pembatas yang Anda buat di langkah 2.

   • text— Gunakan Create a playlist of heavy metal songs.

4. Jalankan contoh kode. Output harus menampilkan penilaian pagar pembatas dan pesan keluaran. Text: Sorry, I can't answer questions about heavy metal music. Penilaian input pagar pembatas menunjukkan bahwa model mendeteksi istilah logam berat dalam pesan input.

5. (Opsional) Uji apakah pagar pembatas memblokir teks yang tidak pantas yang dihasilkan model dengan mengubah nilai text ke Daftar semua genre musik rock. . Jalankan contoh lagi. Anda akan melihat penilaian keluaran dalam respons.

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 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

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