Menetapkan versi filter

Dokumen ini menjelaskan cara kerja versi filter Model Armor dan cara menginstruksikan Model Armor untuk menggunakan versi filter atau alias versi filter tertentu dalam operasi.

Model Armor menggunakan filter untuk mendeteksi dan memblokir konten berbahaya, data sensitif, URL berbahaya, materi pelecehan seksual terhadap anak-anak (CSAM), dan serangan injeksi perintah dalam perintah dan respons LLM. Untuk mengetahui informasi selengkapnya, lihat Filter Model Armor.

Versi filter Model Armor memberikan stabilitas untuk workload produksi dan akses ke model deteksi ancaman terbaru. Anda harus mengonfigurasi satu versi filter di tingkat template. Anda tidak dapat menentukan versi yang berbeda untuk setiap filter.

Kapan harus mengonfigurasi versi dan alias filter

Berikut adalah beberapa kasus penggunaan umum:

• Mengunci perilaku pemfilteran deterministik: Tetapkan template ke versi filter tertentu untuk mencegah perubahan logika deteksi ancaman dalam sistem yang sangat penting.
• Menerima update keamanan otomatis: Gunakan alias Stable untuk mengadopsi model deteksi ancaman yang diupdate secara otomatis saat lulus validasi.
• Menguji kemampuan deteksi mendatang: Gunakan alias Latest di lingkungan pra-produksi untuk mengevaluasi aturan filter baru terhadap pola traffic dunia nyata.
• Mengaktifkan siklus peluncuran yang dapat diprediksi: Validasi workload terhadap versi filter yang baru dirilis sebelum mengupdate template produksi secara manual.

Alias versi

Dalam template Model Armor, Anda dapat menggunakan alias untuk menentukan versi filter yang Anda inginkan. Alias mewakili tahap dalam siklus proses versi. Setiap alias ditetapkan ke versi yang sesuai seiring berjalannya siklus proses.

Jika Anda memilih alias, template akan menggunakan versi yang ditetapkan untuk alias tersebut. Saat versi dasar untuk alias tersebut diupdate (misalnya, saat versi baru dipromosikan ke Stable), template yang menggunakan alias tersebut akan otomatis menggunakan versi baru. Jika Anda tidak ingin versi filter berubah, arahkan template ke versi filter tertentu.

Anda dapat memilih dari alias berikut:

• Latest: Alias dengan model dan perlindungan terbaru, dengan update rutin terhadap ancaman yang muncul. Alias ini menawarkan tujuan tingkat layanan (SLO) standar, tetapi stabilitasnya dapat bervariasi di berbagai versi. Mode ini cocok untuk pengujian, staging, dan workload yang memprioritaskan model deteksi terbaru daripada perilaku filter yang konsisten.
• Stable: Alias default untuk versi dengan template yang tersedia. Alias ini memberikan logika deteksi yang andal dan tidak berubah, serta cocok untuk lingkungan produksi dan workload yang memerlukan perilaku filter yang tidak berubah. Saat versi baru menjadi Stable, versi Stable sebelumnya akan menjadi Legacy.
• Legacy: Alias untuk versi Stable sebelumnya yang tetap tersedia selama 90 hari setelah versi Stable baru dirilis. Anda dapat memigrasikan sistem produksi ke versi Stable baru kapan saja selama periode ini. Anda tidak dapat membuat template baru menggunakan versi Legacy.
• Retired: Alias untuk versi yang telah melampaui masa tenggang 90 hari dan tidak lagi tersedia. Model Armor menggunakan versi Stable untuk membersihkan panggilan ke template yang masih menggunakan versi Retired.

Filter yang tidak menggunakan versi filter

Setelan versi filter tidak memengaruhi Sensitive Data Protection dan filter URL berbahaya.

Siklus proses versi

Google Cloud memberikan notifikasi tentang perubahan siklus proses versi, termasuk saat versi menjadi Legacy dan tanggal penghentiannya yang akan datang dalam setiap respons Sanitize API. Anda harus memigrasikan template apa pun yang menggunakan versi Legacy ke Stable atau Latest dalam jangka waktu 90 hari.

Contoh berikut menjelaskan siklus proses versi:

1. Rilis (Latest): Google merilis versi filter baru (v2) sebagai Latest.
2. Promosi (Latest ke Stable): Saat Google mempromosikan versi Latest ke Stable (v2 menjadi Stable), hal berikut akan terjadi:
   1. Google memindahkan versi Stable sebelumnya (v1) ke Legacy.
   2. Versi baru (v3) menjadi Latest baru. Google mempromosikan versi setelah menjalani pengujian yang ketat, menunjukkan penggunaan harian yang konsisten, dan memiliki masalah pelanggan yang minimal, atau saat perlindungan ancaman kritis menjadi diperlukan.
3. Penghentian (Legacy hingga Retired): Setelah versi filter tetap dalam status Legacy selama 90 hari, Google akan menghentikannya, dan versi tersebut tidak akan tersedia lagi.

Linimasa rilis versi

Tabel berikut memberikan detail tentang versi filter, termasuk alias, tanggal rilis, tanggal penghentian, dan wilayah yang didukung.

Versi	Alias	Tanggal rilis	Tanggal penghentian	Wilayah yang didukung
v1	Legacy (Stable di asia-northeast3; Legacy mulai 25 September 2026 di australia-southeast2)	30-01-2025	2026-12-17	asia-northeast1 asia-northeast3 (Stable) asia-south1 asia-southeast1 australia-southeast2 (Legacy mulai 25 September 2026) europe-southwest1 europe-west9 northamerica-northeast2 us us-central1 us-east4 us-west1
v2	Legacy	2025-06-19	2026-12-17	eu europe-west1 europe-west2 europe-west3 europe-west4 us-east1
v3	Stable (Stable mulai 25 September 2026 di australia-southeast2)	2026-05-25	—	asia-northeast1 asia-south1 asia-southeast1 australia-southeast2 (Stable mulai 25 September 2026) eu europe-southwest1 europe-west1 europe-west2 europe-west3 europe-west4 europe-west9 northamerica-northeast2 southamerica-east1 us us-central1 us-east1 us-east4 us-west1
v4	Latest	2026-09-18	—	asia-northeast1 asia-south1 asia-southeast1 eu europe-southwest1 europe-west1 europe-west2 europe-west3 europe-west4 europe-west9 northamerica-northeast2 southamerica-east1 us us-central1 us-east1 us-east4 us-west1

Untuk mengetahui informasi tentang perubahan di setiap versi, lihat Histori versi filter.

Perilaku template

Perilaku template bergantung pada versi filter yang digunakan dan mengikuti karakteristik berikut:

• Template tanpa versi: Template tanpa versi yang ditentukan, baik baru maupun yang sudah ada, akan ditetapkan secara default ke versi Stable.

• Template dengan alias Latest atau Stable: Template ini otomatis menggunakan versi yang ditetapkan ke alias ini. Misalnya, saat versi filter baru menjadi versi Stable, template yang menggunakan alias Stable akan berpindah ke versi baru tanpa memerlukan perubahan template.

  Catatan: Anda tidak dapat menetapkan versi filter dalam template ke Legacy atau Retired.

• Template yang menggunakan versi tertentu:

  • Jika versi sesuai dengan versi Latest atau Stable, template akan berperilaku seperti yang diharapkan.
  • Jika versi tersebut sesuai dengan versi Legacy, template akan berperilaku seperti yang diharapkan saat digunakan untuk operasi pembersihan selama periode 90 hari. Setelah 90 hari, versi akan beralih ke fase Retired. Selama fase ini, Anda harus memigrasikan template ke versi Latest atau Stable.

Mengganti versi filter default untuk setelan harga minimum

Dengan setelan dasar, integrasi Gemini Enterprise Agent Platform menggunakan versi filter Stable secara default. Untuk mengganti setelan ini, tentukan template dalam panggilan generateContent ke model Gemini. Untuk melakukannya, buat template dengan versi atau alias filter tertentu di region yang sama dengan tempat Anda berencana mengirim permintaan Gemini.

gcloud

gcloud model-armor templates create TEMPLATE_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --pi-and-jailbreak-filter-settings-enforcement=enabled \
    --filter-version-selector-alias=FILTER_VERSION_ALIAS

Ganti kode berikut:

• TEMPLATE_ID: ID template yang akan dibuat.
• PROJECT_ID: ID project yang memiliki template.
• LOCATION: region untuk menyimpan template Model Armor. Region ini harus sama dengan region tempat Anda berencana mengirim permintaan Gemini; jika tidak, Agent Platform akan menerima error Template not found. Untuk mengetahui daftar region yang didukung untuk integrasi ini, lihat Integrasi dengan Gemini Enterprise Agent Platform.
• FILTER_VERSION_ALIAS: alias versi filter pilihan Anda. Gunakan filter-version-alias-stable atau filter-version-alias-latest.

REST

export TEMPLATE_CONFIG='{
  "filterConfig": {
    "piAndJailbreakFilterSettings": {
      "filterEnforcement": "ENABLED"
    }
  },
  "templateMetadata": {
    "filterVersionSelector": {
      "alias": "FILTER_VERSION_ALIAS"
    }
  }
}'

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d "$TEMPLATE_CONFIG" \
    "https://modelarmor.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/templates?template_id=TEMPLATE_ID"

Ganti kode berikut:

• FILTER_VERSION_ALIAS: alias versi filter pilihan Anda. Gunakan FILTER_VERSION_ALIAS_STABLE atau FILTER_VERSION_ALIAS_LATEST.
• PROJECT_ID: ID project yang memiliki template.
• TEMPLATE_ID: ID template yang akan dibuat.
• LOCATION: region untuk menyimpan template Model Armor. Region ini harus sama dengan region tempat Anda berencana mengirim permintaan Gemini; jika tidak, Agent Platform akan menerima error Template not found. Untuk mengetahui daftar region yang didukung untuk integrasi ini, lihat Integrasi dengan Gemini Enterprise Agent Platform.

Berikan ID template di objek model_armor_config dalam panggilan Gemini Anda. Konfigurasi filter yang ditentukan dalam template akan berlaku, bukan setelan harga minimum level project.

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/publishers/google/models/gemini-2.5-flash:generateContent" \
  -d '{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "Your prompt here"
        }
      ]
    }
  ],
  "model_armor_config": {
    "prompt_template_name": "projects/PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID",
    "response_template_name": "projects/PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID"
  }
}'

Ganti kode berikut:

• PROJECT_ID: Google Cloud Project ID
• REGION: Google Cloud region endpoint Gemini.
• LOCATION: region tempat template Model Armor disimpan. Region ini harus sama dengan region yang ditentukan untuk REGION.
• TEMPLATE_ID: ID template Model Armor.

Catatan: Anda tidak dapat mengganti versi filter untuk integrasi Model Armor dengan server Google dan Google Cloud MCP.

Mengonfigurasi versi filter untuk template

Anda dapat mengonfigurasi versi filter untuk template dengan salah satu dari dua cara berikut:

• Dengan menggunakan alias: Gunakan alias dinamis seperti Stable atau Latest agar template otomatis menggunakan nomor versi yang sesuai dengan alias pilihan Anda. Dengan demikian, Anda tidak perlu melakukan update manual saat versi yang mendasarinya berubah.
• Dengan menggunakan nomor versi: Gunakan nomor versi seperti v3 atau v4 untuk memastikan bahwa template ditetapkan ke versi yang ditentukan, sehingga memastikan perilaku yang tetap dan tidak berubah bahkan saat alias diperbarui.

Membuat template menggunakan alias versi

Untuk membuat template menggunakan alias versi tertentu, jalankan perintah berikut:

gcloud

gcloud model-armor templates create TEMPLATE_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --pi-and-jailbreak-filter-settings-enforcement=enabled \
    --filter-version-selector-alias=FILTER_VERSION_ALIAS

Ganti kode berikut:

• TEMPLATE_ID: ID template yang akan dibuat.
• PROJECT_ID: ID project yang memiliki template.
• LOCATION: lokasi template.
• FILTER_VERSION_ALIAS: alias versi filter pilihan Anda. Gunakan filter-version-alias-stable atau filter-version-alias-latest.

REST

export TEMPLATE_CONFIG='{
  "filterConfig": {
    "piAndJailbreakFilterSettings": {
      "filterEnforcement": "ENABLED"
    }
  },
  "templateMetadata": {
    "filterVersionSelector": {
      "alias": "FILTER_VERSION_ALIAS"
    }
  }
}'

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d "$TEMPLATE_CONFIG" \
    "https://modelarmor.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/templates?template_id=TEMPLATE_ID"

Ganti kode berikut:

• FILTER_VERSION_ALIAS: alias versi filter pilihan Anda. Gunakan FILTER_VERSION_ALIAS_STABLE atau FILTER_VERSION_ALIAS_LATEST.
• PROJECT_ID: ID project yang memiliki template.
• TEMPLATE_ID: ID template yang akan dibuat.
• LOCATION: lokasi template.

Responsnya mirip dengan hal berikut ini:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID",
  "createTime": "2026-04-05T17:57:46.976854398Z",
  "updateTime": "2026-04-05T17:57:46.976854398Z",
  "filterConfig": {
    "piAndJailbreakFilterSettings": {
      "filterEnforcement": "ENABLED"
    }
  },
  "templateMetadata": {
    "filterVersionSelector": {
      "alias": "FILTER_VERSION_ALIAS"
    }
  }
}

Membuat template menggunakan versi filter tertentu

Jika memerlukan filter yang tidak dapat diubah, Anda dapat membuat template yang sesuai dengan versi tertentu. Untuk melakukannya, jalankan perintah berikut:

gcloud

gcloud model-armor templates create TEMPLATE_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --pi-and-jailbreak-filter-settings-enforcement=enabled \
    --filter-version-selector=FILTER_VERSION_NUMBER

Ganti kode berikut:

• TEMPLATE_ID: ID template yang akan dibuat.
• PROJECT_ID: ID project yang memiliki template.
• LOCATION: lokasi template.
• FILTER_VERSION_NUMBER: nomor versi filter pilihan Anda, seperti v3 atau v4.

REST

export TEMPLATE_CONFIG='{
  "filterConfig": {
    "piAndJailbreakFilterSettings": {
      "filterEnforcement": "ENABLED"
    }
  },
  "templateMetadata": {
    "filterVersionSelector": {
      "version": "FILTER_VERSION_NUMBER"
    }
  }
}'

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d "$TEMPLATE_CONFIG" \
    "https://modelarmor.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/templates?template_id=TEMPLATE_ID"

Ganti kode berikut:

• FILTER_VERSION_NUMBER: nomor versi filter pilihan Anda, seperti v3 atau v4.
• PROJECT_ID: ID project yang memiliki template.
• TEMPLATE_ID: ID template yang akan dibuat.
• LOCATION: lokasi template.

Responsnya mirip dengan hal berikut ini:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID",
  "createTime": "2026-04-05T18:03:29.134974974Z",
  "updateTime": "2026-04-05T18:03:29.134974974Z",
  "filterConfig": {
    "piAndJailbreakFilterSettings": {
      "filterEnforcement": "ENABLED"
    }
  },
  "templateMetadata": {
    "filterVersionSelector": {
      "version": "FILTER_VERSION_NUMBER"
    }
  }
}

Memperbarui versi filter template

Anda dapat memperbarui template yang ada untuk menggunakan alias versi filter atau nomor versi filter tertentu:

gcloud

• Untuk mengupdate template agar menggunakan alias versi filter, jalankan perintah berikut:

  gcloud model-armor templates update TEMPLATE_ID \
      --project=PROJECT_ID \
      --location=LOCATION \
      --filter-version-selector-alias=FILTER_VERSION_ALIAS
  

• Untuk mengupdate template agar menggunakan nomor versi filter tertentu, jalankan perintah berikut:

  gcloud model-armor templates update TEMPLATE_ID \
      --project=PROJECT_ID \
      --location=LOCATION \
      --filter-version-selector=FILTER_VERSION_NUMBER
  

Ganti kode berikut:

• TEMPLATE_ID: ID template yang akan diperbarui.
• PROJECT_ID: ID project yang memiliki template.
• LOCATION: lokasi template.
• FILTER_VERSION_ALIAS: alias versi filter pilihan Anda. Gunakan filter-version-alias-stable atau filter-version-alias-latest.
• FILTER_VERSION_NUMBER: nomor versi filter pilihan Anda, seperti v3 atau v4.

REST

• Untuk mengupdate template agar menggunakan alias versi filter, jalankan perintah berikut:

  export TEMPLATE_CONFIG='{
    "templateMetadata": {
      "filterVersionSelector": {
        "alias": "FILTER_VERSION_ALIAS"
      }
    }
  }'
  
  curl -X PATCH \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      -H "Content-Type: application/json" \
      -d "$TEMPLATE_CONFIG" \
      "https://modelarmor.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID?updateMask=templateMetadata.filterVersionSelector"
  

• Untuk mengupdate template agar menggunakan nomor versi filter tertentu, jalankan perintah berikut:

  export TEMPLATE_CONFIG='{
    "templateMetadata": {
      "filterVersionSelector": {
        "version": "FILTER_VERSION_NUMBER"
      }
    }
  }'
  
  curl -X PATCH \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      -H "Content-Type: application/json" \
      -d "$TEMPLATE_CONFIG" \
      "https://modelarmor.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID?updateMask=templateMetadata.filterVersionSelector"
  

Ganti kode berikut:

• FILTER_VERSION_ALIAS: alias versi filter pilihan Anda. Gunakan FILTER_VERSION_ALIAS_STABLE atau FILTER_VERSION_ALIAS_LATEST.
• FILTER_VERSION_NUMBER: nomor versi filter pilihan Anda, seperti v3 atau v4.
• PROJECT_ID: ID project yang memiliki template.
• TEMPLATE_ID: ID template yang akan diperbarui.
• LOCATION: lokasi template.

Responsnya mirip dengan hal berikut ini:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID",
  "createTime": "2026-04-05T18:03:29.134974974Z",
  "updateTime": "2026-04-05T18:04:07.711205953Z",
  "filterConfig": {
    "piAndJailbreakFilterSettings": {
      "filterEnforcement": "ENABLED"
    }
  },
  "templateMetadata": {
    "filterVersionSelector": {
      "alias": "FILTER_VERSION_ALIAS"
    }
  }
}

Melihat versi filter yang digunakan dalam operasi pembersihan

Metadata respons Sanitize API mencakup informasi tentang versi filter yang digunakan selama sanitasi. Demikian pula, perintah sanitasi Google Cloud CLI menampilkan informasi ini dalam outputnya, dan perintah gcloud model-armor templates describe menampilkan versi filter template.

Anda akan menerima peringatan penghentian penggunaan dalam respons pembersihan 30 hari sebelum Google menghentikan versi tersebut.

Contoh berikut menunjukkan respons API yang menyertakan versi filter:

"sanitizationResult": {
    "filterMatchState": "NO_MATCH_FOUND",
    "invocationResult": "SUCCESS",
    "filterResults": {
      "csam": {
        "csamFilterFilterResult": {
          "executionState": "EXECUTION_SUCCESS",
          "matchState": "NO_MATCH_FOUND"
        }
      },
      "malicious_uris": {
        "maliciousUriFilterResult": {
          "executionState": "EXECUTION_SUCCESS",
          "matchState": "NO_MATCH_FOUND"
        }
      },
      "rai": {
        "raiFilterResult": {
          "executionState": "EXECUTION_SUCCESS",
          "matchState": "NO_MATCH_FOUND",
          "raiFilterTypeResults": {
            "sexually_explicit": {
              "matchState": "NO_MATCH_FOUND"
            },
            "hate_speech": {
              "matchState": "NO_MATCH_FOUND"
            },
            "harassment": {
              "matchState": "NO_MATCH_FOUND"
            }
          }
        }
      },
      "pi_and_jailbreak": {
        "piAndJailbreakFilterResult": {
          "executionState": "EXECUTION_SUCCESS",
          "matchState": "NO_MATCH_FOUND"
        }
      },
      "sdp": {
        "sdpFilterResult": {
          "inspectResult": {
            "executionState": "EXECUTION_SUCCESS",
            "matchState": "NO_MATCH_FOUND"
          }
        }
      }
    },
  "sanitizationMetadata": {
    "filterVersionConfig": {
      "filterVersion": "v2",
      "filterVersionAlias": "FILTER_VERSION_ALIAS_LEGACY",
      "releaseDate": {
        "year": 2025,
        "month": 6,
        "day": 19
      },
      "projectedDeprecationDate": {
        "year": 2026,
        "month": 12,
        "day": 17
      },
      "messageItems": [
        {
          "messageType": "WARNING",
          "message": "This filter version (v2) is in LEGACY state and will be
          RETIRED on 2026-12-17. Please migrate your template to the STABLE or
          LATEST version to ensure continued protection."
        }
      ]
   }
  }
}

Model Armor membuat log platform untuk permintaan sanitasi dan responsnya di Cloud Logging. Untuk mengetahui informasi selengkapnya tentang log audit yang dibuat otomatis, lihat Logging audit Model Armor.