Kebijakan SanitizeUserPrompt

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:

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.

Enable the 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 name dapat berisi huruf, angka, spasi, tanda hubung, garis bawah, dan titik. Nilai ini tidak boleh melebihi 255 karakter.

Secara opsional, gunakan elemen <DisplayName> untuk memberi label pada kebijakan di editor proxy UI pengelolaan dengan nama bahasa alami yang berbeda.

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:
  • BERHASIL: Semua filter berhasil dijalankan.
  • SEBAGIAN: Beberapa filter dilewati atau gagal dieksekusi.
  • KEGAGALAN: Semua filter dilewati atau gagal dieksekusi.
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.