Halaman ini berlaku untuk Apigee dan Apigee hybrid.
Lihat dokumentasi
Apigee Edge.
Ringkasan
Kebijakan SanitizeUserPrompt melindungi aplikasi AI dari konten berbahaya dengan membersihkan perintah pengguna yang dikirim ke model AI generatif. Kebijakan ini menggunakan Model Armor untuk mengevaluasi perintah pengguna terkait konten berbahaya, sehingga memungkinkan perlindungan native untuk beban kerja AI menggunakan Apigee. Model Armor adalah Google Cloud layanan yang menawarkan langkah-langkah keamanan dan keselamatan AI untuk mengurangi risiko yang terkait dengan model bahasa besar (LLM).
Kebijakan ini digunakan bersama dengan kebijakan SanitizeModelResponse.
Kebijakan ini adalah Kebijakan yang dapat diperluas dan penggunaan kebijakan ini mungkin memiliki implikasi biaya atau penggunaan, bergantung pada lisensi Apigee Anda. Untuk informasi tentang jenis kebijakan dan implikasi penggunaan, lihat Jenis kebijakan.
Sebelum memulai
Sebelum menggunakan kebijakan SanitizeUserPrompt, Anda harus menyelesaikan tugas berikut:
- Buat template Model Armor. Langkah ini harus diselesaikan sebelum Anda membuat kebijakan SanitizeUserPrompt.
- Tetapkan endpoint API untuk layanan Model Armor.
- Buat kebijakan SanitizeModelResponse. Tugas ini harus diselesaikan sebelum Anda men-deploy kebijakan SanitizeUserPrompt.
Peran yang diperlukan
Untuk mendapatkan izin yang diperlukan untuk menerapkan dan menggunakan kebijakan SanitizeUserPrompt, minta administrator untuk memberi Anda peran IAM berikut di akun layanan yang Anda gunakan untuk men-deploy proxy Apigee:
-
Model Armor User (
roles/modelarmor.user
) -
Model Armor Viewer (
roles/modelarmor.viewer
)
Untuk mengetahui informasi selengkapnya tentang cara memberikan peran, lihat Mengelola akses ke project, folder, dan organisasi.
Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.
Mengaktifkan API
Enable the Model Armor API.
Elemen <SanitizeUserPrompt>
Menentukan kebijakan SanitizeUserPrompt.
Nilai Default | Lihat tab Kebijakan Default, di bawah |
Wajib? | Wajib |
Jenis | Objek kompleks |
Elemen Induk | T/A |
Elemen Turunan |
<DisplayName> <IgnoreUnresolvedVariables> <TemplateName> <UserPromptSource> |
Elemen <SanitizeUserPrompt>
menggunakan sintaksis berikut:
Sintaks
<SanitizeUserPrompt async="false" continueOnError="false" enabled="true" name="sanitize-text"> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> <DisplayName>Sanitize-Text-sample</DisplayName> <ModelArmor> <TemplateName>projects/{project}/locations/{location}/templates/{template-name}</TemplateName> </ModelArmor> <UserPromptSource>{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}</UserPromptSource> </SanitizeUserPrompt>
Kebijakan Default
Contoh berikut menunjukkan setelan default saat Anda menambahkan kebijakan SanitizeUserPrompt ke alur permintaan di UI Apigee:
<SanitizeUserPrompt async="false" continueOnError="false" enabled="true" name="sanitize-text"> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> <DisplayName>Sanitize-Text-sample</DisplayName> <ModelArmor> <TemplateName>projects/{project}/locations/{location}/templates/{template-name}</TemplateName> </ModelArmor> <UserPromptSource>{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}</UserPromptSource> </SanitizeUserPrompt>
Saat Anda menyisipkan kebijakan SanitizeUserPrompt baru menggunakan UI Apigee, template akan berisi stub untuk semua kemungkinan operasi. Lihat di bawah untuk mengetahui informasi tentang elemen yang diperlukan.
Elemen ini memiliki atribut berikut yang umum untuk semua kebijakan:
Atribut | Default | Wajib? | Deskripsi |
---|---|---|---|
name |
T/A | Wajib |
Nama internal kebijakan. Nilai atribut Secara opsional, gunakan elemen |
continueOnError |
false | Opsional | Tetapkan ke false untuk menampilkan error saat kebijakan gagal. Perilaku ini wajar terjadi untuk
sebagian besar kebijakan. Tetapkan ke true agar eksekusi alur berlanjut meskipun setelah kebijakan gagal. Lihat juga:
|
enabled |
benar | Opsional | Tetapkan ke true untuk menerapkan kebijakan. Tetapkan ke false untuk menonaktifkan
kebijakan. Kebijakan tidak akan diterapkan meskipun tetap terlampir ke alur. |
async |
false | Tidak digunakan lagi | Atribut ini tidak digunakan lagi. |
Tabel berikut memberikan deskripsi tingkat tinggi tentang elemen turunan <SanitizeUserPrompt>
:
Elemen Turunan | Wajib? | Deskripsi |
---|---|---|
<DisplayName> |
Opsional | Nama kebijakan. |
<IgnoreUnresolvedVariables> |
Opsional | Menentukan apakah pemrosesan berhenti jika variabel yang digunakan untuk nama template atau payload Model Armor tidak terselesaikan. |
<ModelArmor> |
Wajib | Berisi informasi yang diperlukan untuk menentukan template Model Armor. |
<UserPromptSource> |
Opsional | Lokasi payload untuk teks perintah pengguna yang akan diekstrak. Hanya nilai teks string yang didukung.
Kolom ini mendukung sintaksis template pesan Apigee, termasuk penggunaan variabel atau fungsi Jalur JSON. Contoh: {jsonpath('$.input.prompt.text',request.content,false)} |
Contoh
Bagian ini memberikan contoh penggunaan <SanitizeUserPrompt>
.
Contoh ini menggunakan semua nilai default untuk deteksi model dan ekstraksi perintah:
<SanitizeUserPrompt async="false" continueOnError="false" enabled="true" name="sanitize-text"> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> <DisplayName>Sanitize-Text-sample</DisplayName> <ModelArmor> <TemplateName>projects/{project}/locations/{location}/templates/{template-name}</TemplateName> </ModelArmor> </SanitizeUserPrompt>
Referensi elemen turunan
Bagian ini menjelaskan elemen turunan <SanitizeUserPrompt>
.
<DisplayName>
Gunakan selain atribut name
untuk memberi label pada kebijakan di editor proxy UI pengelolaan dengan nama yang berbeda dan lebih terdengar alami.
Elemen <DisplayName>
umum untuk semua kebijakan.
Nilai Default | T/A |
Wajib? | Opsional. Jika Anda menghilangkan <DisplayName> , nilai atribut name kebijakan akan digunakan. |
Jenis | String |
Elemen Induk | <PolicyElement> |
Elemen Turunan | Tidak ada |
Elemen <DisplayName>
menggunakan sintaksis berikut:
Sintaks
<PolicyElement> <DisplayName>POLICY_DISPLAY_NAME</DisplayName> ... </PolicyElement>
Contoh
<PolicyElement> <DisplayName>My Validation Policy</DisplayName> </PolicyElement>
Elemen <DisplayName>
tidak memiliki atribut atau elemen turunan.
<IgnoreUnresolvedVariables>
Menentukan apakah pemrosesan berhenti saat variabel tidak terselesaikan. Tetapkan ke
true
untuk mengabaikan variabel yang belum terselesaikan dan melanjutkan pemrosesan.
Nilai Default | Salah |
Wajib? | Opsional |
Jenis | Boolean |
Elemen Induk |
<SanitizeUserPrompt>
|
Elemen Turunan | Tidak ada |
<ModelArmor>
Berisi informasi yang diperlukan untuk menentukan template Model Armor.
Nilai Default | T/A |
Wajib? | Wajib |
Jenis | String |
Elemen Induk | |
Elemen Turunan |
<TemplateName>
|
Elemen <ModelArmor>
menggunakan sintaksis berikut:
Sintaks
<ModelArmor> <TemplateName>projects/{project}/locations/{location}/templates/{template-name}</TemplateName> </ModelArmor>
Contoh
Contoh ini menggunakan variabel alur Apigee untuk mengisi informasi yang diperlukan.
<ModelArmor> <TemplateName>projects/{organization.name}/locations/{system.region.name}/templates/{id}</TemplateName> </ModelArmor>
Tabel berikut memberikan deskripsi tingkat tinggi tentang elemen turunan
<ModelArmor>
.
Elemen Turunan | Wajib? | Deskripsi |
---|---|---|
<TemplateName> |
Wajib | String Template Model Armor yang digunakan untuk membersihkan perintah pengguna. Nilai ini dapat dibuat template menggunakan variabel alur Apigee berikut: projects/{organization.name}/locations/{system.region.name}/templates/{id} |
<UserPromptSource>
Lokasi payload untuk teks perintah pengguna yang akan diekstrak. Kolom ini mendukung sintaksis template pesan Apigee, termasuk penggunaan variabel atau fungsi Jalur JSON. Contoh:
{jsonpath('$.input.prompt.text',request.content,false)}
Nilai Default | {jsonPath($.contents[-1].parts[-1].text,request.content,true)} |
Wajib? | Opsional |
Jenis | String |
Elemen Induk |
<SanitizeUserPrompt>
|
Elemen Turunan | Tidak ada |
Variabel alur
Variabel alur dapat digunakan untuk mengonfigurasi perilaku runtime dinamis untuk kebijakan dan alur, berdasarkan header HTTP atau konten pesan, atau konteks yang tersedia di Alur. Untuk mengetahui informasi selengkapnya tentang variabel alur, lihat Referensi variabel alur.
Kebijakan ini dapat menetapkan variabel hanya baca ini selama eksekusi.
Nama variabel | Deskripsi |
---|---|
SanitizeUserPrompt.POLICY_NAME.templateUsed |
Menentukan template armor model yang digunakan. Misalnya:
projects/myproject/locations/us-west1/templates/mytemplate |
SanitizeUserPrompt.POLICY_NAME.userPrompt |
Menentukan konten perintah yang digunakan untuk panggilan ke Model Armor guna membersihkan konten. |
SanitizeUserPrompt.POLICY_NAME.modelResponse |
Menentukan konten respons LLM yang digunakan untuk panggilan ke Model Armor guna membersihkan konten. |
SanitizeUserPrompt.POLICY_NAME.responseFromModelArmor |
Menentukan respons JSON dari Model Armor. |
SanitizeUserPrompt.POLICY_NAME.filterMatchState |
Menentukan apakah filter cocok. Nilai yang valid mencakup MATCH_FOUND dan NO_MATCH_FOUND . |
SanitizeUserPrompt.POLICY_NAME.invocationResult |
Kolom yang menunjukkan hasil pemanggilan, terlepas dari status kecocokan. Dapat memiliki
hal berikut:
|
SanitizeUserPrompt.POLICY_NAME.raiFilterResult.executionState |
Hasil eksekusi filter Rai. Nilai yang valid mencakup EXECUTION_SUCCESS dan EXECUTION_SKIPPED . |
SanitizeUserPrompt.POLICY_NAME.raiFilterResult.matchState |
Status pencocokan filter Rai. Nilai yang valid mencakup MATCH_FOUND dan NO_MATCH_FOUND . |
SanitizeUserPrompt.POLICY_NAME.sdpFilterResult.inspectResult.executionState |
Status eksekusi hasil pemeriksaan filter SDP. Nilai yang valid mencakup EXECUTION_SUCCESS dan EXECUTION_SKIPPED . |
SanitizeUserPrompt.POLICY_NAME.sdpFilterResult.inspectResult.matchState |
Status pencocokan hasil inspeksi filter SDP. Nilai yang valid mencakup MATCH_FOUND dan NO_MATCH_FOUND . |
SanitizeUserPrompt.POLICY_NAME.sdpFilterResult.deidentifyResult.executionState |
Filter SDP mengidentifikasi status eksekusi hasil. Nilai yang valid mencakup EXECUTION_SUCCESS dan EXECUTION_SKIPPED . |
SanitizeUserPrompt.POLICY_NAME.sdpFilterResult.deidentifyResult.matchState |
Filter SDP de mengidentifikasi status kecocokan hasil. Nilai yang valid mencakup MATCH_FOUND dan NO_MATCH_FOUND . |
SanitizeUserPrompt.POLICY_NAME.piAndJailbreakFilterResult.executionState |
Status eksekusi hasil filter injeksi perintah dan Jailbreak. Nilai yang valid mencakup EXECUTION_SUCCESS dan EXECUTION_SKIPPED . |
SanitizeUserPrompt.POLICY_NAME.piAndJailbreakFilterResult.matchState |
Hasil filter injeksi perintah dan Jailbreak cocok dengan status. Nilai yang valid mencakup MATCH_FOUND dan NO_MATCH_FOUND . |
SanitizeUserPrompt.POLICY_NAME.csamFilterFilterResult.executionState |
Status eksekusi filter CSAM. Nilai yang valid mencakup EXECUTION_SUCCESS dan EXECUTION_SKIPPED . |
SanitizeUserPrompt.POLICY_NAME.csamFilterFilterResult.matchState |
Status pencocokan filter CSAM. Nilai yang valid mencakup MATCH_FOUND dan NO_MATCH_FOUND . |
SanitizeUserPrompt.POLICY_NAME.maliciousUriFilterResult.executionState |
Status eksekusi filter URI berbahaya. Nilai yang valid mencakup EXECUTION_SUCCESS dan EXECUTION_SKIPPED . |
SanitizeUserPrompt.POLICY_NAME.maliciousUriFilterResult.matchState |
Status pencocokan filter URI berbahaya. Nilai yang valid mencakup MATCH_FOUND dan NO_MATCH_FOUND . |
SanitizeUserPrompt.POLICY_NAME.sanitizationMetadata.errorCode |
Kode Error kustom yang diganti jika ada dalam respons Model Armor. |
SanitizeUserPrompt.POLICY_NAME.sanitizationMetadata.errorMessage |
Kode Error kustom yang diganti jika ada dalam respons Model Armor. |
SanitizeUserPrompt.POLICY_NAME.csamFilterMatched/code> |
Nilai boolean yang menunjukkan apakah filter CSAM cocok. |
SanitizeUserPrompt.POLICY_NAME.maliciousURIs |
Daftar URI berbahaya yang ditambahkan yang terdeteksi oleh filter URI berbahaya. |
SanitizeUserPrompt.POLICY_NAME.maliciousURIsDetected |
Nilai boolean yang menunjukkan apakah filter URI berbahaya cocok. |
SanitizeUserPrompt.POLICY_NAME.matchesFound |
Nilai boolean yang menunjukkan apakah ada filter yang cocok. |
SanitizeUserPrompt.POLICY_NAME.promptInjectionDetected |
Nilai boolean yang menunjukkan apakah filter injeksi perintah cocok. |
SanitizeUserPrompt.POLICY_NAME.promptInjectionConfidence |
Tingkat keyakinan deteksi injeksi perintah. |
SanitizeUserPrompt.POLICY_NAME.raiMatchesFound |
Nilai boolean yang menunjukkan apakah filter RAI cocok. |
SanitizeUserPrompt.POLICY_NAME.requestSentToModelArmor |
Nilai boolean yang menunjukkan apakah permintaan dikirim ke Model Armor. |
SanitizeUserPrompt.POLICY_NAME.sanitizeOperation |
Menentukan operasi yang dilakukan oleh kebijakan. Nilai yang valid mencakup SANITIZE_USER_PROMPT
dan SANITIZE_MODEL_RESPONSE . |
Referensi error
Bagian ini menjelaskan kode error dan pesan error yang ditampilkan serta variabel error yang ditetapkan oleh Apigee khusus untuk kebijakan SanitizeUserPrompt. Informasi ini penting untuk diketahui jika Anda mengembangkan aturan error untuk menangani error. Untuk mempelajari lebih lanjut, lihat Yang perlu Anda ketahui tentang error kebijakan dan Menangani error.
Error runtime
Error ini dapat terjadi saat kebijakan dieksekusi.
Kode kerusakan | Status HTTP | Penyebab |
---|---|---|
steps.sanitize.user.prompt.response.FilterMatched |
400 |
Error ini terjadi jika perintah pengguna tidak lulus pemeriksaan template Model Armor. |
steps.sanitize.user.prompt.SanitizationResponseParsingFailed |
500 |
Error ini terjadi jika respons Model Armor tidak dapat diuraikan. |
steps.sanitize.user.prompt.FailedToExtractUserPrompt |
500 |
Error ini terjadi jika ekstraksi perintah pengguna otomatis untuk nilai default gagal. |
steps.sanitize.user.prompt.InternalError |
500 |
Error ini terjadi jika ada error server internal. |
steps.sanitize.modelarmor.ModelArmorTemplateNameExtractionFailed |
500 |
Error ini terjadi jika nama template tidak dapat di-resolve. |
steps.sanitize.modelarmor.AuthenticationFailure |
500 |
Error ini terjadi jika akun layanan tidak memiliki izin untuk memanggil Model Armor API. |
steps.sanitize.modelarmor.ModelArmorAPIFailed |
500 |
Error ini terjadi jika Model Armor API menampilkan error. |
steps.sanitize.modelarmor.ModelArmorCalloutError |
500 |
Error ini terjadi jika panggilan Model Armor API gagal. |
steps.sanitize.modelarmor.ServiceUnavailable |
500 |
Error ini terjadi jika layanan Model Armor tidak tersedia. |
Error saat deployment
Error ini dapat terjadi saat Anda men-deploy proxy yang berisi kebijakan ini.
Nama error | Penyebab |
---|---|
The ModelArmor/TemplateName element is required. |
Terjadi jika elemen <TemplateName> di <ModelArmor> tidak ada. |
The TemplateName element value is required. |
Terjadi jika nilai <TemplateName> kosong. |
Variabel error
Variabel ini ditetapkan saat kebijakan ini memicu error saat runtime. Untuk mengetahui informasi selengkapnya, lihat Yang perlu Anda ketahui tentang error kebijakan.
Variabel | Di mana | Contoh |
---|---|---|
fault.name="FAULT_NAME" |
FAULT_NAME adalah nama error, seperti yang tercantum dalam tabel Runtime errors di atas. Nama kerusakan adalah bagian terakhir dari kode kerusakan. | fault.name Matches "UnresolvedVariable" |
SanitizeUserPrompt.POLICY_NAME.failed |
POLICY_NAME adalah nama kebijakan yang ditentukan pengguna yang menampilkan error. | SanitizeUserPrompt.sanitize-prompt.failed = true |
Contoh respons error
{ "fault": { "faultstring": "SanitizeUserPrompt[sanitize-prompt]: unable to resolve variable [variable_name]", "detail": { "errorcode": "steps.sanitizeuserprompt.UnresolvedVariable" } } }
Contoh aturan error
<FaultRule name="SanitizeUserPrompt Faults"> <Step> <Name>SUP-CustomSetVariableErrorResponse</Name> <Condition>(fault.name = "SetVariableFailed")</Condition> </Step> <Condition>(sanitizeuserprompt.failed = true)</Condition> </FaultRule>
Kode error dan pesan error template Model Armor
Template Model Armor mendukung penggantian kode error dan pesan error yang ditampilkan oleh permintaan API kebijakan SanitizeUserPrompt. Jika pengguna menetapkan penggantian, kode error dan pesan error Model Armor akan mengisi variabel alur.
Misalnya, respons dengan kode dan pesan error Model Armor dapat terlihat seperti berikut:
{ "sanitizationResult": { "filterMatchState": "MATCH_FOUND", "filterResults": {...}, "sanitizationMetadata": { "errorCode": "890", "errorMessage": "get out" }, "invocationResult": "SUCCESS" } }
Skema
Setiap jenis kebijakan ditentukan oleh skema XML (.xsd
). Sebagai referensi, skema kebijakan
tersedia di GitHub.