Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

הגדרת רישום ביומן

במאמר הזה מוסבר איך להגדיר את Model Armor כדי לרשום ביומן את הפעולות הבאות:

פעולות שיוצרות, מעדכנות או מוחקות תבנית
פעולות שמבצעות סניטציה של הנחיה למשתמש או של תשובת מודל

ב-הגנה מוגברת על המודל נעשה שימוש ביומני ביקורת כדי לתעד פעילויות אדמין ופעילויות של ניהול משאבים. מידע נוסף זמין במאמר בנושא רישום ביומן ביקורת של הגנה מוגברת על המודל.

למידע על תמחור היומנים, ראו תמחור של Cloud Logging. יכול להיות שיהיו גם חיובים על השימוש ב-Model Armor, בהתאם לנפח הנתונים שעוברים עיבוד. פרטים נוספים זמינים במאמר בנושא תמחור של Model Armor.

לפני שמתחילים

לפני שמתחילים, צריך לבצע את המשימות הבאות.

קבלת ההרשאות הנדרשות

כדי לקבל את ההרשאות שנדרשות להגדרת רישום ביומן עבור Model Armor, צריך לבקש מהאדמין להקצות לכם את תפקיד ה-IAM‏ Model Armor Admin (roles/modelarmor.admin) בתבנית Model Armor. כדי לקרוא הסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.

יכול להיות שאפשר לקבל את ההרשאות הנדרשות גם באמצעות תפקידים בהתאמה אישית או תפקידים מוגדרים מראש.

הפעלת ממשקי ה-API

כדי להשתמש בהגנה מוגברת על המודל, צריך להפעיל את Model Armor API.

המסוף

מפעילים את הגנה מוגברת על המודל API.
תפקידים שנדרשים להפעלת ממשקי API
כדי להפעיל ממשקי API, צריך את תפקיד ה-IAM 'אדמין של Service Usage' (roles/serviceusage.serviceUsageAdmin), שכולל את ההרשאה serviceusage.services.enable. איך מקצים תפקידים
להפעלת ה-API
בוחרים את הפרויקט שבו רוצים להפעיל את הגנה מוגברת על המודל.

gcloud

לפני שמתחילים, צריך לבצע את השלבים הבאים באמצעות Google Cloud CLI עם Model Armor API:

במסוף Google Cloud , מפעילים את Cloud Shell.

הפעלת Cloud Shell

בחלק התחתון של Google Cloud המסוף יתחיל סשן של Cloud Shell ותופיע הודעה של שורת הפקודה. Cloud Shell היא סביבת מעטפת שבה ה-CLI של Google Cloud מותקן ומוגדרים ערכים לפרויקט הקיים. הסשן יופעל תוך כמה שניות.
הגדרת שינוי מברירת המחדל של נקודת קצה ל-API באמצעות ה-CLI של gcloud

הגדרת שינוי מברירת המחדל של נקודת קצה ל-API באמצעות ה-CLI של gcloud

השלב הזה נדרש רק אם משתמשים ב-CLI של gcloud כדי להפעיל את Model Armor API. כדי לוודא שה-CLI של gcloud מנתב את הבקשות לשירות Model Armor בצורה נכונה, צריך להגדיר ידנית את החלפת נקודת הקצה של ה-API.

מריצים את הפקודה הבאה כדי להגדיר את נקודת קצה ל-API לשירות הגנה מוגברת על המודל.

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

מחליפים את LOCATION באזור שבו רוצים להשתמש בהגנה מוגברת על המודל.

הגדרת ניקוי תעבורה

בשרתי Google ו- Google Cloud MCP, מגדירים ניקוי של תעבורת נתונים דרך הגדרות אבטחה מינימליות. מידע נוסף זמין במאמר בנושא הגדרת הגנה לשרתי Google ו-Google Cloud MCP.

הגדרת רישום ביומן בתבניות

בתבניות מוגדרים המסננים והסף לקטגוריות שונות של בטיחות ואבטחה. כשיוצרים או מעדכנים תבנית Model Armor, אפשר לציין אם המערכת תתעד פעולות מסוימות ב-Model Armor. משתמשים בדגלים הבאים במטא-נתונים של התבנית:

‫log_template_operations: ערך בוליאני שמאפשר לכם לרשום ביומן את הפעולות של יצירה, עדכון, קריאה ומחיקה של תבנית.
‫log_sanitize_operations: ערך בוליאני שמאפשר לכם לרשום ביומן את התוכן המלא של ההנחיות למשתמשים והתשובות של המודל במהלך פעולות ניקוי.

המסוף

נכנסים לדף הגנה מוגברת על המודל במסוף Google Cloud .

מעבר אל הגנה מוגברת על המודל
ודאו שאתם צופים בפרויקט שבו הפעלתם את הגנה מוגברת על המודל.
בדף Model Armor (הגנה על מודלים), לוחצים על Create Template (יצירת תבנית). מידע נוסף על יצירת תבניות זמין במאמר בנושא יצירת תבנית הגנה מוגברת על המודל.
בקטע Configure logging (הגדרת רישום ביומן), בוחרים את הפעולות שרוצים להגדיר עבורן רישום ביומן.
לוחצים על יצירה.

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"

מחליפים את מה שכתוב בשדות הבאים:

‫PROJECT_ID: מזהה הפרויקט שאליו שייך התבנית.
‫LOCATION: המיקום של התבנית.
‫TEMPLATE_ID: מזהה התבנית.

Python

כדי להריץ את הקוד הזה, קודם צריך להגדיר סביבת פיתוח של Python ולהתקין את 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)

מחליפים את מה שכתוב בשדות הבאים:

‫PROJECT_ID: מזהה הפרויקט שאליו שייך התבנית.
‫LOCATION: המיקום של התבנית.
‫TEMPLATE_ID: מזהה התבנית.

הגדרת רישום ביומן בהגדרות אבטחה מינימליות

כשמחילים הגדרות אבטחה מינימליות על תעבורת נתונים ממודלים של Gemini ב-Gemini Enterprise Agent Platform ובשרתי Google ו-MCP בפרויקט, הגדרות אבטחה מינימליות מגדירות את מסנני הבטיחות והאבטחה לפעולות ניקוי. Google Cloud כשמעדכנים את הגדרות הרצפה של Model Armor, אפשר לציין אם פעולות החיטוי של יומני Model Armor יתבצעו.

אפשר להפעיל את הרישום של פעולות החיטוי בנפרד עבור Agent Platform ושרתי Google ו-MCP. Google Cloud כשההגדרה הזו מופעלת, היומנים כוללים את ההנחיה והתשובה (במקרה של Agent Platform) או את הקריאות לכלי ואת התשובות של הכלי (במקרה של שרתי MCP), את תוצאות ההערכה של Model Armor ושדות נוספים של מטא-נתונים.

בדוגמאות הבאות אפשר לראות איך להפעיל רישום ביומן של פעולות ניקוי גם ב-Agent Platform וגם בשרתים של Google ושל Google Cloud MCP.

המסוף

נכנסים לדף הגנה מוגברת על המודל במסוף Google Cloud .

מעבר אל הגנה מוגברת על המודל
ודאו שאתם צופים בפרויקט שבו הפעלתם את הגנה מוגברת על המודל.
עוברים לכרטיסייה הגדרות הרצפה.
בקטע Logs, מסמנים את תיבות הסימון Vertex AI ו-Google managed MCP כדי להפעיל את הרישום ביומן לכל שירות.
לוחצים על Save.

gcloud

משתמשים בדגל --enable-vertex-ai-cloud-logging כדי להפעיל רישום ביומן של Agent Platform, ובדגל --enable-google-mcp-server-cloud-logging כדי להפעיל רישום ביומן של שרתי Google ו-MCP. Google Cloud כדי להשבית את הרישום ביומן, משתמשים בדגלים --no-enable-vertex-ai-cloud-logging ו---no-enable-google-mcp-server-cloud-logging.

הפקודה הבאה מאפשרת רישום ביומן של פעולות ניקוי גם ב-Agent Platform וגם בשרתי Google ו- Google Cloud MCP:

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

מחליפים את PROJECT_ID במזהה הפרויקט.

REST

כדי להפעיל את הרישום ביומן, מגדירים את aiPlatformFloorSetting.enableCloudLogging ל-true עבור Agent Platform ואת googleMcpServerFloorSetting.enableCloudLogging ל-true עבור שרתי Google ו- Google Cloud MCP בשיטה UpdateFloorSetting.

הפקודה הבאה מאפשרת רישום ביומן של פעולות ניקוי גם ב-Agent Platform וגם בשרתים של 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"

מחליפים את PROJECT_ID במזהה הפרויקט.

Python

כדי להריץ את הקוד הזה, קודם צריך להגדיר סביבת פיתוח של Python ולהתקין את 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}")

מחליפים את PROJECT_ID במזהה הפרויקט.

הצגה וסינון של יומנים של הגנה מוגברת על המודל

כדי להציג ולסנן יומנים של הגנה מוגברת על המודל, משתמשים ב-Logs Explorer ב-Logging:

נכנסים לדף Logs Explorer במסוף Google Cloud .

כניסה לדף Logs Explorer

מידע נוסף זמין במאמר צפייה ביומנים באמצעות Logs Explorer.
בחלונית השאילתות, מזינים אחת מהשאילתות הבאות כדי לסנן את יומני הגנה מוגברת על המודל:
- כדי לראות את כל היומנים של הגנה מוגברת על המודל, כולל יומני ביקורת ויומנים של פעולות ניקוי:
```
protoPayload.serviceName="modelarmor.googleapis.com" OR jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"
```
- כדי לראות רק את יומני הביקורת של Model Armor:
```
protoPayload.serviceName="modelarmor.googleapis.com"
```
  במאמר משאבים ושירותים במעקב תוכלו למצוא רשימה של כל שמות השירותים וסוגי המשאבים במעקב.
- כדי לראות רק את היומנים של Model Armor לפעולות ניקוי:
```
jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"
```
  כדי לחדד עוד יותר את יומני הפעולות של ניקוי הנתונים, אפשר לציין שם לקוח או מזהה קורלציה בשאילתה.
  - שימוש בשם לקוח: כש-הגנה מוגברת על המודל משולב עם שירותים כמו Gemini Enterprise Agent Platform או Gemini Enterprise, אפשר להשתמש בשם הלקוח כדי לסנן יומנים של שילוב ספציפי.
```
jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"
labels."modelarmor.googleapis.com/client_name"="CLIENT_NAME"
```
  - שימוש במזהה קורלציה:
```
jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"
labels."modelarmor.googleapis.com/client_correlation_id"="CORRELATION_ID"
```
  מחליפים את מה שכתוב בשדות הבאים:
  - ‫CLIENT_NAME: השם של הלקוח. משתמשים באחד מהערכים הבאים:
    - ‫CLIENT_NAME_UNSPECIFIED: ערך ברירת המחדל, שמשמש כשהשם של הלקוח לא מצוין.
    - ‫VERTEX_AI: לשילוב עם Gemini Enterprise Agent Platform.
    - LOAD_BALANCER: לשילוב באמצעות תוסף Load Balancer as a Service.
    - ‫LANGCHAIN: לשילוב עם LangChain.
    - ‫GEMINI_ENTERPRISE_BUSINESS: לשילוב עם Gemini Enterprise – מהדורת Business.
    - ‫GOOGLE_MCP_SERVER: לשילוב עם שרתי MCP שמנוהלים על ידי Google.
    - ‫AGENT_GATEWAY: לשילוב עם Agent Gateway.
    - GEMINI_ENTERPRISE_NON_BUSINESS לשילוב עם מהדורות Gemini Enterprise שאינן Business (Standard, ‏ Plus, ‏ Frontline).
    - SECURE_WEB_PROXY לשילוב עם Secure Web Proxy.
  - ‫CORRELATION_ID: המזהה הייחודי שנוצר לבקשה ספציפית.

הצלבת נתונים בין יומנים ואירועים קשורים

כדי לבצע קורלציה בין יומנים ואירועים של אינטראקציה ספציפית, אפשר להשתמש במזהה קורלציה של לקוח הגנה מוגברת על המודל. המזהה הזה הוא מזהה ייחודי שאתם יוצרים (למשל, UUID) שמאפשר לעקוב אחרי בקשה ספציפית במערכת שלכם. כדי להגדיר מזהה קורלציה של לקוח בכותרת curl, משתמשים באפשרות -H כדי לכלול בכותרת בקשה מותאמת אישית MA-Client-Correlation-Id.

דוגמה לפורמט:

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"

מחליפים את מה שכתוב בשדות הבאים:

‫PROJECT_ID: מזהה הפרויקט שאליו שייך התבנית.
‫LOCATION: המיקום של התבנית.
‫TEMPLATE_ID: מזהה התבנית.
‫USER_PROMPT: ההנחיה שסופקה למודל.
‫MODEL_RESPONSE: התשובה שהתקבלה מהמודל.

יומני פלטפורמה לעומת יומני ביקורת של Cloud

חשוב להבחין בין הרישומים שאפשר להפעיל בתבנית הגנה מוגברת על המודל או בהגדרות אבטחה מינימליות לבין יומני הביקורת של Cloud.

תכונה	יומני ביקורת של Cloud	יומני פלטפורמה
המטרה העיקרית	ביקורת אבטחה של קריאות ל-API (מי עשה מה ומתי) וניטור התאימות.	מעקב תפעולי, ניפוי באגים וניתוח מפורט של אירועי חיטוי.
פעולות API שתועדו	פעולות יצירה, קריאה, עדכון, מחיקה והצגה ברשימה של תבניות והגדרות של רצפות. פעולות ניקוי (`SanitizeUserPrompt`, `SanitizeModelResponse`) נרשמות כמטא-נתונים.	מציג את כל הבקשות, כמו `SanitizeUserPrompt` ו-`SanitizeModelResponse`.
תוכן המטען הייעודי	לא כולל את ההנחיה בפועל למשתמש או את טקסט התגובה של המודל לפעולות של sanitize. מכיל מטא-נתונים כמו המתקשר, השיטה, המשאב, חותמת הזמן והסטטוס.	כולל את המטען הייעודי המלא, כמו ההנחיה או טקסט התשובה, תוצאות הסינון ופרטים אחרים של החיטוי.
מנגנון ההפעלה	הגדרות סטנדרטיות של יומני ביקורת ב-IAM עבור Model Armor API. Google Cloud ברוב המקרים, צריך להפעיל את יומני הגישה לנתונים באופן מפורש. יומני ביקורת לפעולות בתבניות נוצרים באופן אוטומטי.	כדי להפעיל את האפשרות הזו, צריך להגדיר את הדגל הבוליאני `log_sanitize_operations` במטא-נתונים של התבנית או בהגדרות אבטחה מינימליות.
תנאי רישום ביומן	היומנים יוצרים, קוראים, מעדכנים, מוחקים ומציגים ברשימה פעולות בתבניות ובהגדרות של רצפות באופן אוטומטי.	מתעד נתונים (הנחיות למשתמשים ותגובות של מודלים) לכל בקשה במישור הנתונים, בלי קשר לשאלה אם Sensitive Data Protection מופעלת או אם יש התאמה להגדרת מסנן כלשהי.
נפח היומן והעלות	בדרך כלל קטנים יותר וצפויים יותר, ועלותם היא בהתאם לתמחור הרגיל של Cloud Logging.	יכול להיות גדול מאוד, מה שעלול להוביל לעלויות גבוהות ב-Cloud Logging בגלל מטען ייעודי גדול ושימוש תדיר. יכול להיות שמטענים גדולים יפוצלו לכמה רשומות ביומן.
שיקולי אבטחה	יחסית בטוח כי נתוני המטען הייעודי לא מתועדים ביומן. נדרשות הרשאות IAM מיוחדות כדי לגשת אליהם (לדוגמה, תפקידי IAM ספציפיים כדי לצפות ביומני ביקורת).	מכיל נתוני משתמשים רגישים (פרטים אישיים מזהים, מידע סודי). הגישה אפשרית לכל מי שיש לו הרשאות צפייה ביומן (לדוגמה, `roles/logging.privateLogViewer`).
המלצה	הפעלה לצורך מעקב כללי אחרי אבטחה ותאימות.	לא מומלץ לשימוש בנתוני ייצור או במידע אישי רגיש, אלא אם הם מנותבים בצורה מאובטחת ליעד עם בקרת גישה (לדוגמה, BigQuery עם IAM מחמיר).

הפעלת הרישום בתבנית כותבת הנחיות ותשובות גולמיות לרישום. הנתונים האלה עשויים לכלול נתוני משתמש רגישים, פרטים אישיים מזהים (PII) או מידע סודי. תנועה גבוהה ומטענים גדולים עלולים להוביל לעלויות תיעוד משמעותיות ולנפחי יומן גדולים שחורגים מהמגבלות, ולכן נדרש ניהול קפדני.

זהות המתקשר ביומני הביקורת

כשאתם צופים ביומני ביקורת, יומני הביקורת של Cloud מתעדים את הזהות של המתקשר בשדה protoPayload.authenticationInfo.principalEmail. הזהות שמתועדת תלויה באופן הקריאה ל-API של הגנה מוגברת על המודל:

הפעלה ישירה של API: אם משתמש או חשבון שירות קוראים ישירות ל-API של הגנה מוגברת על המודל (לדוגמה, באמצעות gcloud, ספריות לקוח או ממשקי API בארכיטקטורת REST), אז principalEmail מכיל את כתובת האימייל של המשתמש או חשבון השירות הזה.
הפעלה דרך שירות משולב Google Cloud : אם הגנה מוגברת על המודל משולב עם שירות אחרGoogle Cloud , כמו Gemini Enterprise Agent Platform, אז principalEmail מכיל את הזהות של השירות הזה, שלרוב היא חשבון שירות שמנוהל על ידי Google. הפורמט של סוכני שירות הוא service-PROJECT_NUMBER@SERVICE_NAME.iam.gserviceaccount.com. לדוגמה, שיחה שמקורה בתכונה של Gemini Enterprise Agent Platform משתמשת בסוכן שירות של Gemini Enterprise Agent Platform.

כדי להבחין בין המתקשרים, בודקים את השדה principalEmail ברשומה ביומן הביקורת. בשיחות ממשתמשי קצה או מחשבונות שירות בניהול המשתמשים מוצגות כתובות האימייל שלהם, ובשיחות דרך שירותים אחרים Google Cloud מוצגות כתובות האימייל של חשבונות שירות שמנוהלים על ידי Google.

הגדרת רישום ביומן קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

לפני שמתחילים

קבלת ההרשאות הנדרשות

הפעלת ממשקי ה-API

המסוף

gcloud

הגדרת שינוי מברירת המחדל של נקודת קצה ל-API באמצעות ה-CLI של gcloud

הגדרת ניקוי תעבורה

הגדרת רישום ביומן בתבניות

המסוף

REST

Python

הגדרת רישום ביומן בהגדרות אבטחה מינימליות

המסוף

gcloud

REST

Python

הצגה וסינון של יומנים של הגנה מוגברת על המודל

הצלבת נתונים בין יומנים ואירועים קשורים

יומני פלטפורמה לעומת יומני ביקורת של Cloud

זהות המתקשר ביומני הביקורת

הגדרת רישום ביומן