Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris. # Integrasikan pemeriksaan Penalaran Otomatis dalam aplikasi Anda Setelah menerapkan kebijakan Penalaran Otomatis di pagar pembatas (lihat[Terapkan kebijakan Penalaran Otomatis Anda di aplikasi Anda](deploy-automated-reasoning-policy.md)), Anda dapat menggunakannya saat runtime untuk memvalidasi respons LLM dan bertindak berdasarkan umpan balik. Halaman ini menjelaskan cara memanggil API validasi, menafsirkan temuan secara terprogram, dan menerapkan pola integrasi umum seperti menulis ulang tanggapan yang tidak valid dan mengajukan pertanyaan klarifikasi. Pemeriksaan Penalaran Otomatis hanya beroperasi dalam *mode deteksi* — mereka mengembalikan temuan dan umpan balik daripada memblokir konten. Aplikasi Anda bertanggung jawab untuk memutuskan apa yang harus dilakukan dengan temuan: menyajikan tanggapan, menulis ulang, meminta klarifikasi, atau kembali ke perilaku default. ## Ikhtisar integrasi Saat runtime, integrasi mengikuti alur ini: ``` User question ──► LLM generates response ──► ApplyGuardrail validates response │ ┌─────────┴─────────┐ │ │ VALID Not VALID │ │ ▼ ▼ Serve response Inspect findings to user │ ┌────────┴────────┐ │ │ OTHER FINDING TRANSLATION_ TYPES AMBIGUOUS / SATISFIABLE │ │ ▼ ▼ Rewrite using Ask user for AR feedback clarification │ │ ▼ ▼ Validate again Validate with clarified input ``` Temuan Penalaran Otomatis dikembalikan melalui API apa pun yang mendukung konfigurasi Amazon Bedrock Guardrails: + `ApplyGuardrail`- API validasi mandiri. Gunakan ini ketika Anda ingin memvalidasi konten secara independen dari pemanggilan LLM. Ini adalah pendekatan yang disarankan untuk pemeriksaan Penalaran Otomatis karena memberi Anda kontrol penuh atas konten apa yang divalidasi dan kapan. + `Converse`dan `InvokeModel` — Pemanggilan LLM APIs dengan konfigurasi pagar pembatas. Temuan Penalaran Otomatis dikembalikan di `trace` bidang respons. + `InvokeAgent`dan `RetrieveAndGenerate` — Agen dan basis pengetahuan APIs dengan konfigurasi pagar pembatas. Halaman ini berfokus pada `ApplyGuardrail` API karena memberikan fleksibilitas paling besar untuk menerapkan pola penulisan ulang dan klarifikasi yang dijelaskan di bawah ini. Untuk informasi tentang menggunakan pagar pembatas dengan yang lain APIs, lihat [Menggunakan pagar pembatas](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails-use.html). ## Contoh chatbot penulisan ulang sumber terbuka Untuk implementasi lengkap gaya produksi dari pola yang dijelaskan di halaman ini, lihat [Pemeriksaan Penalaran Otomatis](https://github.com/aws-samples/amazon-bedrock-samples/tree/main/responsible_ai/automated-reasoning-rewriting-chatbot) yang menulis ulang chatbot. GitHub Contoh aplikasi ini menunjukkan: + Loop penulisan ulang berulang di mana respons yang tidak valid secara otomatis dikoreksi berdasarkan umpan balik AR. + Menindaklanjuti pertanyaan ketika LLM membutuhkan konteks tambahan dari pengguna untuk menulis ulang secara akurat. + Mekanisme batas waktu yang secara otomatis melanjutkan pemrosesan saat pengguna tidak menanggapi pertanyaan klarifikasi. + Injeksi konteks kebijakan ke LLM diminta sehingga LLM dapat merujuk aturan kebijakan lengkap selama penulisan ulang. + Pencatatan audit JSON dari setiap iterasi validasi untuk kepatuhan dan debugging. Sampel menggunakan Python/Flask backend dengan frontend React dan berkomunikasi dengan Amazon Bedrock untuk inferensi LLM dan Amazon Bedrock Guardrails untuk validasi melalui API. `ApplyGuardrail` **catatan** Aplikasi sampel menyertakan konten kebijakan secara langsung dalam permintaan pembuatan LLM untuk mendukung kebijakan Penalaran Otomatis apa pun tanpa memerlukan unggahan dokumen. Dalam penerapan produksi, Anda biasanya akan menggunakan konten RAG atau memberi LLM dokumen bahasa alami asli alih-alih kode sumber kebijakan Penalaran Otomatis. ## Panggilan ApplyGuardrail dengan pemeriksaan Penalaran Otomatis Gunakan `ApplyGuardrail` API untuk memvalidasi konten terhadap pagar pembatas Anda. API menerima satu atau beberapa blok konten dan mengembalikan penilaian yang mencakup temuan Penalaran Otomatis. ### Struktur permintaan `guardrailIdentifier`(Diperlukan) ID pagar pembatas atau ARN. Gunakan pagar pembatas yang memiliki kebijakan Penalaran Otomatis Anda terlampir. `guardrailVersion`(Diperlukan) Nomor versi pagar pembatas (misalnya,`1`). Gunakan versi bernomor untuk beban kerja produksi, bukan. `DRAFT` `source`(Diperlukan) Setel ke `OUTPUT` saat memvalidasi tanggapan LLM. Setel ke `INPUT` saat memvalidasi permintaan pengguna. Untuk pemeriksaan Penalaran Otomatis, Anda biasanya memvalidasi output LLM. `content`(Diperlukan) Array blok konten untuk memvalidasi. Setiap blok berisi `text` bidang dengan konten untuk diperiksa. Anda dapat meneruskan pertanyaan pengguna dan respons LLM sebagai blok konten terpisah, atau menggabungkannya menjadi satu blok. ### Contoh: Validasi respons LLM menggunakan AWS CLI ``` aws bedrock-runtime apply-guardrail \ --guardrail-identifier "your-guardrail-id" \ --guardrail-version "1" \ --source OUTPUT \ --content '[ { "text": { "text": "User: Am I eligible for parental leave if I have been working here for 2 years full-time?\nAssistant: Yes, you are eligible for parental leave." } } ]' ``` ### Contoh: Validasi respons LLM menggunakan Python (boto3) ``` import boto3 import json bedrock_runtime = boto3.client("bedrock-runtime", region_name="us-east-1") response = bedrock_runtime.apply_guardrail( guardrailIdentifier="your-guardrail-id", guardrailVersion="1", source="OUTPUT", content=[ { "text": { "text": ( "User: Am I eligible for parental leave if I have been " "working here for 2 years full-time?\n" "Assistant: Yes, you are eligible for parental leave." ) } } ], ) # The AR findings are in the assessments for assessment in response.get("assessments", []): ar_assessment = assessment.get("automatedReasoningPolicy", {}) findings = ar_assessment.get("findings", []) for finding in findings: # Each finding is a union — exactly one key is present # Possible keys: valid, invalid, satisfiable, impossible, # translationAmbiguous, tooComplex, noTranslations print(json.dumps(finding, indent=2, default=str)) ``` ### Struktur respons `ApplyGuardrail`Responsnya mencakup `assessments` array. Setiap penilaian berisi `automatedReasoningPolicy` objek dengan `findings` array. Setiap temuan adalah tipe gabungan — persis salah satu kunci berikut hadir: + `valid` + `invalid` + `satisfiable` + `impossible` + `translationAmbiguous` + `tooComplex` + `noTranslations` Untuk penjelasan rinci tentang setiap jenis temuan dan bidangnya, lihat[Hasil temuan dan validasi](automated-reasoning-checks-concepts.md#ar-concept-findings). ## Menafsirkan temuan AR saat runtime Untuk bertindak berdasarkan temuan Penalaran Otomatis secara terprogram, aplikasi Anda perlu mengekstrak jenis temuan, detail terjemahan, dan aturan pendukung atau kontradiksi. Bagian berikut menjelaskan cara mengurai setiap bagian dari temuan. ### Tentukan jenis temuan Setiap temuan adalah persatuan — persis satu kunci hadir. Periksa kunci mana yang ada untuk menentukan jenis temuan: ``` def get_finding_type(finding): """Return the finding type and its data from an AR finding union.""" for finding_type in [ "valid", "invalid", "satisfiable", "impossible", "translationAmbiguous", "tooComplex", "noTranslations" ]: if finding_type in finding: return finding_type, finding[finding_type] return None, None ``` ### Baca terjemahannya Sebagian besar jenis temuan menyertakan `translation` objek yang menunjukkan bagaimana pemeriksaan Penalaran Otomatis menerjemahkan input bahasa alami ke dalam logika formal. Terjemahannya berisi: + `premises`— Kondisi yang diekstraksi dari input (misalnya,`isFullTime = true`,`tenureMonths = 24`). + `claims`— Pernyataan untuk memvalidasi (misalnya,). `eligibleForParentalLeave = true` + `untranslatedPremises`— Bagian dari input yang tidak dapat dipetakan ke variabel kebijakan. Bagian-bagian ini tidak divalidasi. + `untranslatedClaims`— Klaim yang tidak dapat dipetakan ke variabel kebijakan. Periksa `untranslatedPremises` dan `untranslatedClaims` untuk memahami ruang lingkup validasi. `VALID`Hasilnya hanya mencakup klaim yang diterjemahkan — konten yang tidak diterjemahkan tidak diverifikasi. ### Baca aturan pendukung atau kontradiktif Bergantung pada jenis temuan, temuan tersebut mencakup aturan yang menjelaskan hasilnya: + `valid`Temuan meliputi `supportingRules` — aturan kebijakan yang membuktikan klaim itu benar. + `invalid`Temuan meliputi `contradictingRules` — aturan kebijakan yang dilanggar klaim. + `satisfiable`Temuan termasuk a `claimsTrueScenario` dan a `claimsFalseScenario` — menunjukkan kondisi di mana klaim itu benar dan salah. Aturan dan skenario ini adalah input utama untuk pola penulisan ulang yang dijelaskan dalam. [Tulis ulang tanggapan yang tidak valid menggunakan umpan balik AR](#rewrite-invalid-responses) ### Tentukan hasil agregat Permintaan validasi tunggal dapat mengembalikan beberapa temuan. Untuk menentukan hasil keseluruhan, urutkan temuan berdasarkan tingkat keparahan dan pilih yang terburuk. Urutan keparahan dari terburuk ke yang terbaik adalah:`TRANSLATION_AMBIGUOUS`,,`IMPOSSIBLE`,`INVALID`,`SATISFIABLE`,`VALID`. ``` SEVERITY_ORDER = { "tooComplex": 0, "translationAmbiguous": 0, "impossible": 1, "invalid": 2, "satisfiable": 3, "valid": 4, "noTranslations": 5, } def get_aggregate_result(findings): """Return the worst finding type from a list of findings.""" worst = None worst_severity = float("inf") for finding in findings: finding_type, _ = get_finding_type(finding) severity = SEVERITY_ORDER.get(finding_type, 0) if severity < worst_severity: worst_severity = severity worst = finding_type return worst ``` ## Menangani hasil validasi dalam aplikasi Anda Gunakan hasil agregat untuk memutuskan apa yang dilakukan aplikasi Anda selanjutnya. Tabel berikut merangkum tindakan yang disarankan untuk setiap jenis hasil. | Hasil | Apa artinya | Tindakan yang disarankan | | --- | --- | --- | | valid | Tanggapannya terbukti secara matematis benar mengingat premis dan aturan kebijakan Anda. | Sajikan respons kepada pengguna. Catat temuan untuk tujuan audit (lihat[Membangun jejak audit](#build-audit-trail)). | | invalid | Responsnya bertentangan dengan aturan kebijakan Anda. contradictingRulesBidang mengidentifikasi aturan mana yang dilanggar. | Tulis ulang respons menggunakan umpan balik AR (lihat[Tulis ulang tanggapan yang tidak valid menggunakan umpan balik AR](#rewrite-invalid-responses)). Jika penulisan ulang gagal setelah beberapa kali mencoba, blokir respons dan kembalikan pesan fallback. | | satisfiable | Responsnya benar dalam beberapa kondisi tetapi tidak semua. Itu tidak salah, tetapi tidak lengkap - tidak menyebutkan semua persyaratan. | Tulis ulang respons untuk memasukkan kondisi yang hilang. Gunakan claimsFalseScenario untuk mengidentifikasi apa yang hilang. Atau, Anda dapat membiarkan LLM Anda mengajukan pertanyaan klarifikasi pengguna. | | impossible | Tempat itu kontradiktif, atau kebijakan tersebut mengandung aturan yang bertentangan. | Minta pengguna untuk mengklarifikasi masukan mereka (lihat[Ajukan pertanyaan klarifikasi](#ask-clarifying-questions)). Jika masalah berlanjut, ini mungkin mengindikasikan masalah kebijakan - tinjau laporan kualitas. | | translationAmbiguous | Masukan memiliki beberapa interpretasi yang valid. Model terjemahan tidak setuju tentang cara memetakan bahasa alami ke variabel kebijakan. | Mintalah pengguna untuk klarifikasi untuk menyelesaikan ambiguitas. Gunakan differenceScenarios bidang options dan untuk menghasilkan pertanyaan klarifikasi yang ditargetkan. | | tooComplex | Input melebihi batas pemrosesan untuk analisis logis. | Sederhanakan input dengan memecahnya menjadi bagian-bagian yang lebih kecil, atau kembalikan pesan fallback yang menjelaskan bahwa respons tidak dapat diverifikasi. | | noTranslations | Masukan tidak relevan dengan domain kebijakan Anda. Tidak ada variabel kebijakan yang dapat dipetakan. | Konten di luar topik untuk kebijakan ini. Sajikan respons tanpa validasi AR, atau gunakan komponen pagar pembatas lainnya (seperti kebijakan topik) untuk menangani konten di luar topik. | ## Tulis ulang tanggapan yang tidak valid menggunakan umpan balik AR Pola integrasi yang paling kuat untuk pemeriksaan Penalaran Otomatis adalah *loop penulisan ulang*: ketika respons `invalid` atau`satisfiable`, aplikasi Anda membuat prompt yang mencakup respons asli, temuan spesifik, dan aturan kebijakan, lalu meminta LLM untuk menulis ulang respons agar konsisten dengan kebijakan. Respons yang ditulis ulang divalidasi lagi, dan loop berlanjut sampai respons `valid` atau jumlah iterasi maksimum tercapai. ### Menulis ulang aliran loop ``` LLM generates initial response │ ▼ Validate with ApplyGuardrail ◄──────────────────┐ │ │ ▼ │ ┌─────┴─────┐ │ │ │ │ VALID Not VALID │ │ │ │ ▼ ▼ │ Done Construct rewriting prompt │ with findings + rules │ │ │ ▼ │ LLM rewrites response │ │ │ ▼ │ Max iterations? ──── No ────────────────┘ │ Yes │ ▼ Return best response with warning ``` ### Bangun prompt penulisan ulang Prompt penulisan ulang harus mencakup tiga informasi dari temuan AR: 1. Respon asli yang gagal validasi. 1. Temuan spesifik — termasuk premis yang diterjemahkan, klaim, dan aturan yang bertentangan atau mendukung. 1. Instruksi untuk menulis ulang tanggapan sehingga konsisten dengan aturan kebijakan. **Contoh template prompt penulisan ulang:** ``` The following response was checked against our policy and found to be {finding_type}. Original response: {original_response} The validation found the following issue: - Premises (what was understood from the input): {premises} - Claims (what was asserted): {claims} - Contradicting rules: {contradicting_rules} Please rewrite the response so that it is consistent with the policy document. Keep the same helpful tone and answer the user's question accurately based on the rules. If you cannot provide an accurate answer without more information, explain what additional information is needed. ``` **Tip** Selalu sertakan konten Retrieval Augmented Generation (RAG) dalam permintaan penulisan ulang Anda atau aturan kebijakan sehingga LLM memiliki semua konteks yang dibutuhkan saat menulis ulang. Templat prompt penulisan ulang memberikan detail temuan spesifik, sedangkan prompt sistem menyediakan konteks kebijakan yang lebih luas. Pendekatan konteks ganda ini ditunjukkan dalam contoh chatbot penulisan [ulang sumber terbuka](https://github.com/aws-samples/amazon-bedrock-samples/tree/main/responsible_ai/automated-reasoning-rewriting-chatbot). ### Menulis ulang praktik terbaik + **Tetapkan jumlah iterasi maksimum.** Loop penulisan ulang harus memiliki batas keras (biasanya 2-5 iterasi) untuk mencegah loop tak terbatas. Jika respons masih tidak `valid` setelah iterasi maksimum, kembalikan respons terbaik dengan peringatan atau kembali ke pesan default. + **Memproses temuan dalam urutan prioritas.** Ketika beberapa temuan dikembalikan, atasi temuan yang paling parah terlebih dahulu. Urutan tingkat keparahannya adalah: `translationAmbiguous``impossible`,,`invalid`,`satisfiable`,`valid`. + **Sertakan konteks kebijakan dalam prompt sistem.** LLM membutuhkan akses ke dokumen sumber atau aturan kebijakan lengkap untuk menulis ulang secara akurat. Anda dapat menggunakan [Pangkalan Pengetahuan](https://docs.aws.amazon.com/bedrock/latest/userguide/knowledge-base.html) untuk menyertakan dokumen Anda dalam permintaan pembuatan atau menggunakan `ExportAutomatedReasoningPolicyVersion` API untuk mengambil definisi kebijakan dan memformatnya untuk LLM. + **Log setiap iterasi.** Catat respons asli, temuan, prompt penulisan ulang, dan respons yang ditulis ulang untuk setiap iterasi. Jejak audit ini berharga untuk debugging dan kepatuhan (lihat[Membangun jejak audit](#build-audit-trail)). ## Ajukan pertanyaan klarifikasi Ketika Penalaran Otomatis memeriksa kembali`translationAmbiguous`,`satisfiable`, atau `impossible` hasil, LLM mungkin tidak memiliki informasi yang cukup untuk menulis ulang respons secara akurat. Dalam kasus ini, aplikasi Anda dapat meminta pengguna untuk klarifikasi, kemudian memasukkan jawaban ke dalam upaya validasi berikutnya. ### Kapan harus meminta klarifikasi + **`translationAmbiguous`**— Masukan memiliki beberapa interpretasi yang valid. `options`Bidang ini menunjukkan interpretasi yang bersaing, dan `differenceScenarios` lapangan menunjukkan bagaimana mereka berbeda dalam praktik. Gunakan ini untuk menghasilkan pertanyaan yang ditargetkan tentang ambiguitas spesifik. + **`satisfiable`**Responsnya benar dalam beberapa kondisi tetapi tidak semua. Ini `claimsFalseScenario` menunjukkan kondisi di mana respons akan salah. Tanyakan kepada pengguna tentang kondisi spesifik tersebut. + **`impossible`**Masukan berisi pernyataan yang kontradiktif. Minta pengguna untuk mengklarifikasi kontradiksi. + **Penulisan ulang gagal** — Jika LLM tidak dapat menulis ulang respons `valid` setelah beberapa kali mencoba, mungkin perlu konteks tambahan dari pengguna. Mintalah LLM untuk menghasilkan pertanyaan klarifikasi berdasarkan temuan. ### Pola klarifikasi Alur klarifikasi berfungsi sebagai berikut: 1. Ekstrak variabel ambigu atau kondisi yang hilang dari temuan AR. 1. Hasilkan pertanyaan klarifikasi - baik secara terprogram dari bidang temuan, atau dengan meminta LLM untuk merumuskan pertanyaan berdasarkan temuan. 1. Sajikan pertanyaan kepada pengguna dan kumpulkan jawaban. 1. Masukkan jawaban ke dalam konteks dan hasilkan respons baru. 1. Validasi respons baru dengan`ApplyGuardrail`. **Contoh: Hasilkan pertanyaan klarifikasi dari temuan `satisfiable`** ``` def generate_clarifying_questions(finding_data, user_question): """Ask the LLM to generate clarifying questions from a SATISFIABLE finding.""" claims_true = json.dumps( finding_data.get("claimsTrueScenario", {}), indent=2, default=str ) claims_false = json.dumps( finding_data.get("claimsFalseScenario", {}), indent=2, default=str ) prompt = ( f"A user asked: {user_question}\n\n" f"The answer is correct when these conditions hold:\n{claims_true}\n\n" f"But incorrect when these conditions hold:\n{claims_false}\n\n" f"Generate 1-3 short, specific questions to ask the user to determine " f"which conditions apply to their situation. Format each question on " f"its own line." ) return generate_response(prompt, "You are a helpful assistant.") ``` ## Membangun jejak audit Temuan Penalaran Otomatis memberikan bukti validitas yang dapat diverifikasi secara matematis. Untuk industri yang diatur dan skenario kepatuhan, bukti ini adalah pembeda utama - Anda dapat menunjukkan bahwa respons AI telah diverifikasi terhadap aturan kebijakan tertentu dengan penugasan variabel tertentu, tidak hanya cocok dengan pola atau dinilai secara probabilistik. Untuk membangun jejak audit yang efektif, catat informasi berikut untuk setiap permintaan validasi: + **Stempel waktu dan ID permintaan.** Ketika validasi terjadi dan pengenal unik untuk permintaan. + **Konten masukan.** Pertanyaan pengguna dan respons LLM yang divalidasi. + **Menemukan jenis dan detail.** Hasil validasi (`valid`,`invalid`, dll.), premis dan klaim yang diterjemahkan, dan aturan pendukung atau kontradiksi. + **Tindakan diambil.** Apa yang dilakukan aplikasi Anda dengan temuan - menyajikan tanggapan, menulis ulang, meminta klarifikasi, atau memblokirnya. + **Menulis ulang sejarah.** Jika respons ditulis ulang, catat setiap iterasi: respons asli, prompt penulisan ulang, respons yang ditulis ulang, dan hasil validasi untuk setiap iterasi. + **Versi kebijakan.** Versi pagar pembatas dan versi kebijakan yang digunakan untuk validasi. Ini memastikan Anda dapat mereproduksi hasil validasi nanti. **Contoh: Struktur entri log audit** ``` { "timestamp": "2025-07-21T14:30:00Z", "request_id": "req-abc123", "guardrail_id": "your-guardrail-id", "guardrail_version": "1", "user_question": "Am I eligible for parental leave?", "llm_response": "Yes, you are eligible for parental leave.", "validation_result": "valid", "findings": [ { "type": "valid", "premises": "isFullTime = true, tenureMonths = 24", "claims": "eligibleForParentalLeave = true", "supporting_rules": ["A1B2C3D4E5F6"] } ], "action_taken": "served_response", "rewrite_iterations": 0 } ``` **Tip** Simpan log audit di toko yang tahan lama dan tahan rusak seperti Amazon CloudWatch Logs atau Amazon S3 dengan kunci objek diaktifkan. Untuk skenario kepatuhan, pertimbangkan untuk menggunakan Lake untuk menanyakan log audit di seluruh organisasi Anda.