Mengonfigurasi logging

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

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

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

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

Sebelum memulai

Selesaikan tugas ini sebelum Anda menyelesaikan tugas lainnya di halaman ini.

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) di template Model Armor. Untuk mengetahui informasi selengkapnya tentang pemberian 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

1. Enable the Model Armor API.

   Roles required to enable APIs

   To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

   Enable the API

2. Pilih project tempat Anda ingin mengaktifkan Model Armor.

gcloud

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

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

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

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

   Ganti LOCATION dengan region tempat Anda ingin menggunakan Model Armor.

Menyiapkan pembersihan traffic

Untuk server Model Context Protocol (MCP) yang dikelola Google, siapkan pembersihan traffic melalui setelan batas bawah. Untuk mengetahui informasi selengkapnya, lihat Mengonfigurasi perlindungan untuk server Google dan MCP jarak jauh. Google Cloud (Pratinjau)

Mengonfigurasi logging dalam template

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

• log_template_operations: Nilai boolean yang mengaktifkan logging operasi pembuatan, pembaruan, pembacaan, dan penghapusan template.

• log_sanitize_operations: Nilai boolean yang mengaktifkan logging operasi pembersihan. Log mencakup perintah dan respons, hasil evaluasi Model Armor, dan kolom metadata tambahan.

Konsol

1. Di konsol Google Cloud , buka halaman Model Armor.

   Buka Model Armor

2. Pastikan Anda melihat project tempat Anda mengaktifkan Model Armor.

3. Di halaman Model Armor, klik Create Template. Untuk mengetahui informasi selengkapnya tentang cara membuat template, lihat Membuat template Model Armor.

4. Di bagian Konfigurasi logging, pilih operasi yang logging-nya ingin Anda konfigurasi.

5. 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, pertama-tama siapkan lingkungan pengembangan Python 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 ruang

Setelan dasar menetapkan filter keamanan dan perlindungan dasar di semua model Gemini di Vertex AI dan server Model Context Protocol (MCP) yang dikelola Google (Pratinjau) dalam project Anda. Saat memperbarui setelan batas bawah Model Armor, Anda dapat menentukan apakah operasi pembersihan Model Armor dicatat.

Catatan: Di konsol Google Cloud , pencatatan setelan lantai untuk operasi pembersihan diaktifkan secara default untuk Vertex AI, tetapi dinonaktifkan secara default untuk server MCP.

Jika Anda memiliki persyaratan residensi data, Anda harus mengonfigurasi sink log untuk merutekan log ke lokasi penyimpanan yang sesuai sebelum mengaktifkan Cloud Logging dalam prosedur berikutnya. Mengonfigurasi sink log akan membantu memastikan log Model Armor disimpan di bucket regional yang sesuai. Untuk mengetahui informasi selengkapnya, lihat Membagi log Anda berdasarkan wilayah.

Anda dapat mengaktifkan logging operasi sanitasi untuk Vertex AI dan server MCP yang dikelola Google secara terpisah. Jika diaktifkan, log akan menyertakan perintah dan respons (untuk Vertex AI) atau panggilan alat dan respons alat (untuk server MCP), hasil evaluasi Model Armor, dan kolom metadata tambahan.

Konsol

1. Di konsol Google Cloud , buka halaman Model Armor.

   Buka Model Armor

2. Pastikan Anda melihat project tempat Anda mengaktifkan Model Armor.

3. Buka tab Setelan Lantai.

4. Di bagian Log, pilih MCP yang dikelola Google.

5. Klik Simpan.

gcloud

Anda dapat menggunakan salah satu flag berikut untuk mengelola logging operasi pembersihan di setelan lantai.

Untuk mengaktifkan Logging, gunakan salah satu flag berikut:

• Untuk Vertex AI, gunakan tanda --enable-vertex-ai-cloud-logging.
• Untuk server MCP yang dikelola Google, gunakan flag --enable-google-mcp-server-cloud-logging.

Untuk menonaktifkan Logging, gunakan salah satu flag berikut:

• Untuk Vertex AI, gunakan tanda --no-enable-vertex-ai-cloud-logging.

• Untuk server MCP yang dikelola Google, gunakan flag --no-enable-google-mcp-server-cloud-logging.

  Catatan: Anda dapat mengaktifkan atau menonaktifkan logging untuk satu atau kedua layanan menggunakan satu perintah.

Contoh perintah berikut mengaktifkan logging operasi pembersihan untuk server MCP yang dikelola Google dan Vertex AI:

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

Anda dapat menggunakan metode UpdateFloorSetting untuk memperbarui setelan lantai guna mengaktifkan logging operasi sanitasi. Saat menggunakan metode ini, pastikan untuk menetapkan parameter yang sesuai ke benar (true) untuk mengaktifkan logging:

• Untuk Vertex AI, tetapkan aiPlatformFloorSetting.enableCloudLogging ke true.

• Untuk server MCP yang dikelola Google, setel googleMcpServerFloorSetting.enableCloudLogging ke true.

Contoh perintah berikut mengaktifkan logging operasi pembersihan untuk server MCP yang dikelola Google dan Vertex AI:

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, pertama-tama siapkan lingkungan pengembangan Python 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 log

Untuk melihat log Model Armor, Anda dapat menggunakan Logs Explorer di Logging dengan mengikuti langkah-langkah berikut:

1. Buka Logs Explorer di konsol Google Cloud . Untuk mengetahui informasi selengkapnya, lihat Melihat log menggunakan Logs Explorer.
2. Filter log menurut nama layanan modelarmor.googleapis.com.
3. Cari entri yang terkait dengan operasi yang Anda aktifkan di template. Untuk mengetahui daftar semua nama layanan dan jenis resource yang dimonitor, lihat Resource dan layanan yang dimonitor.

Memfilter log Model Armor

Anda dapat menggunakan label log untuk memfilter log Model Armor untuk operasi sanitasi dan logging template. Untuk melakukannya, ikuti petunjuk berikut:

Jalankan kueri berikut di Logs Explorer untuk memfilter log operasi sanitasi.

jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"

Untuk lebih menyaring log operasi sanitasi, Anda dapat menentukan project ID, nama klien, atau ID korelasi dalam kueri.

• Menggunakan ID project:

  jsonPayload.@type="type.googleapis.com%2Fgoogle.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry";project=PROJECT_ID
  

• Menggunakan nama klien:

  jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"
  labels."modelarmor.googleapis.com/client_name"="CLIENT_NAME"
  

• Menggunakan ID korelasi:

  labels."modelarmor.googleapis.com/client_correlation_id"="CORRELATION_ID"
  

Ganti kode berikut:

• PROJECT_ID: Google Cloud Project ID
• CLIENT_NAME: nama klien Anda.
• CORRELATION_ID: ID unik yang Anda buat untuk permintaan tertentu.

Menghubungkan log dan peristiwa terkait

Untuk mengaitkan log dan peristiwa untuk interaksi tertentu, Anda dapat menggunakan ID korelasi klien. ID ini adalah ID unik yang Anda buat (misalnya, UUID) yang melacak permintaan tertentu di seluruh sistem Anda. Untuk menyetel ID korelasi klien di header curl, gunakan opsi -H untuk menyertakan header kustom dalam permintaan Anda.

Berikut contoh formatnya:

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 tempat template berada.
• LOCATION: lokasi template.
• TEMPLATE_ID: ID template.
• USER_PROMPT: perintah yang diberikan ke model.
• MODEL_RESPONSE: respons yang diterima dari model.

Kirim masukan