Kebijakan SanitizeModelResponse

Halaman ini berlaku untuk Apigee dan Apigee Hybrid.

Lihat dokumentasi Apigee Edge.

Pratinjau

Fitur ini tunduk pada "Persyaratan Penawaran Pra-GA" di bagian Persyaratan Layanan Umum dari Persyaratan Khusus Layanan. Fitur pra-GA tersedia "sebagaimana adanya" dan mungkin memiliki dukungan terbatas. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran.

Kebijakan SanitizeModelResponse melindungi klien AI dari konten berbahaya atau menyinggung dengan membersihkan respons dari model AI generatif. Kebijakan ini menggunakan Model Armor untuk mengevaluasi respons model terkait konten berbahaya atau menyinggung, sehingga memungkinkan perlindungan native untuk klien dan beban kerja AI menggunakan Apigee. Model Armor adalah Google Cloud layanan yang menawarkan langkah-langkah keamanan dan keselamatan AI untuk memitigasi risiko yang terkait dengan model bahasa besar (LLM).

Kebijakan ini digunakan bersama dengan SanitizeModelResponse policy.

Kebijakan ini adalah Kebijakan yang dapat diperluas dan penggunaan kebijakan ini mungkin memiliki implikasi biaya atau penggunaan, bergantung pada lisensi Apigee Anda. Untuk mengetahui informasi tentang jenis kebijakan dan implikasi penggunaannya, lihat Jenis kebijakan.

Sebelum memulai

Sebelum menggunakan kebijakan SanitizeModelResponse, Anda harus menyelesaikan tugas berikut:

• Buat template Model Armor. Langkah ini harus diselesaikan sebelum Anda membuat kebijakan SanitizeModelResponse.
• Tetapkan endpoint API untuk layanan Model Armor.

Peran yang diperlukan

Untuk mendapatkan izin yang diperlukan untuk menerapkan dan menggunakan kebijakan SanitizeModelResponse, minta administrator untuk memberi Anda peran IAM berikut pada akun layanan yang Anda gunakan untuk men-deploy proxy Apigee:

• Pengguna Model Armor (roles/modelarmor.user)
• Penampil Model Armor (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 kustom atau peran yang telah ditentukan lainnya.

Mengaktifkan API

Enable the Model Armor APIs.

Enable the APIs

Elemen <SanitizeModelResponse>

Menentukan kebijakan SanitizeModelResponse.

Nilai Default	Lihat tab Kebijakan Default di bawah
Wajib?	Wajib
Jenis	Objek kompleks
Elemen Induk	T/A
Elemen Turunan	<DisplayName> <IgnoreUnresolvedVariables> <TemplateName> <UserPromptSource> <LLMResponseSource>

Elemen <SanitizeModelResponse> menggunakan sintaksis berikut:

Sintaks

<SanitizeModelResponse async="false" continueOnError="false" enabled="true" name="sanitize-response">
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <DisplayName>sanitize-response-sample</DisplayName>
  <ModelArmor>
    <TemplateName>projects/{project}/locations/{location}/templates/{template-name}</TemplateName>
  </ModelArmor>
  <UserPromptSource>{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}</UserPromptSource>
  <LLMResponseSource>{jsonPath($.candidates[-1].content.parts,response.content,true)}</LLMResponseSource>
</SanitizeModelResponse>

Kebijakan Default

Contoh berikut menunjukkan setelan default saat Anda menambahkan kebijakan SanitizeModelResponse ke alur permintaan di UI Apigee:

<SanitizeModelResponse async="false" continueOnError="false" enabled="true" name="sanitize-response">
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <DisplayName>sanitize-response-sample</DisplayName>
  <ModelArmor>
    <TemplateName>projects/{project}/locations/{location}/templates/{template-name}</TemplateName>
  </ModelArmor>
  <UserPromptSource>{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}</UserPromptSource>
  <LLMResponseSource>{jsonPath($.candidates[-1].content.parts,response.content,true)}</LLMResponseSource>
</SanitizeModelResponse>

Saat Anda menyisipkan kebijakan SanitizeModelResponse baru menggunakan UI Apigee, template berisi stub untuk semua kemungkinan operasi. Lihat di bawah untuk mengetahui informasi tentang elemen yang diperlukan.

This element has the following attributes that are common to all policies:

Attribute	Default	Required?	Description
name	N/A	Required	The internal name of the policy. The value of the name attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters. Optionally, use the <DisplayName> element to label the policy in the management UI proxy editor with a different, natural-language name.
continueOnError	false	Optional	Set to false to return an error when a policy fails. This is expected behavior for most policies. Set to true to have flow execution continue even after a policy fails. See also: Fault rules are triggered ONLY in an error state (about continueOnError) Handling faults within the current flow
enabled	true	Optional	Set to true to enforce the policy. Set to false to turn off the policy. The policy will not be enforced even if it remains attached to a flow.
async	false	Deprecated	This attribute is deprecated.

Tabel berikut memberikan deskripsi umum tentang elemen turunan <SanitizeModelResponse>:

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.
<TemplateName>	Wajib	Template Model Armor yang digunakan untuk menyaring respons LLM. Nilai ini dapat dibuat template menggunakan variabel alur Apigee berikut: projects/{organization.name}/locations/{system.region.name}/templates/{id}
<UserPromptSource>	Wajib	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 JSON Path . Contoh: {jsonpath('$.contents[-1].parts[-1].text',request.content,false)}
<LLMResponseSource>	Wajib	Lokasi payload untuk teks respons LLM yang akan diekstrak. Hanya nilai teks string yang didukung. Kolom ini mendukung sintaksis template pesan Apigee, termasuk penggunaan variabel atau fungsi JSON Path . Contoh: {jsonpath('$.input.prompt.text',request.content,false)}

Referensi elemen turunan

Bagian ini menjelaskan elemen turunan <SanitizeModelResponse>.

<DisplayName>

Use in addition to the name attribute to label the policy in the management UI proxy editor with a different, more natural-sounding name.

The <DisplayName> element is common to all policies.

Default Value	N/A
Required?	Optional. If you omit <DisplayName>, the value of the policy's name attribute is used.
Type	String
Parent Element	<PolicyElement>
Child Elements	None

The <DisplayName> element uses the following syntax:

Syntax

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

Example

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

The <DisplayName> element has no attributes or child elements.

<IgnoreUnresolvedVariables>

Menentukan apakah pemrosesan berhenti saat variabel tidak terselesaikan. Setel ke true untuk mengabaikan variabel yang belum terselesaikan dan melanjutkan pemrosesan.

Nilai Default	Salah
Wajib?	Opsional
Jenis	Boolean
Elemen Induk	<SanitizeModelResponse>
Elemen Turunan	Tidak ada

<TemplateName>

Template Model Armor.

Nilai Default	T/A
Wajib?	Wajib
Jenis	String
Elemen Induk	<SanitizeModelResponse>
Elemen Turunan	Tidak ada

Elemen <TemplateName> 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>

<UserPromptSource>

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 JSON Path. Contoh:

{jsonpath('$.input.prompt.text',request.content,false)}

Nilai Default	{jsonPath($.contents[-1].parts[-1].text,request.content,true)}
Wajib?	Wajib
Jenis	String
Elemen Induk	<SanitizeModelResponse>
Elemen Turunan	Tidak ada

<LLMResponseSource>

Lokasi payload untuk respons LLM yang akan diekstrak. Hanya nilai teks string yang didukung.

Kolom ini mendukung sintaksis template pesan Apigee, termasuk penggunaan variabel atau fungsi JSON Path. Contoh:

{jsonpath('$.input.prompt.text',request.content,false)}

Nilai Default	{jsonPath($.candidates[-1].content.parts,response.content,true)}
Wajib?	Wajib
Jenis	String
Elemen Induk	<SanitizeModelResponse>
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 dapat menetapkan variabel hanya baca ini selama eksekusi.

Nama variabel	Deskripsi
SanitizeModelResponse.POLICY_NAME.templateUsed	Menentukan template pelindung model mana yang digunakan. Contoh: projects/myproject/locations/us-west1/templates/mytemplate
SanitizeModelResponse.POLICY_NAME.userPrompt	Menentukan konten perintah yang digunakan untuk panggilan ke Model Armor guna membersihkan konten.
SanitizeModelResponse.POLICY_NAME.modelResponse	Menentukan konten respons LLM yang digunakan untuk panggilan ke Model Armor guna membersihkan konten.
SanitizeModelResponse.POLICY_NAME.responseFromModelArmor	Menentukan respons json dari Model Armor. Model Armor.
SanitizeModelResponse.POLICY_NAME.filterMatchState	Menentukan apakah filter cocok. Nilai yang valid mencakup MATCH_FOUND dan NO_MATCH_FOUND.
SanitizeModelResponse.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.
SanitizeModelResponse.POLICY_NAME.raiFilterResult.executionState	Hasil eksekusi filter Rai. Nilai yang valid mencakup EXECUTION_SUCCESS dan EXECUTION_SKIPPED.
SanitizeModelResponse.POLICY_NAME.raiFilterResult.matchState	Status kecocokan filter Rai. Nilai yang valid mencakup MATCH_FOUND dan NO_MATCH_FOUND.
SanitizeModelResponse.POLICY_NAME.sdpFilterResult.inspectResult.executionState	Status eksekusi hasil pemeriksaan filter SDP. Nilai yang valid mencakup EXECUTION_SUCCESS dan EXECUTION_SKIPPED.
SanitizeModelResponse.POLICY_NAME.sdpFilterResult.inspectResult.matchState	Status kecocokan hasil pemeriksaan filter SDP. Nilai yang valid mencakup MATCH_FOUND dan NO_MATCH_FOUND.
SanitizeModelResponse.POLICY_NAME.sdpFilterResult.deidentifyResult.executionState	Status eksekusi hasil penghapusan identitas filter SDP. Nilai yang valid mencakup EXECUTION_SUCCESS dan EXECUTION_SKIPPED.
SanitizeModelResponse.POLICY_NAME.sdpFilterResult.deidentifyResult.matchState	Status kecocokan hasil penghapusan identitas filter SDP. Nilai yang valid mencakup MATCH_FOUND dan NO_MATCH_FOUND.
SanitizeModelResponse.POLICY_NAME.piAndJailbreakFilterResult.executionState	Status eksekusi hasil filter Prompt injection dan Jailbreak. Nilai yang valid mencakup EXECUTION_SUCCESS dan EXECUTION_SKIPPED.
SanitizeModelResponse.POLICY_NAME.piAndJailbreakFilterResult.matchState	Status kecocokan hasil filter Prompt injection dan Jailbreak. Nilai yang valid mencakup MATCH_FOUND dan NO_MATCH_FOUND.
SanitizeModelResponse.POLICY_NAME.csamFilterFilterResult.executionState	Status eksekusi filter CSAM. Nilai yang valid mencakup EXECUTION_SUCCESS dan EXECUTION_SKIPPED.
SanitizeModelResponse.POLICY_NAME.csamFilterFilterResult.matchState	Status kecocokan filter CSAM. Nilai yang valid mencakup MATCH_FOUND dan NO_MATCH_FOUND.
SanitizeModelResponse.POLICY_NAME.maliciousUriFilterResult.executionState	Status eksekusi filter URI berbahaya. Nilai yang valid mencakup EXECUTION_SUCCESS dan EXECUTION_SKIPPED.
SanitizeModelResponse.POLICY_NAME.maliciousUriFilterResult.matchState	Status kecocokan filter URI berbahaya. Nilai yang valid mencakup MATCH_FOUND dan NO_MATCH_FOUND.
SanitizeModelResponse.POLICY_NAME.sanitizationMetadata.errorCode	Kode Error yang diganti secara kustom jika ada dalam respons Model Armor.
SanitizeModelResponse.POLICY_NAME.sanitizationMetadata.errorMessage	Kode Error yang diganti secara kustom jika ada dalam respons Model Armor.
SanitizeModelResponse.POLICY_NAME.csamFilterMatched/code>	Nilai boolean yang menunjukkan apakah filter CSAM cocok.
SanitizeModelResponse.POLICY_NAME.maliciousURIs	Daftar URI berbahaya yang ditambahkan yang terdeteksi oleh filter URI berbahaya.
SanitizeModelResponse.POLICY_NAME.maliciousURIsDetected	Nilai boolean yang menunjukkan apakah filter URI berbahaya cocok.
SanitizeModelResponse.POLICY_NAME.matchesFound	Nilai boolean yang menunjukkan apakah ada filter yang cocok.
SanitizeModelResponse.POLICY_NAME.promptInjectionDetected	Nilai boolean yang menunjukkan apakah filter injeksi perintah cocok.
SanitizeModelResponse.POLICY_NAME.promptInjectionConfidence	Tingkat keyakinan deteksi serangan injeksi perintah.
SanitizeModelResponse.POLICY_NAME.raiMatchesFound	Nilai boolean yang menunjukkan apakah filter RAI cocok.
SanitizeModelResponse.POLICY_NAME.requestSentToModelArmor	Nilai boolean yang menunjukkan apakah permintaan dikirim ke Model Armor.
SanitizeModelResponse.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 kesalahan dan pesan error yang ditampilkan serta variabel kesalahan yang ditetapkan oleh Apigee khusus untuk kebijakan <SanitizeModelResponse>. Informasi ini penting untuk diketahui jika Anda mengembangkan aturan kesalahan untuk menangani kesalahan. Untuk mempelajari lebih lanjut, lihat Yang perlu Anda ketahui tentang error kebijakan dan Menangani kesalahan.

Error runtime

Kode kesalahan	Status HTTP	Penyebab
steps.sanitize.model.response.FilterMatched	400	Error ini terjadi jika perintah pengguna tidak lulus pemeriksaan template Model Armor.
steps.sanitize.model.response.SanitizationResponseParsingFailed	500	Error ini terjadi jika respons Model Armor tidak dapat diuraikan.
steps.sanitize.model.response.FailedToExtractUserPrompt	500	Error ini terjadi jika ekstraksi perintah pengguna otomatis untuk nilai default gagal.
steps.sanitize.model.response.FailedToExtractLLMResponse	500	Error ini terjadi jika ekstraksi respons model otomatis untuk nilai default gagal.
steps.sanitize.model.response.InternalError	500	Error ini terjadi jika ada error server internal.
steps.sanitize.model.response.ModelArmorTemplateNameExtractionFailed	500	Error ini terjadi jika nama template tidak dapat diselesaikan.
steps.sanitize.model.response.AuthenticationFailure	500	Error ini terjadi jika akun layanan tidak memiliki izin untuk memanggil Model Armor API.
steps.sanitize.model.response.ModelArmorAPIFailed	500	Error ini terjadi jika Model Armor API menampilkan error.
steps.sanitize.model.response.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 kesalahan

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 kesalahan, seperti yang tercantum dalam tabel Error runtime di atas. Nama kesalahan adalah bagian terakhir dari kode kesalahan.	fault.name Matches "UnresolvedVariable"
SanitizeModelResponse.POLICY_NAME.failed	POLICY_NAME adalah nama kebijakan yang ditentukan pengguna yang menyebabkan kesalahan.	SanitizeModelResponse.sanitize-response.failed = true

Contoh respons error

Catatan: Untuk penanganan error, praktik terbaiknya adalah menangkap bagian errorcode dari respons error. Jangan mengandalkan teks di faultstring, karena dapat berubah.

{
  "fault": {
    "faultstring": "SanitizeModelResponse[sanitize-response]: unable to resolve variable [variable_name]",
    "detail": {
      "errorcode": "steps.sanitizemodelresponse.UnresolvedVariable"
    }
  }
}

Contoh aturan kesalahan

<FaultRule name="SanitizeModelResponse Faults">
    <Step>
        <Name>SMR-CustomSetVariableErrorResponse</Name>
        <Condition>(fault.name = "SetVariableFailed")</Condition>
    </Step>
    <Condition>(sanitizemodelresponse.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 SanitizeModelResponse. 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.