‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

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

במאמר הזה מוסבר איך להגדיר את 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, נדרשת ההרשאה serviceusage.services.enable. אם יצרתם את הפרויקט, סביר להניח שכבר יש לכם את ההרשאה הזו דרך התפקיד 'בעלים' (roles/owner). אחרת, תוכלו לקבל את ההרשאה הזו דרך התפקיד 'אדמין בממשק Service Usage' (roles/serviceusage.serviceUsageAdmin). איך מקצים תפקידים
להפעלת ה-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 עם הגנה מוגברת על המודל ורוצים להשתמש באזור או במספר אזורים שונים מאזור ברירת המחדל us. כדי לוודא שה-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 ו- Google Cloud MCP בנפרד. כשמפעילים את האפשרות הזו, היומנים כוללים את ההנחיה והתשובה (ב-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 ו- Google Cloud MCP. כדי להשבית את הרישום ביומן, משתמשים בדגלים --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. כולל מטא-נתונים כמו המתקשר, השיטה, המשאב, חותמת הזמן והסטטוס.	כולל את המטען הייעודי המלא, כמו ההנחיה או טקסט התשובה, תוצאות הסינון ופרטים אחרים של הניקוי.
מנגנון ההפעלה	הגדרות סטנדרטיות Google Cloud של יומני ביקורת ב-IAM עבור Model Armor API. לרוב צריך להפעיל את יומני הגישה לנתונים באופן מפורש. יומני ביקורת לפעולות בתבניות נוצרים באופן אוטומטי.	כדי להפעיל את האפשרות הזו, צריך להגדיר את הדגל הבוליאני `log_sanitize_operations` במטא-נתונים של התבנית או בהגדרות אבטחה מינימליות.
תנאי הרישום	היומנים יוצרים, קוראים, מעדכנים, מוחקים ומציגים ברשימה פעולות בתבניות ובהגדרות של הרצפה באופן אוטומטי.	מתעד נתונים (הנחיות למשתמשים ותגובות של מודלים) לכל הבקשות במישור הנתונים, בלי קשר להפעלה של Sensitive Data Protection או להתאמה של הגדרות מסנן כלשהן.
נפח היומן והעלות	בדרך כלל קטנים יותר וצפויים יותר, וחל עליהם תמחור רגיל של Cloud Logging.	יכול להיות שהם יהיו גדולים מאוד, מה שעלול להוביל לעלויות גבוהות ב-Cloud Logging בגלל מטען ייעודי גדול ושימוש תדיר. יכול להיות שמטענים גדולים יפוצלו לכמה רשומות ביומן.
שיקולי אבטחה	יחסית בטוח כי נתוני המטען הייעודי לא מתועדים ביומן. נדרשות הרשאות IAM מיוחדות כדי לגשת אליהם (לדוגמה, תפקידי IAM ספציפיים כדי לצפות ביומני ביקורת).	מכילה נתוני משתמשים רגישים (פרטים אישיים מזהים, מידע סודי). הגישה ליומן פתוחה לכל מי שיש לו הרשאת צפייה ביומן (לדוגמה, `roles/logging.privateLogViewer`).
המלצה	הפעלה לצורך מעקב כללי אחרי אבטחה ותאימות.	לא מומלץ לשימוש בנתוני ייצור או במידע אישי רגיש, אלא אם הם מנותבים בצורה מאובטחת ל-sink עם בקרת גישה (לדוגמה, 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.

המאמרים הבאים

השוואה בין יומני Model Armor לבין יומני Gemini Enterprise

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

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

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

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

המסוף

gcloud

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

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

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

המסוף

REST

Python

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

המסוף

gcloud

REST

Python

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

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

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

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

המאמרים הבאים

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