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, lihat[Melakukan percakapan dengan operasi Converse API](conversation-inference.md). **Topics** + [Panggil Converse API dengan pagar pembatas](#guardrails-use-converse-api-call) + [Memproses respons saat menggunakan Converse API](#guardrails-use-converse-api-response) + [Contoh kode untuk menggunakan Converse API dengan pagar pembatas](#converse-api-guardrail-example) ## Panggil Converse API dengan pagar pembatas Untuk menggunakan pagar pembatas, Anda menyertakan informasi konfigurasi untuk pagar pembatas dalam panggilan ke operasi [Converse](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Converse.html) atau [ConverseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseStream.html)(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](conversation-inference-supported-models-features.md) **Topics** + [Konfigurasikan pagar pembatas untuk bekerja dengan API Converse](#guardrails-use-converse-api-call-configure) + [Mengevaluasi hanya konten tertentu dalam pesan](#guardrails-use-converse-api-call-message) + [Menjaga prompt sistem yang dikirim ke API Converse](#guardrails-use-converse-api-call-message-system-guard) + [Pesan dan perilaku pagar pembatas prompt sistem](#guardrails-use-converse-api-call-message-system-message-guard) ### Konfigurasikan pagar pembatas untuk bekerja dengan API Converse Anda menentukan informasi konfigurasi 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 [GuardrailConfiguration](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_GuardrailConfiguration.html)objek, seperti yang ditunjukkan pada contoh berikut. ``` { "guardrailIdentifier": "Guardrail ID", "guardrailVersion": "Guardrail version", "trace": "enabled" } ``` Jika Anda menggunakan`ConverseStream`, Anda melewati [GuardrailStreamConfiguration](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_GuardrailStreamConfiguration.html)objek. 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](guardrails-streaming.md). ### Mengevaluasi hanya konten tertentu dalam pesan Saat Anda meneruskan [Pesan](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Message.html) ke model, pagar pembatas menilai konten dalam pesan. Anda juga dapat menilai bagian tertentu dari pesan dengan menggunakan bidang `guardContent` ([GuardrailConverseContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_GuardrailConverseContentBlock.html)). **Tip** Menggunakan `guardContent` bidang ini mirip dengan menggunakan tag input dengan [InvokeModel](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModel.html)dan [InvokeModelWithResponseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModelWithResponseStream.html). Untuk informasi selengkapnya, lihat [Terapkan tag ke input pengguna untuk memfilter konten](guardrails-tagging.md). 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](guardrails-contextual-grounding-check.md) (berdasarkan bidang). `qualifiers` Pemeriksaan grounding kontekstual di pagar pembatas hanya akan mengevaluasi konten di blok ini. Namun, jika pagar pembatas juga memiliki [filter kata](guardrails-content-filters.md) 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](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_SystemContentBlock.html)) 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. | | Prompt sistem memiliki blok pagar pembatas | Prompt sistem tidak memiliki blok pagar pembatas | | --- | --- | --- | | **Pesan memiliki blok pagar pembatas** | Sistem: Guardrail menyelidiki konten di blok pagar pembatas Pesan: Pagar pembatas menyelidiki konten di blok pagar pembatas | Sistem: Pagar pembatas tidak menyelidiki apa pun Pesan: Pagar pembatas menyelidiki konten di blok pagar pembatas | | **Pesan tidak memiliki blok pagar pembatas** | Sistem: Guardrail menyelidiki konten di blok pagar pembatas 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. + `stopReason`Bidang dalam respons diatur ke`guardrail_intervened`. + Jika Anda mengaktifkan penelusuran, jejak tersedia di Bidang `trace` ([ConverseTrace](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseTrace.html)). Dengan`ConverseStream`, jejak ada di metadata ([ConverseStreamMetadataEvent](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseStreamMetadataEvent.html)) yang dikembalikan operasi. + Teks konten yang diblokir yang telah Anda konfigurasikan di pagar pembatas dikembalikan di bidang `output` ([ConverseOutput](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseOutput.html)). 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" } ] }, "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. **Untuk menjaga percakapan** 1. Buat pagar pembatas dengan mengikuti instruksi di. [Buat pagar pembatas Anda](guardrails-components.md) + **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. 1. Buat versi pagar pembatas dengan mengikuti instruksi di. [Buat versi pagar pembatas](guardrails-versions-create.md) 1. Dalam contoh kode berikut ([Converse](#converse-api-guardrail-example-converse) dan [ConverseStream](#converse-api-guardrail-example-converse-stream)), 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.` 1. 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. 1. (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() ``` ------