Mengintegrasikan Model Armor dengan Gemini Enterprise Agent Platform

Dokumen ini menjelaskan cara mengonfigurasi Model Armor untuk melindungi model Gemini di Gemini Enterprise Agent Platform dengan menyaring perintah dan respons. Jika diintegrasikan dengan Gemini Enterprise Agent Platform, Model Armor akan mencegat perintah sebelum mencapai model Gemini, dan mencegat respons sebelum diterima oleh aplikasi Anda. Berdasarkan konfigurasi Anda, Platform Agen Gemini Enterprise memanggil layanan Model Armor, yang memeriksa atau memblokir traffic yang melanggar kebijakan yang Anda tetapkan—menerapkan langkah-langkah keamanan seperti deteksi injeksi perintah dan jailbreak, filter AI yang bertanggung jawab, dan Perlindungan Data Sensitif. Anda dapat mengonfigurasi integrasi ini dengan menggunakan setelan minimum untuk perlindungan tingkat project atau menggunakan template untuk perlindungan per permintaan.

Model Armor memberikan perlindungan perintah dan respons dalam Gemini API di Vertex AI untuk metode generateContent. Anda harus mengaktifkan Cloud Logging untuk melihat hasil pembersihan perintah dan respons.

Selain melindungi panggilan REST langsung ke layanan Gemini Enterprise Agent Platform, Anda juga dapat menggunakan Model Armor untuk melindungi antarmuka lain yang menyediakan akses ke Gemini API di Vertex AI, seperti SDK AI Generatif Google atau SDK Firebase AI Logic.

Batasan

Pertimbangkan batasan berikut saat mengintegrasikan Model Armor dengan Gemini Enterprise Agent Platform:

  • Saat menggunakan template Sensitive Data Protection untuk memindai perintah atau respons, Model Armor akan memeriksa apakah konten cocok dengan kriteria filter yang ditentukan dalam template. Jika menemukan kecocokan, Model Armor akan menandai bahwa konten tersebut memicu filter Sensitive Data Protection. Meskipun Sensitive Data Protection melakukan de-identifikasi data berdasarkan konfigurasi template, Model Armor tidak meneruskan data yang telah di-de-identifikasi—seperti konten yang disamarkan, disensor, atau di-hash—kembali ke Platform Agen Gemini Enterprise untuk diproses lebih lanjut. Sebagai gantinya, jika jenis penegakan adalah INSPECT_AND_BLOCK, Model Armor akan mengeluarkan putusan pemblokiran untuk memastikan bahwa data sensitif tidak diproses lebih lanjut.
  • Pembersihan perintah dan respons yang berisi dokumen tidak didukung.
  • Jika Gemini Enterprise Agent Platform merutekan permintaan ke region tempat template Model Armor yang ditentukan tidak ada, permintaan akan gagal dengan error Template not found.

  • Gemini Enterprise Agent Platform melewati langkah pembersihan Model Armor dan terus memproses permintaan dalam kondisi berikut:

    • Model Armor tidak tersedia di wilayah tempat Gemini Enterprise Agent Platform berada.
    • Model Armor tidak dapat dijangkau untuk sementara.
    • Terjadi error dalam Model Armor.

    Semua instance ini terkadang dapat mengekspos perintah atau respons yang tidak disaring karena permintaan berlanjut tanpa sanitasi perintah dan respons.

    Meskipun integrasi dibuat untuk ketersediaan tinggi selama kegagalan koneksi, mode INSPECT_AND_BLOCK akan tetap melaporkan error konfigurasi, seperti masalah izin atau kuota.

Sebelum memulai

Mengonfigurasi cara Model Armor membantu melindungi Gemini Enterprise Agent Platform

Anda dapat mengonfigurasi cara Model Armor melindungi Gemini Enterprise Agent Platform dengan salah satu dari dua cara berikut:

  • Menggunakan template untuk perlindungan per permintaan: Pendekatan ini memberikan kontrol terperinci dengan memungkinkan Anda menerapkan template tertentu ke setiap panggilan API ke model Gemini di Gemini Enterprise Agent Platform.generateContent
  • Menggunakan setelan batas bawah untuk perlindungan tingkat project: Pendekatan ini menerapkan perlindungan dasar dengan menerapkan setelan batas bawah ke semua panggilan API generateContent ke model Gemini di Gemini Enterprise Agent Platform dalam project Anda.

Tentukan jenis penegakan untuk menentukan apakah pelanggaran hanya diperiksa atau juga diblokir.

Konfigurasi per permintaan menggunakan template

Template memungkinkan Anda mengonfigurasi cara Model Armor menyaring perintah dan respons serta menentukan konfigurasi filter keamanan. Anda harus membuat template terlebih dahulu, lalu menggunakan template ini dengan metode generateContent Gemini. Untuk mengetahui informasi selengkapnya tentang template, lihat Membuat dan mengelola template Model Armor.

Setelah mengonfigurasi template Model Armor, teruskan ID template sebagai parameter saat melakukan panggilan ke Gemini API menggunakan metode generateContent. Gemini Enterprise Agent Platform mengarahkan permintaan ke Model Armor untuk diproses.

Untuk menerapkan template tertentu ke panggilan generateContent individual, sertakan objek modelArmorConfig dalam permintaan Anda.

  • promptTemplateName: Nama resource template Model Armor untuk membersihkan perintah.
  • responseTemplateName: Nama resource template Model Armor untuk membersihkan respons.

Contoh kode berikut menunjukkan permintaan ke metode generateContent.

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $(gcloud auth print-access-token)" "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/gemini-2.0-flash-001:generateContent" -d '{
"contents": [
    {
        "role": "user",
        "parts": [
            {
                "text": "[YOUR PROMPT HERE]"
            }
        ]
    }
]
, "generationConfig": {
    "responseModalities": ["TEXT"]
    ,"temperature": 0.2
    ,"maxOutputTokens": 1024
    ,"topP": 0.8
},
 "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
  • LOCATION: lokasi Google Cloud endpoint Gemini. Lokasi yang didukung adalah europe-west1, europe-west2, europe-west3, asia-southeast1, dan asia-south1.
  • TEMPLATE_ID: ID template Model Armor.

Contoh kode berikut menunjukkan respons dari metode generateContent.

{
  "promptFeedback": {
    "blockReason": "MODEL_ARMOR",
    "blockReasonMessage": "Blocked by Floor Setting. The prompt violated Responsible AI Safety settings (Harassment, Dangerous), Prompt Injection and Jailbreak filters."
  },
  "usageMetadata": {
    "trafficType": "ON_DEMAND"
  },
  "modelVersion": "gemini-2.0-flash-001",
  "createTime": "2025-03-26T13:14:36.961184Z",
  "responseId": "vP3jZ6DVOqLKnvgPqZL-8Ao"
}

Menentukan jenis penerapan untuk template

Untuk mengonfigurasi cara Model Armor menangani deteksi, tetapkan jenis penegakan.

Contoh berikut menunjukkan konfigurasi template Model Armor dengan jenis penerapan Inspect only.

export TEMPLATE_CONFIG='{
   "filter_config": {
    "rai_settings": {
     "rai_filters": [{
       "filter_type": "HATE_SPEECH",
       "confidence_level": "MEDIUM_AND_ABOVE"
      }, {
      "filter_type": "HARASSMENT",
      "confidence_level": "MEDIUM_AND_ABOVE"
    }, {
      "filter_type": "DANGEROUS",
      "confidence_level": "MEDIUM_AND_ABOVE"
    },{
      "filter_type": "SEXUALLY_EXPLICIT",
      "confidence_level": "MEDIUM_AND_ABOVE"
    }]
  },
  "pi_and_jailbreak_filter_settings": {
    "filter_enforcement": "ENABLED",
    "confidence_level": "LOW_AND_ABOVE"
  },
  "malicious_uri_filter_settings": {
    "filter_enforcement": "ENABLED"
  }
 },
 "template_metadata": {
    "enforcement_type": "INSPECT_ONLY",
    "multi_language_detection": {
      "enable_multi_language_detection": true
    }
  }
}'

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

Ganti kode berikut:

  • PROJECT_ID: ID project tempat template berada.
  • TEMPLATE_ID: ID template yang akan dibuat.
  • LOCATION: lokasi template.

Konfigurasi tingkat project menggunakan setelan minimum

Setelan tingkat menentukan dasar perlindungan minimum yang berlaku untuk semua panggilan generateContent Gemini Enterprise Agent Platform dalam project, meskipun parameter modelArmorConfig dihilangkan dari permintaan API. Lihat Mengonfigurasi setelan tingkat untuk mempelajari cara menyiapkan setelan tingkat.

Untuk mengaktifkan integrasi Model Armor dan Gemini Enterprise Agent Platform, tetapkan setelan batas bawah hanya di tingkat project menggunakan API atau konsol Google Cloud .

Untuk mengonfigurasi setelan lantai dengan integrasi Gemini Enterprise Agent Platform, jalankan perintah berikut:

gcloud

gcloud model-armor floorsettings update \
  --full-uri=projects/PROJECT_ID/locations/global/floorSetting \
  --add-integrated-services=VERTEX_AI

Perintah ini mengaktifkan mode penerapan INSPECT_ONLY secara default. Untuk mengubah mode ke INSPECT_AND_BLOCK, jalankan perintah berikut:

gcloud model-armor floorsettings update \
  --full-uri=projects/PROJECT_ID/locations/global/floorSetting \
  --vertex-ai-enforcement-type=INSPECT_AND_BLOCK

Untuk menghapus Gemini Enterprise Agent Platform dari layanan terintegrasi, jalankan perintah berikut:

gcloud model-armor floorsettings update \
  --full-uri=projects/PROJECT_ID/locations/global/floorSetting \
  --remove-integrated-services=VERTEX_AI

Untuk menghapus semua layanan terintegrasi yang dikonfigurasi dari setelan lantai, jalankan perintah berikut:

gcloud model-armor floorsettings update \
  --full-uri=projects/PROJECT_ID/locations/global/floorSetting \
  --clear-integrated-services

Ganti PROJECT_ID dengan ID project untuk setelan tingkat.

REST

curl -X PATCH \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -d '{"filterConfig" : {"piAndJailbreakFilterSettings": { "filterEnforcement": "ENABLED"}}, "integratedServices": ["AI_PLATFORM"], "aiPlatformFloorSetting":{"inspectOnly":true, "enableCloudLogging":true}, "enableFloorSettingEnforcement":true}' \
  "https://modelarmor.googleapis.com/v1/projects/PROJECT_ID/locations/global/floorSetting"

Ganti PROJECT_ID dengan ID project yang berisi setelan tingkat.

Setelah mengonfigurasi setelan tingkat untuk mengaktifkan pembersihan Gemini Enterprise Agent Platform, Model Armor akan membersihkan semua panggilan API generateContent ke endpoint Gemini project menggunakan setelan filter yang ditentukan.

Contoh kode berikut menunjukkan cara menggunakan metode generateContent.

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $(gcloud auth print-access-token)" "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/gemini-2.5-flash:generateContent" -d '{
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $(gcloud auth print-access-token)" "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/gemini-2.5-flash:generateContent" -d '{
"contents": [
  {
      "role": "user",
      "parts": [
          {
              "text": ""
          }
      ]
  }
]
, "generationConfig": {
  "responseModalities": ["TEXT"]
  ,"temperature": 0.2
  ,"maxOutputTokens": 1024
  ,"topP": 0.8
}
}'

Ganti kode berikut:

  • PROJECT_ID: Google Cloud Project ID Anda.
  • LOCATION: lokasi endpoint Gemini. Google Cloud Untuk lokasi yang didukung, lihat Lokasi untuk Model Armor API.

Contoh kode berikut menunjukkan respons dari metode generateContent.

{
"promptFeedback": {
  "blockReason": "MODEL_ARMOR",
  "blockReasonMessage": "Blocked by Floor Setting. The prompt violated
  Responsible AI Safety settings (Harassment, Dangerous), Prompt Injection
  and Jailbreak filters."
},
"usageMetadata": {
  "trafficType": "ON_DEMAND"
},
"modelVersion": "gemini-2.5-flash",
"createTime": "2025-03-26T13:14:36.961184Z",
"responseId": "vP3jZ6DVOqLKnvgPqZL-8Ao"
}

Menentukan jenis penegakan untuk setelan tingkat

Untuk mengonfigurasi cara Model Armor menangani deteksi, tetapkan jenis penegakan ke INSPECT atau INSPECT_AND_BLOCK. Contoh berikut menunjukkan konfigurasi setelan tingkat dengan jenis penerapan INSPECT_AND_BLOCK.

gcloud

gcloud model-armor floorsettings update \
  --full-uri=projects/modelarmor-api-test/locations/global/floorSetting \
  --vertex-ai-enforcement-type=INSPECT_AND_BLOCK

REST

export FLOOR_SETTING='{
  "filterConfig": {
    "raiSettings": {
      "raiFilters": [
        { "filterType": "HATE_SPEECH", "confidenceLevel": "LOW_AND_ABOVE" },
        { "filterType": "DANGEROUS", "confidenceLevel": "LOW_AND_ABOVE" },
        { "filterType": "SEXUALLY_EXPLICIT", "confidenceLevel": "LOW_AND_ABOVE" },
        { "filterType": "HARASSMENT", "confidenceLevel": "LOW_AND_ABOVE" }
      ]
    },
    "sdpSettings": {
      "basicConfig": { "filterEnforcement": "ENABLED" }
    },
    "piAndJailbreakFilterSettings": {
      "filterEnforcement": "ENABLED",
      "confidenceLevel": "LOW_AND_ABOVE"
    },
    "maliciousUriFilterSettings": { "filterEnforcement": "ENABLED" }
  },
  "integratedServices": ["AI_PLATFORM"],
  "aiPlatformFloorSetting": {
    "inspectAndBlock": true,
    "enableCloudLogging": true
  },
  "enableFloorSettingEnforcement": true
}'

curl -X PATCH \
    -d "$FLOOR_SETTING" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://modelarmor.googleapis.com/v1/projects/PROJECT_ID/locations/global/floorSetting"

Ganti kode berikut:

  • PROJECT_ID: ID project untuk setelan tingkat.
  • LOCATION: lokasi setelan tingkat.

Menguji penegakan inline dengan panggilan API

Uji integrasi untuk memanggil metode generateContent API Gemini Enterprise Agent Platform. Gunakan perintah yang dirancang untuk melanggar setelan batas bawah yang dikonfigurasi.

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $(gcloud auth print-access-token)" "https://${VERTEX_AI_LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${VERTEX_AI_LOCATION}/publishers/google/models/gemini-2.5-flash:generateContent" -d '{
"contents": [
    {
        "role": "user",
        "parts": [
            {
                "text": ""
            }
        ]
    }
]
, "generationConfig": {
    "responseModalities": ["TEXT"]
    ,"temperature": 0.2
    ,"maxOutputTokens": 1024
    ,"topP": 0.8
}
}'

Jika integrasi berfungsi seperti yang diharapkan, API akan menampilkan respons dengan kolom blockReason disetel ke MODEL_ARMOR saat Model Armor mengidentifikasi perintah sebagai pelanggaran.

Contoh responsnya adalah sebagai berikut:

    {
    "promptFeedback": {
      "blockReason": "MODEL_ARMOR",
      "blockReasonMessage": "Blocked by Floor Setting. The prompt violated Responsible AI Safety settings..."
    },
    "usageMetadata": { "trafficType": "ON_DEMAND" },
    "modelVersion": "gemini-2.5-flash"
    }

Aturan interaksi dan prioritas

Saat menggunakan Model Armor dengan Gemini Enterprise Agent Platform, Anda dapat menentukan konfigurasi keamanan di beberapa tingkat. Dalam kasus tersebut, Model Armor dan Gemini Enterprise Agent Platform mengikuti urutan prioritas tertentu:

  1. Template Model Armor: Konfigurasi apa pun yang diberikan secara eksplisit dalam konfigurasi permintaan API memiliki prioritas tertinggi. Setelan ini menggantikan konfigurasi lain yang bertentangan untuk permintaan tertentu tersebut.

  2. Setelan minimum Model Armor: Jika tidak ada konfigurasi penggantian yang diberikan dalam permintaan API, setelan minimum Model Armor akan diterapkan.

  3. Filter keamanan Gemini Enterprise Agent Platform: Filter keamanan default yang dibuat ke dalam Gemini Enterprise Agent Platform memiliki prioritas terendah. Setelan ini hanya berlaku jika Anda tidak menentukan template atau setelan tingkat Model Armor tertentu.

Pendekatan hierarkis ini memberikan kombinasi standar minimum yang luas di seluruh organisasi (menggunakan setelan minimum) dan kontrol per permintaan (menggunakan template), sekaligus tetap menggunakan fitur keamanan bawaan Platform Agen Gemini Enterprise sebagai dasar.

Perilaku fitur keamanan Model Armor dan Gemini Enterprise Agent Platform bergantung pada cara Anda memberikan konfigurasi.

Template dikonfigurasi? Filter keamanan Gemini Enterprise Agent Platform dikonfigurasi? Setelan minimum dikonfigurasi? Perilaku
Ya Ya Semua Anda mendapatkan error. Anda tidak dapat menentukan konfigurasi template dan filter keamanan Gemini Enterprise Agent Platform dalam permintaan yang sama.
Ya Tidak Semua Model Armor berjalan, menggunakan template yang ditentukan dalam modelArmorConfig. Filter keamanan Gemini Enterprise Agent Platform diabaikan. Template permintaan menggantikan setelan minimum.
Tidak Ya Ya Keduanya berjalan. Pemindaian Model Armor menggunakan kebijakan setelan dasar, dan Gemini Enterprise Agent Platform mengevaluasi filter keamanannya. Hasil yang paling ketat diterapkan.
Tidak Tidak Ya Armor Model berjalan, menggunakan kebijakan setelan batas bawah aktif.
Tidak Ya Tidak Hanya filter keamanan Gemini Enterprise Agent Platform yang dievaluasi. Model Armor tidak dipanggil.
Tidak Tidak Tidak Filter keamanan Model Armor per permintaan maupun Gemini Enterprise Agent Platform tidak diterapkan. Hanya perilaku model dasar yang aktif.