Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris. # Kasus penggunaan untuk Pagar Batuan Dasar Amazon Setelah Anda membuat pagar pembatas, Anda dapat menerapkan dengan fitur-fitur berikut: + [Inferensi model](inference.md) — Terapkan pagar pembatas ke permintaan yang dikirimkan dan respons yang dihasilkan saat menjalankan inferensi pada model. + [Agen](agents.md) — Kaitkan pagar pembatas dengan agen untuk menerapkannya pada petunjuk yang dikirim ke agen dan tanggapan dikembalikan darinya. + [Basis pengetahuan](knowledge-base.md) — Terapkan pagar pembatas saat menanyakan basis pengetahuan dan menghasilkan tanggapan darinya. + [Flow](flows.md) — Tambahkan pagar pembatas ke node prompt atau node basis pengetahuan dalam aliran untuk menerapkannya ke input dan output dari node ini. Tabel berikut menjelaskan cara menyertakan pagar pembatas untuk masing-masing fitur ini menggunakan Konsol Manajemen AWS atau Amazon Bedrock API. **** | Kasus penggunaan | Konsol | API | | --- | --- | --- | | Inferensi model | Pilih pagar pembatas saat [menggunakan taman bermain.](playgrounds.md) | Tentukan di header dalam [InvokeModelWithResponseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModelWithResponseStream.html)permintaan [InvokeModel](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModel.html)atau sertakan di guardrailConfig bidang di badan [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)permintaan. | | Berasosiasi dengan agen | Saat Anda [membuat atau memperbarui](agents-build-modify.md) agen, tentukan di bagian detail Guardrail pada pembuat Agen. | Sertakan guardrailConfiguration bidang di badan [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_UpdateAgent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_UpdateAgent.html)permintaan [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_CreateAgent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_CreateAgent.html)atau permintaan. | | Gunakan saat menanyakan basis pengetahuan | Ikuti langkah-langkah di [Pagar pembatas](kb-test-config.md#kb-test-config-guardrails) bagian konfigurasi kueri. Tambahkan pagar pembatas saat Anda mengatur Konfigurasi. | Sertakan guardrailConfiguration bidang di badan [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)permintaan. | | Sertakan dalam simpul prompt dalam aliran | Saat Anda [membuat](flows-create.md) atau [memperbarui](flows-modify.md) alur, pilih simpul prompt dan tentukan pagar pembatas di bagian Konfigurasi. | Saat Anda menentukan simpul prompt di nodes bidang dalam [UpdateFlow](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_UpdateFlow.html)permintaan [CreateFlow](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_CreateFlow.html)atau, sertakan guardrailConfiguration bidang di [PromptFlowNodeConfiguration](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_PromptFlowNodeConfiguration.html). | | Sertakan dalam node basis pengetahuan dalam aliran | Saat Anda [membuat](flows-create.md) atau [memperbarui](flows-modify.md) alur, pilih node basis pengetahuan dan tentukan pagar pembatas di bagian Konfigurasi. | Saat Anda menentukan node basis pengetahuan di nodes bidang dalam [UpdateFlow](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_UpdateFlow.html)permintaan [CreateFlow](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_CreateFlow.html)atau, sertakan guardrailConfiguration bidang di [KnowledgeBaseFlowNodeConfiguration](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_KnowledgeBaseFlowNodeConfiguration.html). | Bagian ini mencakup penggunaan pagar pembatas dengan inferensi model dan Amazon Bedrock API. Anda dapat menggunakan operasi inferensi dasar ([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)) dan Converse API ([Converse](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Converse.html) dan [ConverseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseStream.html)). Dengan kedua set operasi Anda dapat menggunakan pagar pembatas dengan inferensi model sinkron dan streaming. Anda juga dapat mengevaluasi input pengguna secara selektif dan dapat mengonfigurasi perilaku respons streaming. **Topics** + [Gunakan pagar pembatas Anda dengan operasi inferensi untuk mengevaluasi masukan pengguna](guardrails-input-tagging-base-inference.md) + [Gunakan ApplyGuardrail API di aplikasi Anda](guardrails-use-independent-api.md) # Gunakan pagar pembatas Anda dengan operasi inferensi untuk mengevaluasi masukan pengguna Anda dapat menggunakan pagar pembatas dengan operasi inferensi dasar, [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)(streaming). Bagian ini mencakup cara Anda mengevaluasi input pengguna secara selektif dan bagaimana Anda dapat mengonfigurasi perilaku respons streaming. Perhatikan bahwa untuk aplikasi percakapan, Anda dapat mencapai hasil yang sama dengan [ConverseAPI](guardrails-use-converse-api.md). Misalnya kode yang memanggil operasi inferensi dasar, lihat[Kirim satu prompt dengan InvokeModel](inference-invoke.md). Untuk informasi tentang penggunaan pagar pembatas dengan operasi inferensi dasar, ikuti langkah-langkah di tab API. [Uji pagar pembatas Anda](guardrails-test.md) **Topics** + [Terapkan tag ke input pengguna untuk memfilter konten](guardrails-tagging.md) + [Konfigurasikan perilaku respons streaming untuk memfilter konten](guardrails-streaming.md) + [Sertakan pagar pembatas dengan API Converse](guardrails-use-converse-api.md) # Terapkan tag ke input pengguna untuk memfilter konten Tag input memungkinkan Anda menandai konten tertentu dalam teks input yang ingin diproses oleh pagar pembatas. Ini berguna ketika Anda ingin menerapkan pagar pembatas ke bagian input tertentu, sambil membiarkan bagian lain tidak diproses. Misalnya, prompt input dalam aplikasi RAG mungkin berisi prompt sistem, hasil pencarian dari sumber dokumentasi tepercaya, dan kueri pengguna. Karena permintaan sistem disediakan oleh pengembang dan hasil pencarian berasal dari sumber tepercaya, Anda mungkin hanya perlu evaluasi pagar pembatas hanya pada permintaan pengguna. Dalam contoh lain, prompt input dalam aplikasi percakapan mungkin berisi prompt sistem, riwayat percakapan, dan input pengguna saat ini. Permintaan sistem adalah instruksi khusus pengembang, dan riwayat percakapan berisi masukan pengguna historis dan respons model yang mungkin telah dievaluasi oleh pagar pembatas. Untuk skenario seperti itu, Anda mungkin hanya ingin mengevaluasi input pengguna saat ini. Dengan menggunakan tag input, Anda dapat mengontrol bagian mana dari prompt input yang harus diproses dan dievaluasi dengan pagar pembatas, memastikan bahwa perlindungan Anda disesuaikan dengan kasus penggunaan Anda. Ini juga membantu dalam meningkatkan kinerja, dan mengurangi biaya, karena Anda memiliki fleksibilitas untuk mengevaluasi bagian input yang relatif lebih pendek dan relevan, bukan seluruh prompt input. **Tandai konten untuk pagar pembatas** Untuk menandai konten untuk pagar pembatas untuk diproses, gunakan tag XMLyang merupakan kombinasi dari awalan cadangan dan kustom. `tagSuffix` Contoh: ``` { "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" } } ``` Dalam contoh sebelumnya, konten *`Berapa banyak objek yang saya miliki di ember S3 saya? *`dan "*“Bagaimana cara mengunduh file dari bucket S3 saya*? “ ditandai untuk pemrosesan pagar pembatas menggunakan tag. `` Perhatikan bahwa awalan `amazon-bedrock-guardrails-guardContent` disediakan oleh pagar pembatas. **Akhiran Tag** Sufiks tag (`xyz`dalam contoh sebelumnya) adalah nilai dinamis yang harus Anda berikan di `tagSuffix` bidang `amazon-bedrock-guardrailConfig` untuk menggunakan penandaan input. Disarankan untuk menggunakan string acak baru sebagai `tagSuffix` untuk setiap permintaan. Ini membantu mengurangi potensi serangan injeksi cepat dengan membuat struktur tag tidak dapat diprediksi. Tag statis dapat mengakibatkan pengguna jahat menutup tag XHTML dan menambahkan konten berbahaya setelah penutupan tag, yang mengakibatkan serangan *injeksi*. Anda terbatas pada karakter alfanumerik dengan panjang antara 1 dan 20 karakter, inklusif. Dengan akhiran contoh`xyz`, Anda harus melampirkan semua konten yang akan dijaga menggunakan tag XHTML dengan akhiran Anda:. `` *your content* `` Kami menyarankan Anda menggunakan pengenal unik dinamis untuk setiap permintaan sebagai akhiran tag. **Beberapa tag** Anda dapat menggunakan struktur tag yang sama beberapa kali dalam teks input untuk menandai bagian konten yang berbeda untuk pemrosesan pagar pembatas. Sarang tag tidak diperbolehkan. **Konten yang tidak ditandai** Konten di luar tag input tidak diproses oleh pagar pembatas. Ini memungkinkan Anda untuk menyertakan instruksi, contoh percakapan, basis pengetahuan, atau konten lain yang Anda anggap aman dan tidak ingin diproses oleh pagar pembatas. Jika tidak ada tag di prompt input, prompt lengkap akan diproses oleh pagar pembatas. Satu-satunya pengecualian adalah [Mendeteksi serangan cepat dengan Amazon Bedrock Guardrails](guardrails-prompt-attack.md) filter, yang membutuhkan tag input untuk hadir. # Konfigurasikan perilaku respons streaming untuk memfilter konten [InvokeModelWithResponseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModelWithResponseStream.html)API mengembalikan data dalam format streaming. Ini memungkinkan Anda untuk mengakses respons dalam potongan tanpa menunggu seluruh hasilnya. Saat menggunakan pagar pembatas dengan respons streaming, ada dua mode operasi: sinkron dan asinkron. **Mode sinkron** Dalam mode sinkron default, pagar pembatas akan menyangga dan menerapkan kebijakan yang dikonfigurasi ke satu atau beberapa potongan respons sebelum respons dikirim kembali ke pengguna. Mode pemrosesan sinkron memperkenalkan beberapa latensi ke potongan respons, karena itu berarti respons tertunda hingga pemindaian pagar pembatas selesai. Namun, ini memberikan akurasi yang lebih baik, karena setiap potongan respons dipindai oleh pagar pembatas sebelum dikirim ke pengguna. **Mode asinkron** Dalam mode asinkron, pagar pembatas mengirimkan potongan respons ke pengguna segera setelah tersedia, sambil menerapkan kebijakan yang dikonfigurasi secara asinkron di latar belakang. Keuntungannya adalah potongan respons diberikan segera tanpa dampak latensi, tetapi potongan respons mungkin berisi konten yang tidak pantas sampai pemindaian pagar pembatas selesai. Segera setelah konten yang tidak pantas diidentifikasi, potongan berikutnya akan diblokir oleh pagar pembatas. **Awas** Amazon Bedrock Guardrails tidak mendukung penyembunyian informasi sensitif dengan mode asinkron. **Mengaktifkan mode asinkron** Untuk mengaktifkan mode asinkron, Anda perlu menyertakan `streamProcessingMode` parameter dalam `amazon-bedrock-guardrailConfig` objek permintaan Anda: `InvokeModelWithResponseStream` ``` { "amazon-bedrock-guardrailConfig": { "streamProcessingMode": "ASYNCHRONOUS" } } ``` Dengan memahami trade-off antara mode sinkron dan asinkron, Anda dapat memilih mode yang sesuai berdasarkan persyaratan aplikasi Anda untuk latensi dan akurasi moderasi konten. # 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() ``` ------ # Gunakan ApplyGuardrail API di aplikasi Anda Guardrails digunakan untuk menerapkan perlindungan untuk aplikasi AI generatif Anda yang disesuaikan untuk kasus penggunaan Anda dan selaras dengan kebijakan AI Anda yang bertanggung jawab. Guardrails memungkinkan Anda mengonfigurasi topik yang ditolak, memfilter konten berbahaya, dan menghapus informasi sensitif. Anda dapat menggunakan `ApplyGuardrail` API untuk menilai teks apa pun menggunakan Amazon Bedrock Guardrails yang telah dikonfigurasi sebelumnya, tanpa menggunakan model foundation. Fitur `ApplyGuardrail` API meliputi: + **Validasi konten** - Anda dapat mengirim input atau output teks apa pun ke `ApplyGuardrail` API untuk membandingkannya dengan aturan penghindaran topik yang ditentukan, filter konten, detektor PII, dan daftar blok kata. Anda dapat mengevaluasi input pengguna dan output yang dihasilkan FM secara independen. + **Penerapan fleksibel** — Anda dapat mengintegrasikan `ApplyGuardrail` API di mana saja dalam alur aplikasi Anda untuk memvalidasi data sebelum memproses atau menyajikan hasil kepada pengguna. Misalnya, jika Anda menggunakan aplikasi RAG, Anda sekarang dapat mengevaluasi input pengguna sebelum melakukan pengambilan, alih-alih menunggu hingga pembuatan respons akhir. + **Dipisahkan dari model pondasi** - `ApplyGuardrail` API dipisahkan dari model dasar. Anda sekarang dapat menggunakan Guardrails tanpa menggunakan Foundation Models. Anda dapat menggunakan hasil penilaian untuk merancang pengalaman pada aplikasi AI generatif Anda. **Topics** + [Panggilan ApplyGuardrail dalam alur aplikasi Anda](#guardrails-use-independent-api-call) + [Tentukan pagar pembatas yang akan digunakan ApplyGuardrail](#guardrails-use-indepedent-api-call-configure) + [Contoh kasus penggunaan ApplyGuardrail](#guardrails-use-independent-api-call-message) + [Kembalikan output penuh ApplyGuardrail sebagai tanggapan](#guardrails-use-return-full-assessment) ## Panggilan ApplyGuardrail dalam alur aplikasi Anda Permintaan ini memungkinkan pelanggan untuk meneruskan semua konten mereka yang harus dijaga menggunakan pagar pembatas yang ditentukan. Bidang sumber harus diatur ke `INPUT` saat konten yang akan dievaluasi berasal dari pengguna (biasanya prompt input ke LLM). Sumber harus disetel ke `OUTPUT` kapan pagar pembatas keluaran model harus ditegakkan (biasanya respons LLM). ## Tentukan pagar pembatas yang akan digunakan ApplyGuardrail Saat menggunakan`ApplyGuardrail`, Anda menentukan `guardrailIdentifier` dan pagar `guardrailVersion` pembatas yang ingin Anda gunakan. Anda juga dapat mengaktifkan penelusuran untuk pagar pembatas, yang memberikan informasi tentang konten yang diblokir pagar pembatas. ------ #### [ 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" } } ] } ``` ------ ## Contoh kasus penggunaan ApplyGuardrail Output `ApplyGuardrail` permintaan tergantung pada tindakan pagar pembatas yang diambil pada konten yang diteruskan. + Jika pagar pembatas diintervensi di mana konten hanya ditutupi, konten yang tepat dikembalikan dengan masking diterapkan. + Jika pagar pembatas mengintervensi dan memblokir konten permintaan, bidang output akan menjadi satu teks, yang merupakan pesan kalengan berdasarkan konfigurasi pagar pembatas. + Jika tidak ada tindakan pagar pembatas yang diambil pada konten permintaan, array output kosong. ------ #### [ Guardrails takes no action ] **Minta contoh** ``` { "source": "OUTPUT", "content": [ "text": { "text": "Hi, my name is Zaid. Which car brand is reliable?" } ] } ``` **Contoh respons** ``` { "usage": { "topicPolicyUnitsProcessed": 1, "contentPolicyUnitsProcessed": 1, "wordPolicyUnitsProcessed": 0, "sensitiveInformationPolicyFreeUnits": 0 }, "action": "NONE", "outputs": [], "assessments": [{}] } ``` ------ #### [ Guardrails blocks content ] **Contoh respons** ``` { "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 ] **Contoh respons** Pagar pembatas mengintervensi dengan menutupi nama. `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 ] **Contoh masukan** ``` 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 ``` **Contoh keluaran (konten blok)** ``` { "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" } ] } } ] } ``` ------ ## Kembalikan output penuh ApplyGuardrail sebagai tanggapan Konten dianggap terdeteksi jika melanggar konfigurasi pagar pembatas Anda. Misalnya, landasan kontekstual dianggap terdeteksi jika skor grounding atau relevansi kurang dari ambang batas yang sesuai. Secara default, [ApplyGuardrail](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ApplyGuardrail.html)operasi hanya mengembalikan konten yang terdeteksi dalam respons. Anda dapat menentukan `outputScope` bidang dengan `FULL` nilai untuk mengembalikan output penuh. Dalam hal ini, respons juga akan menyertakan entri yang tidak terdeteksi untuk debugging yang ditingkatkan. Anda dapat mengonfigurasi perilaku yang sama ini dalam `Converse` operasi `Invoke` dan dengan menyetel jejak ke opsi lengkap yang diaktifkan. **catatan** Cakupan keluaran penuh tidak berlaku untuk filter kata atau regex di filter informasi sensitif. Ini berlaku untuk semua kebijakan penyaringan lainnya, termasuk informasi sensitif dengan filter yang dapat mendeteksi informasi identitas pribadi (PII).