Google menggunakan teknologi AI untuk menerjemahkan konten ke dalam bahasa pilihan Anda. Terjemahan AI mungkin mengandung kesalahan.

Mengonfigurasi logging

Dokumen ini menjelaskan cara mengonfigurasi Model Armor untuk mencatat operasi berikut:

Operasi yang membuat, memperbarui, atau menghapus template
Operasi yang membersihkan perintah pengguna atau respons model

Model Armor menggunakan log audit untuk mencatat aktivitas pengelolaan administratif dan resource. Untuk mengetahui informasi selengkapnya, lihat Logging audit Model Armor.

Untuk mengetahui informasi tentang harga log, lihat harga Cloud Logging. Biaya penggunaan Model Armor juga mungkin berlaku berdasarkan volume data yang diproses; lihat Harga Model Armor untuk mengetahui detailnya.

Sebelum memulai

Sebelum memulai, selesaikan tugas berikut.

Mendapatkan izin yang diperlukan

Untuk mendapatkan izin yang diperlukan guna mengonfigurasi logging untuk Model Armor, minta administrator untuk memberi Anda peran IAM Model Armor Admin (roles/modelarmor.admin) pada template Model Armor. 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

Anda harus mengaktifkan Model Armor API sebelum dapat menggunakan Model Armor.

Konsol

Aktifkan Model Armor API, jika belum diaktifkan.
Peran yang diperlukan untuk mengaktifkan API
Untuk mengaktifkan API, Anda memerlukan izin serviceusage.services.enable. Jika Anda membuat project, kemungkinan Anda sudah memiliki izin ini melalui peran Pemilik (roles/owner). Jika tidak, Anda bisa mendapatkan izin ini melalui peran Service Usage Admin (roles/serviceusage.serviceUsageAdmin). Pelajari cara memberikan peran.
Mengaktifkan API
Pilih project tempat Anda ingin mengaktifkan Model Armor.

gcloud

Sebelum memulai, ikuti langkah-langkah berikut menggunakan Google Cloud CLI dengan Model Armor API:

Di konsol Google Cloud , aktifkan Cloud Shell.

Aktifkan Cloud Shell

Di bagian bawah konsol Google Cloud , sesi Cloud Shell akan dimulai dan menampilkan perintah command line. Cloud Shell adalah lingkungan shell dengan Google Cloud CLI yang sudah terinstal, dan dengan nilai yang sudah ditetapkan untuk project Anda saat ini. Diperlukan waktu beberapa detik untuk melakukan inisialisasi pada sesi.
Aktifkan Model Armor API, jika belum diaktifkan:
Peran yang diperlukan untuk mengaktifkan API
Untuk mengaktifkan API, Anda memerlukan izin serviceusage.services.enable. Jika Anda membuat project, kemungkinan Anda sudah memiliki izin ini melalui peran Pemilik (roles/owner). Jika tidak, Anda bisa mendapatkan izin ini melalui peran Admin Penggunaan Layanan (roles/serviceusage.serviceUsageAdmin). Pelajari cara memberikan peran.
```
gcloud services enable modelarmor.googleapis.com
```
Tetapkan penggantian endpoint API menggunakan gcloud CLI.

Menetapkan penggantian endpoint API menggunakan gcloud CLI

Langkah ini hanya diperlukan jika Anda menggunakan gcloud CLI dengan Model Armor dan ingin menggunakan region atau multi-region selain multi-region us default. Anda harus menetapkan penggantian endpoint API secara manual untuk memastikan gcloud CLI merutekan permintaan dengan benar ke layanan Model Armor.

Jalankan perintah berikut untuk menetapkan endpoint API untuk layanan Model Armor.

gcloud config set api_endpoint_overrides/modelarmor "https://modelarmor.LOCATION.rep.googleapis.com/"

Ganti LOCATION dengan region atau multi-region tempat Anda ingin menggunakan Model Armor.

Menyiapkan pembersihan traffic

Untuk server Google dan Google Cloud server MCP, siapkan pembersihan traffic melalui setelan tingkat. Untuk mengetahui informasi selengkapnya, lihat Mengonfigurasi perlindungan untuk server Google dan Google Cloud server MCP.

Mengonfigurasi logging dalam template

Template menentukan filter dan nilai minimum untuk berbagai kategori keselamatan dan keamanan. Saat membuat atau memperbarui template Model Armor, Anda dapat menentukan apakah Model Armor mencatat operasi tertentu. Gunakan flag berikut dalam metadata template:

log_template_operations: Nilai boolean yang memungkinkan Anda mencatat operasi pembuatan, pembaruan, pembacaan, dan penghapusan template.
log_sanitize_operations: Nilai boolean yang memungkinkan Anda mencatat konten lengkap perintah pengguna dan respons model selama operasi sanitasi.

Konsol

Di konsol Google Cloud , buka halaman Model Armor.

Buka Model Armor
Pastikan Anda melihat project tempat Anda mengaktifkan Model Armor.
Di halaman Model Armor, klik Create Template. Untuk mengetahui informasi selengkapnya tentang cara membuat template, lihat Membuat template Model Armor.
Di bagian Configure logging, pilih operasi yang ingin Anda konfigurasi logging-nya.
Klik Create.

REST

  curl -X POST \
      -d '{ "filterConfig": {}, "templateMetadata": { "logTemplateOperations": true, "logSanitizeOperations": true } }' \
      -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.
LOCATION: lokasi template.
TEMPLATE_ID: ID template.

Python

Untuk menjalankan kode ini, siapkan lingkungan pengembangan Python terlebih dahulu dan instal Model Armor Python SDK.

   request = modelarmor_v1.CreateTemplateRequest(
     parent="projects/PROJECT_ID/locations/LOCATION",
     template_id="TEMPLATE_ID",
     template={
        "name": "projects/PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID",
        "filter_config": {},
        "template_metadata": {
           "log_template_operations": True,
           "log_sanitize_operations": True
        }
     }
   )
   response = client.create_template(request=request)

Ganti kode berikut:

PROJECT_ID: ID project tempat template berada.
LOCATION: lokasi template.
TEMPLATE_ID: ID template.

Mengonfigurasi logging di setelan lantai

Saat Anda menerapkan setelan batas bawah pada traffic dari model Gemini di Gemini Enterprise Agent Platform dan server MCP Google Cloud Google dalam project Anda, setelan batas bawah menentukan filter keamanan dan perlindungan untuk operasi pembersihan. Saat memperbarui setelan tingkat Model Armor, Anda dapat menentukan apakah Model Armor mencatat operasi pembersihan ke dalam log.

Anda dapat mengaktifkan logging operasi pembersihan untuk Agent Platform dan server MCP Google Google Cloud secara terpisah. Jika diaktifkan, log akan menyertakan perintah dan respons (untuk Agent Platform) atau panggilan alat dan respons alat (untuk server MCP), hasil evaluasi Model Armor, dan kolom metadata tambahan.

Contoh berikut menunjukkan cara mengaktifkan logging operasi pembersihan untuk server Agent Platform dan Google serta Google Cloud MCP.

Konsol

Di konsol Google Cloud , buka halaman Model Armor.

Buka Model Armor
Pastikan Anda melihat project tempat Anda mengaktifkan Model Armor.
Buka tab Setelan Lantai.
Di bagian Logs, centang kotak Vertex AI dan Google managed MCP untuk mengaktifkan logging bagi setiap layanan.
Klik Simpan.

gcloud

Gunakan flag --enable-vertex-ai-cloud-logging untuk mengaktifkan logging untuk Agent Platform, dan flag --enable-google-mcp-server-cloud-logging untuk mengaktifkan logging untuk server Google dan Google Cloud server MCP. Untuk menonaktifkan pencatatan log, gunakan flag --no-enable-vertex-ai-cloud-logging dan --no-enable-google-mcp-server-cloud-logging.

Contoh perintah berikut mengaktifkan logging operasi pembersihan untuk server Agent Platform dan server Google Cloud MCP Google:

gcloud model-armor floorsettings update \
--full-uri='projects/PROJECT_ID/locations/global/floorSetting' \
--enable-vertex-ai-cloud-logging \
--enable-google-mcp-server-cloud-logging

Ganti PROJECT_ID dengan ID project Anda.

REST

Untuk mengaktifkan logging, tetapkan aiPlatformFloorSetting.enableCloudLogging ke true untuk Agent Platform dan googleMcpServerFloorSetting.enableCloudLogging ke true untuk server Google dan Google Cloud server MCP dalam metode UpdateFloorSetting.

Contoh perintah berikut mengaktifkan logging operasi pembersihan untuk server Agent Platform dan Google Google Cloud MCP:

curl -X PATCH \
 -d '{ "aiPlatformFloorSetting":{ "enableCloudLogging": true}, "googleMcpServerFloorSetting":{ "enableCloudLogging": true}}' \
 -H "Content-Type: application/json" \
 -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://modelarmor.googleapis.com/v1/projects/PROJECT_ID/locations/global/floorSetting?updateMask=aiPlatformFloorSetting.enableCloudLogging,googleMcpServerFloorSetting.enableCloudLogging"

Ganti PROJECT_ID dengan ID project Anda.

Python

Untuk menjalankan kode ini, siapkan lingkungan pengembangan Python terlebih dahulu dan instal Model Armor Python SDK.

from google.cloud.modelarmor import v1 as modelarmor_v1
from google.protobuf import field_mask_pb2

# TODO: Initialize the ModelArmorClient, "client"
# client = modelarmor_v1.ModelArmorClient()

project_id = "PROJECT_ID"
location = "global"

floor_setting_name = f"projects/{project_id}/locations/{location}/floorSetting"

request = modelarmor_v1.UpdateFloorSettingRequest(
    floor_setting=modelarmor_v1.FloorSetting(
        name=floor_setting_name,
        ai_platform_floor_setting=modelarmor_v1.FloorSetting.AiPlatformFloorSetting(
            enable_cloud_logging=True
        ),
        google_mcp_server_floor_setting=modelarmor_v1.FloorSetting.GoogleMcpServerFloorSetting(
            enable_cloud_logging=True
        ),
    ),
    update_mask=field_mask_pb2.FieldMask(
        paths=["ai_platform_floor_setting.enable_cloud_logging", "google_mcp_server_floor_setting.enable_cloud_logging"]
    )
)

try:
    response = client.update_floor_setting(request=request)
    print("Successfully updated floor settings logging.")
    print(response)
except Exception as e:
    print(f"An error occurred: {e}")

Ganti PROJECT_ID dengan ID project Anda.

Melihat dan memfilter log Model Armor

Untuk melihat dan memfilter log Model Armor, gunakan Logs Explorer di Logging:

Di konsol Google Cloud , buka halaman Logs Explorer.

Buka Logs Explorer

Untuk mengetahui informasi selengkapnya, lihat Melihat log menggunakan Logs Explorer.
Di panel kueri, masukkan salah satu kueri berikut untuk memfilter log Model Armor:
- Untuk melihat semua log Model Armor, termasuk log audit dan log operasi sanitasi:
```
protoPayload.serviceName="modelarmor.googleapis.com" OR jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"
```
- Untuk melihat hanya log audit Model Armor:
```
protoPayload.serviceName="modelarmor.googleapis.com"
```
  Untuk mengetahui daftar semua nama layanan dan jenis resource yang dimonitor, lihat Resource dan layanan yang dimonitor.
- Untuk melihat hanya log Model Armor untuk operasi sanitasi:
```
jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"
```
  Untuk lebih menyaring log operasi sanitasi, Anda dapat menentukan nama klien, ID korelasi, atau label evaluasi aturan pengecualian (Pratinjau) dalam kueri:
  - Menggunakan nama klien: Saat Model Armor terintegrasi dengan layanan seperti Gemini Enterprise Agent Platform atau Gemini Enterprise, Anda dapat menggunakan nama klien untuk memfilter log untuk integrasi tertentu.
```
jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"
labels."modelarmor.googleapis.com/client_name"="CLIENT_NAME"
```
  - Menggunakan ID korelasi:
```
jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"
labels."modelarmor.googleapis.com/client_correlation_id"="CORRELATION_ID"
```
    Ganti kode berikut:
    - CLIENT_NAME: nama klien Anda. Gunakan salah satu nilai berikut:
      - CLIENT_NAME_UNSPECIFIED: Nilai default, digunakan saat nama klien tidak ditentukan.
      - VERTEX_AI: Untuk integrasi dengan Gemini Enterprise Agent Platform.
      - LOAD_BALANCER: Untuk integrasi menggunakan ekstensi load balancer sebagai layanan.
      - LANGCHAIN: Untuk integrasi dengan LangChain.
      - GEMINI_ENTERPRISE_BUSINESS: Untuk integrasi dengan Gemini Enterprise - edisi Business.
      - GOOGLE_MCP_SERVER: Untuk integrasi dengan server MCP yang dikelola Google dan Google.
      - AGENT_GATEWAY: Untuk integrasi dengan Agent Gateway.
      - GEMINI_ENTERPRISE_NON_BUSINESS: Untuk integrasi dengan edisi Gemini Enterprise selain Business (Standard, Plus, dan Frontline).
      - SECURE_WEB_PROXY: Untuk integrasi dengan Secure Web Proxy.
    - CORRELATION_ID: ID unik yang Anda buat untuk permintaan tertentu.
  - Menggunakan label aturan pengecualian (Pratinjau): Jika aturan pengecualian menggantikan hasil filter atau saat Model Armor melewati evaluasi aturan pengecualian, Model Armor akan mengisi kolom labels tingkat teratas opsional berikut pada entri log modelarmor.googleapis.com/SanitizeOperation:
    - modelarmor.googleapis.com/exclusion_rule_overridden_filters: daftar filter yang dipisahkan koma yang hasil MATCH_FOUND atau EXECUTION_SKIPPED-nya diganti menjadi NO_MATCH_FOUND karena aturan pengecualian cocok.
    - modelarmor.googleapis.com/exclusion_rule_skipped_filters: daftar filter yang dipisahkan koma yang evaluasi aturan pengecualiannya dilewati (misalnya, saat input melebihi batas muatan pengecualian 130.000 token (0,5 MB)).
    Gunakan contoh kueri berikut untuk memfilter log sanitasi menurut label aturan pengecualian:
    - Untuk menemukan permintaan yang hasil filternya diganti oleh aturan pengecualian:
```
jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"
labels."modelarmor.googleapis.com/exclusion_rule_overridden_filters":"FILTER_NAME"
```
    - Untuk menemukan permintaan yang deteksi injeksi perintah dan jailbreak-nya diganti oleh aturan pengecualian:
```
jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"
labels."modelarmor.googleapis.com/exclusion_rule_overridden_filters"="PROMPT_INJECTION_AND_JAILBREAK"
```
    - Untuk menemukan permintaan yang evaluasi aturan eksklusifnya dilewati:
```
jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"
labels."modelarmor.googleapis.com/exclusion_rule_skipped_filters"="FILTER_NAME"
```
    Ganti FILTER_NAME dengan nama filter (PROMPT_INJECTION_AND_JAILBREAK atau RESPONSIBLE_AI).

Menghubungkan log dan peristiwa terkait

Untuk mengorelasikan log dan peristiwa untuk interaksi tertentu, Anda dapat menggunakan ID korelasi klien Model Armor. ID ini adalah ID unik yang Anda buat (misalnya, UUID) yang melacak permintaan tertentu di seluruh sistem Anda. Untuk menetapkan ID korelasi klien di header curl, gunakan opsi -H untuk menyertakan header kustom MA-Client-Correlation-Id dalam permintaan Anda.

Berikut contoh formatnya:

uuid=$(uuidgen) \
curl -X POST -d  '{"userPromptData": { "text": "USER_PROMPT" } }' \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "MA-Client-Correlation-Id:${uuid}" \
    "https://modelarmor.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID:sanitizeUserPrompt"

curl -X POST \
    -d  '{"modelResponseData": { "text": "MODEL_RESPONSE" }, "userPrompt": "USER_PROMPT" }' \
    -H "Content-Type: application/json" \
    -H "MA-Client-Correlation-Id:${uuid}" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://modelarmor.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID:sanitizeModelResponse"

Ganti kode berikut:

PROJECT_ID: ID project yang memiliki template.
LOCATION: lokasi template.
TEMPLATE_ID: ID template.
USER_PROMPT: perintah yang diberikan ke model.
MODEL_RESPONSE: respons yang diterima dari model.

Log platform versus Cloud Audit Logs

Anda perlu membedakan antara log yang dapat diaktifkan dalam setelan minimum atau template Model Armor dan Cloud Audit Logs.

Fitur	Cloud Audit Logs	Log platform
Tujuan utama	Audit keamanan panggilan API (siapa yang melakukan apa, kapan) dan pemantauan kepatuhan.	Pemantauan operasional, proses debug, dan analisis mendetail tentang peristiwa sanitasi.
Operasi API yang direkam	Operasi pembuatan, pembacaan, pembaruan, penghapusan, dan pencantuman pada template dan setelan tingkat. Operasi pembersihan (`SanitizeUserPrompt`, `SanitizeModelResponse`) dicatat sebagai metadata.	Mencatat semua permintaan seperti `SanitizeUserPrompt` dan `SanitizeModelResponse`.
Konten payload	Tidak menyertakan perintah pengguna atau teks respons model yang sebenarnya untuk operasi sanitize. Berisi metadata seperti pemanggil, metode, resource, stempel waktu, dan status.	Mencakup payload lengkap, seperti teks perintah atau respons, hasil filter, dan detail sanitasi lainnya.
Mekanisme pengaktifan	Setelan log audit IAM standar Google Cloud untuk Model Armor API. Log akses data sering kali memerlukan pengaktifan eksplisit. Log audit untuk operasi template dibuat secara otomatis.	Diaktifkan dengan menyetel tanda boolean `log_sanitize_operations` di metadata template atau setelan lantai.
Kondisi pencatatan log	Log membuat, membaca, memperbarui, menghapus, dan mencantumkan operasi pada template dan setelan lantai secara otomatis.	Mencatat data (perintah pengguna dan respons model) untuk permintaan dataplane apa pun, terlepas dari apakah Sensitive Data Protection diaktifkan atau apakah ada setelan filter yang cocok.
Volume dan biaya log	Umumnya lebih kecil dan lebih dapat diprediksi, sehingga dikenai harga Cloud Logging standar.	Dapat berukuran sangat besar dan bervolume tinggi, sehingga berpotensi menimbulkan biaya Cloud Logging yang signifikan karena payload yang besar dan penggunaan yang sering. Payload besar dapat dibagi menjadi beberapa entri log.
Pertimbangan keamanan	Relatif aman karena data payload tidak dicatat. Memerlukan izin IAM khusus untuk mengakses (misalnya, peran IAM tertentu untuk melihat log audit).	Berisi data pengguna yang berpotensi sensitif (PII, informasi rahasia). Dapat diakses oleh siapa saja yang memiliki izin melihat log (misalnya, `roles/logging.privateLogViewer`).
Rekomendasi	Aktifkan untuk pemantauan keamanan dan kepatuhan umum.	Tidak direkomendasikan untuk data produksi atau sensitif kecuali jika dirutekan dengan aman ke tujuan yang dikontrol aksesnya (misalnya, BigQuery dengan IAM yang ketat).

Mengaktifkan logging dalam template akan menulis perintah dan respons mentah ke Logging. Data ini mungkin mencakup data pengguna sensitif, informasi identitas pribadi (PII), atau informasi rahasia. Traffic yang tinggi dan payload yang besar dapat menyebabkan biaya logging yang besar dan potensi volume log yang besar melebihi batas dan memerlukan pengelolaan yang cermat.

Identitas pemanggil di log audit

Saat Anda melihat log audit, Cloud Audit Logs akan merekam identitas pemanggil di kolom protoPayload.authenticationInfo.principalEmail. Identitas yang dicatat bergantung pada cara Model Armor API dipanggil:

Pemanggilan API langsung: Jika pengguna atau akun layanan memanggil Model Armor API secara langsung (misalnya, menggunakan gcloud, library klien, atau REST API), principalEmail akan berisi alamat email pengguna atau akun layanan tersebut.
Pemanggilan melalui layanan Google Cloud terintegrasi: Jika Model Armor terintegrasi dengan layanan Google Cloud lain seperti Platform Agen Gemini Enterprise, maka principalEmail berisi identitas layanan tersebut, yang biasanya merupakan akun layanan yang dikelola Google. Format untuk agen layanan adalah service-PROJECT_NUMBER@SERVICE_NAME.iam.gserviceaccount.com. Misalnya, panggilan yang berasal dari fitur Gemini Enterprise Agent Platform menggunakan agen layanan Gemini Enterprise Agent Platform.

Untuk membedakan antara pemanggil, periksa kolom principalEmail di entri log audit. Panggilan dari pengguna akhir atau akun layanan yang dikelola pengguna menampilkan alamat email mereka, sedangkan panggilan melalui layanan Google Cloud lainnya menampilkan alamat email akun layanan yang dikelola Google.

Langkah berikutnya

Mengorelasikan log Model Armor dengan log Gemini Enterprise

Mengonfigurasi logging Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Sebelum memulai

Mendapatkan izin yang diperlukan

Mengaktifkan API

Konsol

gcloud

Menetapkan penggantian endpoint API menggunakan gcloud CLI

Menyiapkan pembersihan traffic

Mengonfigurasi logging dalam template

Konsol

REST

Python

Mengonfigurasi logging di setelan lantai

Konsol

gcloud

REST

Python

Melihat dan memfilter log Model Armor

Menghubungkan log dan peristiwa terkait

Log platform versus Cloud Audit Logs

Identitas pemanggil di log audit

Langkah berikutnya

Mengonfigurasi logging