מדיניות SanitizeModelResponse

מדיניות ניתנת להרחבה

הדף הזה רלוונטי ל-Apigee ול-Apigee Hybrid.

לעיון במסמכי התיעוד של Apigee Edge

המדיניות SanitizeModelResponse מגנה על לקוחות AI מפני תוכן מזיק או פוגעני על ידי ניקוי תשובות ממודלים של AI גנרטיבי. המדיניות משתמשת ב-Model Armor כדי להעריך את התשובות של המודל ולבדוק אם הן מכילות תוכן פוגעני או מזיק, וכך מאפשרת הגנה מקורית ללקוחות ולעומסי עבודה של AI באמצעות Apigee. הגנה מוגברת על המודל היא שירות שמציע אמצעי אבטחה ובטיחות ל-AI, כדי לצמצם את הסיכונים שקשורים למודלים גדולים של שפה (LLM). Google Cloud

המדיניות הזו משמשת בשילוב עם המדיניות SanitizeUserPrompt.

המדיניות הזו היא מדיניות שניתנת להרחבה, והשימוש בה עשוי להשפיע על העלויות או על הניצול, בהתאם לרישיון Apigee שלכם. מידע על סוגי המדיניות וההשלכות של השימוש זמין במאמר סוגי מדיניות.

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

לפני שמשתמשים במדיניות SanitizeModelResponse, צריך לבצע את המשימות הבאות:

• יוצרים תבנית Model Armor. חובה להשלים את השלב הזה לפני שיוצרים מדיניות SanitizeModelResponse.
• מגדירים את נקודת הקצה ל-API לשירות הגנה מוגברת על המודל.

התפקידים הנדרשים

כדי לקבל את ההרשאות שדרושות להחלה ולשימוש במדיניות SanitizeModelResponse, צריך לבקש מהאדמין להקצות לכם את תפקידי ה-IAM הבאים בחשבון השירות שבו אתם משתמשים כדי לפרוס פרוקסי של Apigee:

• משתמש בהגנה מוגברת על המודל (roles/modelarmor.user)
• צפייה ב-Model Armor (roles/modelarmor.viewer)

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

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

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

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

תפקידים שנדרשים להפעלת ממשקי API

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

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

רכיב <SanitizeModelResponse>

הגדרת מדיניות SanitizeModelResponse.

ערך ברירת מחדל	מידע נוסף מופיע בכרטיסייה מדיניות ברירת המחדל שבהמשך.
חובה?	חובה
סוג	אובייקט מורכב
רכיב אב	לא רלוונטי
רכיבי צאצא	<DisplayName> <IgnoreUnresolvedVariables> <TemplateName> <UserPromptSource> <LLMResponseSource>

רכיב <SanitizeModelResponse> משתמש בתחביר הבא:

תחביר

<SanitizeModelResponse async="false" continueOnError="false" enabled="true" name="sanitize-response">
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <DisplayName>sanitize-response-sample</DisplayName>
  <ModelArmor>
    <TemplateName>projects/{project}/locations/{location}/templates/{template-name}</TemplateName>
  </ModelArmor>
  <UserPromptSource>{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}</UserPromptSource>
  <LLMResponseSource>{jsonPath('$.candidates[-1].content.parts',response.content,true)}</LLMResponseSource>
</SanitizeModelResponse>

מדיניות ברירת המחדל

בדוגמה הבאה מוצגות הגדרות ברירת המחדל כשמוסיפים מדיניות SanitizeModelResponse לזרימת הבקשות בממשק המשתמש של Apigee:

<SanitizeModelResponse async="false" continueOnError="false" enabled="true" name="sanitize-response">
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <DisplayName>sanitize-response-sample</DisplayName>
  <ModelArmor>
    <TemplateName>projects/{project}/locations/{location}/templates/{template-name}</TemplateName>
  </ModelArmor>
  <UserPromptSource>{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}</UserPromptSource>
  <LLMResponseSource>{jsonPath('$.candidates[-1].content.parts',response.content,true)}</LLMResponseSource>
</SanitizeModelResponse>

כשמוסיפים מדיניות חדשה של SanitizeModelResponse באמצעות ממשק המשתמש של Apigee, התבנית מכילה placeholders לכל הפעולות האפשריות. בהמשך מפורט מידע על האלמנטים הנדרשים.

לרכיב הזה יש את המאפיינים הבאים שמשותפים לכל המדיניות:

מאפיין	ברירת מחדל	חובה?	תיאור
name	לא רלוונטי	חובה	השם הפנימי של המדיניות. הערך של מאפיין name יכול להכיל אותיות, מספרים, רווחים, מקפים, קווים תחתונים ונקודות. הערך הזה לא יכול להיות ארוך מ-255 תווים. אפשר להשתמש ברכיב <DisplayName> כדי לתת למדיניות תווית בשם אחר בשפה טבעית בכלי לעריכת פרוקסי בממשק המשתמש לניהול.
continueOnError	FALSE	אופציונלי	מגדירים את הערך false כדי להחזיר שגיאה אם המדיניות נכשלת. זו התנהגות צפויה ברוב המקרים. הגדרה ל-true מאפשרת להמשיך את הביצוע של התהליך גם אחרי שמדיניות נכשלת. מאמרים קשורים: הפעלת כללי תקלות מתבצעת רק במצב שגיאה (מידע על continueOnError) טיפול בתקלות בתהליך הנוכחי
enabled	TRUE	אופציונלי	מגדירים את הערך true כדי לאכוף את המדיניות, או את הערך false כדי להשבית את המדיניות. המדיניות לא נאכפת גם אם היא עדיין משויכת לזרימה.
async	FALSE	הוצא משימוש	המאפיין הזה הוצא משימוש.

בטבלה הבאה מפורט תיאור כללי של רכיבי המשנה של <SanitizeModelResponse>:

רכיב צאצא	חובה?	תיאור
<DisplayName>	אופציונלי	שם המדיניות.
<IgnoreUnresolvedVariables>	אופציונלי	המדיניות קובעת אם העיבוד ייפסק אם המשתנה שמשמש לשם התבנית או למטען הייעודי (payload) של הגנה מוגברת על המודל לא נפתר.
<TemplateName>	חובה	תבנית הגנה מוגברת על המודל ששימשה לניקוי התשובה של ה-LLM. אפשר להשתמש בתבנית לערך הזה באמצעות משתני הזרימה הבאים של Apigee: projects/{organization.name}/locations/{system.region.name}/templates/{id}
<UserPromptSource>	חובה	המיקום של מטען הייעודי (payload) שבו נמצא הטקסט של הנחיית המשתמש שרוצים לחלץ. יש תמיכה רק בערכי טקסט מסוג מחרוזת. השדה הזה תומך בתחביר של תבניות הודעות ב-Apigee, כולל שימוש ב משתנים או בפונקציות של נתיב JSON. לדוגמה: {jsonpath('$.contents[-1].parts[-1].text',request.content,false)}
<LLMResponseSource>	חובה	המיקום של מטען הייעודי (payload) של טקסט התשובה של ה-LLM שרוצים לחלץ. יש תמיכה רק בערכי טקסט מסוג מחרוזת. השדה הזה תומך בתחביר של תבניות הודעות ב-Apigee, כולל שימוש ב משתנים או בפונקציות של נתיב JSON. לדוגמה: {jsonpath('$.input.prompt.text',request.content,false)}

הפניה לרכיב צאצא

בקטע הזה מתוארים רכיבי הבן של <SanitizeModelResponse>.

<DisplayName>

אפשר להשתמש במאפיין הזה בנוסף למאפיין name כדי לתת למדיניות שם אחר, שנשמע יותר טבעי, ב-UI של עורך ה-proxy לניהול.

הרכיב <DisplayName> משותף לכל סוגי המדיניות.

ערך ברירת המחדל	לא רלוונטי
חובה?	זה שינוי אופציונלי. אם לא מציינים את <DisplayName>, המערכת משתמשת בערך של מאפיין name של המדיניות.
סוג	String
רכיב אב	<PolicyElement>
רכיבי צאצא	ללא

רכיב <DisplayName> משתמש בתחביר הבא:

תחביר

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

דוגמה

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

לרכיב <DisplayName> אין מאפיינים או רכיבי צאצא.

<IgnoreUnresolvedVariables>

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

ערך ברירת מחדל	לא נכון
חובה?	אופציונלי
סוג	בוליאני
רכיב אב	<SanitizeModelResponse>
רכיבי צאצא	ללא

<TemplateName>

תבנית הגנה מוגברת על המודל.

ערך ברירת מחדל	לא רלוונטי
חובה?	חובה
סוג	String
רכיב אב	<SanitizeModelResponse>
רכיבי צאצא	ללא

רכיב <TemplateName> משתמש בתחביר הבא:

תחביר

<ModelArmor>
  <TemplateName>projects/{project}/locations/{location}/templates/{template-name}</TemplateName>
</ModelArmor>

דוגמה

בדוגמה הזו נעשה שימוש במשתני זרימה של Apigee כדי לאכלס את המידע הנדרש.

<ModelArmor>
  <TemplateName>projects/{organization.name}/locations/{system.region.name}/templates/{id}</TemplateName>
</ModelArmor>

<UserPromptSource>

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

השדה הזה תומך בתחביר של תבניות הודעות ב-Apigee, כולל שימוש ב משתנים או בפונקציות של נתיב JSON. לדוגמה:

{jsonpath('$.input.prompt.text',request.content,false)}

ערך ברירת מחדל	{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}
חובה?	חובה
סוג	String
רכיב אב	<SanitizeModelResponse>
רכיבי צאצא	ללא

<LLMResponseSource>

המיקום של מטען הייעודי (payload) לתגובת ה-LLM שצריך לחלץ. יש תמיכה רק בערכי טקסט מסוג מחרוזת.

השדה הזה תומך בתחביר של תבניות הודעות ב-Apigee, כולל שימוש ב משתנים או בפונקציות של נתיב JSON. לדוגמה:

{jsonpath('$.input.prompt.text',request.content,false)}

ערך ברירת מחדל	{jsonPath($.candidates[-1].content.parts,response.content,true)}
חובה?	חובה
סוג	String
רכיב אב	<SanitizeModelResponse>
רכיבי צאצא	ללא

משתנים בתהליך

אפשר להשתמש במשתני Flow כדי להגדיר התנהגות דינמית בזמן ריצה של כללי מדיניות ושל Flows, על סמך כותרות HTTP או תוכן ההודעה, או ההקשר שזמין ב-Flow. מידע נוסף על משתני זרימה זמין במאמר חומר עזר בנושא משתני זרימה.

המדיניות הזו מספקת את קבוצת משתני הזרימה הבאה שהם לקריאה בלבד במהלך ההרצה. אפשר להשתמש במשתני הזרימה האלה עם מדיניות DataCapture כדי ליצור דוחות ניתוח בהתאמה אישית. מידע נוסף זמין במאמר בנושא איסוף נתוני לקוחות בהתאם למדיניות בנושא איסוף נתונים.

שם המשתנה	תיאור
SanitizeModelResponse.POLICY_NAME.templateUsed	מציין באיזו תבנית של שריון המודל משתמש. לדוגמה: projects/myproject/locations/us-west1/templates/mytemplate
SanitizeModelResponse.POLICY_NAME.userPrompt	מציינת את תוכן הפרומפט שמשמש לקריאה ל-הגנה מוגברת על המודל כדי לבצע סניטציה של התוכן.
SanitizeModelResponse.POLICY_NAME.modelResponse	מציינת את תוכן התשובה של ה-LLM שמשמש לקריאה ל-הגנה מוגברת על המודל כדי לבצע סניטציה של התוכן.
SanitizeModelResponse.POLICY_NAME.responseFromModelArmor	מציין את תגובת ה-JSON מ-Model Armor. הגנה מוגברת על המודל.
SanitizeModelResponse.POLICY_NAME.filterMatchState	מציין אם המסנן התאים. הערכים התקפים כוללים את MATCH_FOUND ואת NO_MATCH_FOUND.
SanitizeModelResponse.POLICY_NAME.invocationResult	שדה שמציין את התוצאה של הקריאה, ללא קשר לסטטוס ההתאמה. הוא יכול לכלול את הפרטים הבאים: הצלחה: כל המסננים הופעלו בהצלחה. חלקי: חלק מהמסננים דולגו או שההרצה שלהם נכשלה. כשל: כל המסננים דולגו או שהביצוע שלהם נכשל.
SanitizeModelResponse.POLICY_NAME.raiFilterResult.executionState	תוצאת ההרצה של מסנן ה-Rai. הערכים התקפים כוללים את EXECUTION_SUCCESS ואת EXECUTION_SKIPPED.
SanitizeModelResponse.POLICY_NAME.raiFilterResult.matchState	מצב ההתאמה של מסנן ה-Rai. הערכים התקפים כוללים את MATCH_FOUND ואת NO_MATCH_FOUND.
SanitizeModelResponse.POLICY_NAME.sdpFilterResult.inspectResult.executionState	מצב ההפעלה של תוצאת הבדיקה של מסנן ה-SDP. הערכים התקפים כוללים את EXECUTION_SUCCESS ואת EXECUTION_SKIPPED.
SanitizeModelResponse.POLICY_NAME.sdpFilterResult.inspectResult.matchState	מצב ההתאמה של תוצאת הבדיקה של מסנן ה-SDP. הערכים התקפים כוללים את MATCH_FOUND ואת NO_MATCH_FOUND.
SanitizeModelResponse.POLICY_NAME.sdpFilterResult.deidentifyResult.executionState	מצב הביצוע של תוצאת ביטול הזיהוי של מסנן ה-SDP. הערכים התקפים כוללים את EXECUTION_SUCCESS ואת EXECUTION_SKIPPED.
SanitizeModelResponse.POLICY_NAME.sdpFilterResult.deidentifyResult.matchState	מצב ההתאמה של תוצאת ביטול הזיהוי של מסנן ה-SDP. הערכים התקפים כוללים את MATCH_FOUND ואת NO_MATCH_FOUND.
SanitizeModelResponse.POLICY_NAME.piAndJailbreakFilterResult.executionState	מצב ההפעלה של תוצאות הסינון של החדרה פרומפטים ופריצת הגבלות. הערכים התקפים כוללים את EXECUTION_SUCCESS ואת EXECUTION_SKIPPED.
SanitizeModelResponse.POLICY_NAME.piAndJailbreakFilterResult.matchState	התוצאות של סינון ה-Jailbreak והחדרת פרומפטים תואמות למצב. הערכים התקפים כוללים את MATCH_FOUND ואת NO_MATCH_FOUND.
SanitizeModelResponse.POLICY_NAME.csamFilterFilterResult.executionState	מצב הביצוע של מסנן CSAM. הערכים התקפים כוללים את EXECUTION_SUCCESS ואת EXECUTION_SKIPPED.
SanitizeModelResponse.POLICY_NAME.csamFilterFilterResult.matchState	מצב ההתאמה של המסנן CSAM. הערכים התקפים כוללים את MATCH_FOUND ואת NO_MATCH_FOUND.
SanitizeModelResponse.POLICY_NAME.maliciousUriFilterResult.executionState	מצב הביצוע של מסנן URI זדוני. הערכים התקפים כוללים את EXECUTION_SUCCESS ואת EXECUTION_SKIPPED.
SanitizeModelResponse.POLICY_NAME.maliciousUriFilterResult.matchState	מצב ההתאמה של מסנן URI זדוני. הערכים התקפים כוללים את MATCH_FOUND ואת NO_MATCH_FOUND.
SanitizeModelResponse.POLICY_NAME.sanitizationMetadata.errorCode	קוד שגיאה מותאם אישית שמוחלף אם הוא מופיע בתגובה של הגנה מוגברת על המודל.
SanitizeModelResponse.POLICY_NAME.sanitizationMetadata.errorMessage	קוד שגיאה מותאם אישית שמוחלף אם הוא מופיע בתגובה של הגנה מוגברת על המודל.
SanitizeModelResponse.POLICY_NAME.csamFilterMatched	ערך בוליאני שמציין אם המסנן של CSAM התאים.
SanitizeModelResponse.POLICY_NAME.maliciousURIs	רשימה מצורפת של כתובות URI זדוניות שזוהו על ידי המסנן של כתובות URI זדוניות.
SanitizeModelResponse.POLICY_NAME.maliciousURIsDetected	ערך בוליאני שמציין אם מסנן ה-URI הזדוני תאם.
SanitizeModelResponse.POLICY_NAME.matchesFound	ערך בוליאני שמציין אם יש התאמה לאחד מהמסננים.
SanitizeModelResponse.POLICY_NAME.promptInjectionDetected	ערך בוליאני שמציין אם המסנן של החדרה פרומפטים מצא התאמה.
SanitizeModelResponse.POLICY_NAME.promptInjectionConfidence	רמת הסמך של זיהוי החדרת פרומפטים.
SanitizeModelResponse.POLICY_NAME.raiMatchesFound	ערך בוליאני שמציין אם המסנן של RAI התאים.
SanitizeModelResponse.POLICY_NAME.requestSentToModelArmor	ערך בוליאני שמציין אם בקשה נשלחה להגנה מוגברת על המודל.
SanitizeModelResponse.POLICY_NAME.sanitizeOperation	מציין את הפעולה שמבוצעת על ידי המדיניות. הערכים התקפים כוללים SANITIZE_USER_PROMPT ו-SANITIZE_MODEL_RESPONSE.

הפניה לשגיאה

בקטע הזה מפורטים קודי השגיאות והודעות השגיאה שמוחזרים, ומשתני השגיאה שמוגדרים על ידי Apigee באופן ספציפי למדיניות <SanitizeModelResponse>. חשוב לדעת את המידע הזה אם אתם מפתחים כללי תקלות לטיפול בתקלות. מידע נוסף על שגיאות שקשורות למדיניות ועל טיפול בשגיאות

שגיאות זמן ריצה

קוד תקלה	סטטוס HTTP	מטרה
steps.sanitize.model.response.FilterMatched	400	השגיאה הזו מתרחשת אם ההנחיה למשתמש לא עוברת את הבדיקה של תבנית הגנה מוגברת על המודל.
steps.sanitize.model.response.SanitizationResponseParsingFailed	500	השגיאה הזו מתרחשת אם אי אפשר לנתח את התשובה של Model Armor.
steps.sanitize.model.response.FailedToExtractUserPrompt	500	השגיאה הזו מתרחשת אם חילוץ ההנחיה האוטומטית למשתמש עבור ערך ברירת המחדל נכשל.
steps.sanitize.model.response.FailedToExtractLLMResponse	500	השגיאה הזו מתרחשת אם חילוץ התשובה האוטומטית של המודל לערך ברירת המחדל נכשל.
steps.sanitize.model.response.InternalError	500	השגיאה הזו מתרחשת אם יש שגיאת שרת פנימית.
steps.sanitize.model.response.ModelArmorTemplateNameExtractionFailed	500	השגיאה הזו מתרחשת אם אי אפשר לפענח את שם התבנית.
steps.sanitize.model.response.AuthenticationFailure	500	השגיאה הזו מתרחשת אם לחשבון השירות אין הרשאה לקרוא ל-API של הגנה מוגברת על המודל.
steps.sanitize.model.response.ModelArmorAPIFailed	500	השגיאה הזו מתרחשת אם Model Armor API מחזיר שגיאה.
steps.sanitize.model.response.ModelArmorCalloutError	500	השגיאה הזו מתרחשת אם קריאה ל-API של הגנה מוגברת על המודל נכשלת.
steps.sanitize.modelarmor.ServiceUnavailable	500	השגיאה הזו מתרחשת אם שירות הגנה מוגברת על המודל לא זמין.

שגיאות בהטמעה

השגיאות האלה יכולות להתרחש כשפורסים שרת proxy שמכיל את המדיניות הזו.

שם השגיאה	מטרה
The ModelArmor/TemplateName element is required.	השגיאה הזו מתרחשת אם הרכיב <TemplateName> ב-<ModelArmor> לא קיים.
The TemplateName element value is required.	השגיאה הזו מתרחשת אם הערך של <TemplateName> ריק.

משתני תקלות

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

משתנים	כאשר:	דוגמה
fault.name="FAULT_NAME"	‫FAULT_NAME הוא שם התקלה, כפי שמופיע בטבלה Runtime errors שלמעלה. שם התקלה הוא החלק האחרון של קוד התקלה.	fault.name Matches "UnresolvedVariable"
SanitizeModelResponse.POLICY_NAME.failed	‫POLICY_NAME הוא השם שהמשתמש הגדיר למדיניות שגרמה לשגיאה.	SanitizeModelResponse.sanitize-response.failed = true

דוגמה לתגובת שגיאה

הערה: כדי לטפל בשגיאות, מומלץ ללכוד את החלק errorcode של תגובת השגיאה. אל תסתמכו על הטקסט ב-faultstring, כי הוא עשוי להשתנות.

{
  "fault": {
    "faultstring": "SanitizeModelResponse[sanitize-response]: unable to resolve variable [variable_name]",
    "detail": {
      "errorcode": "steps.sanitizemodelresponse.UnresolvedVariable"
    }
  }
}

דוגמה לכלל שגיאה

<FaultRule name="SanitizeModelResponse Faults">
    <Step>
        <Name>SMR-CustomSetVariableErrorResponse</Name>
        <Condition>(fault.name = "SetVariableFailed")</Condition>
    </Step>
    <Condition>(sanitizemodelresponse.failed = true)</Condition>
</FaultRule>

קוד שגיאה והודעות שגיאה של תבנית הגנה מוגברת על המודל

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

לדוגמה, תגובה עם קודי שגיאה והודעות של הגנה מוגברת על המודל יכולה להיראות כך:

{
"sanitizationResult": {
  "filterMatchState": "MATCH_FOUND",
  "filterResults": {...},
  "sanitizationMetadata": {
    "errorCode": "890",
    "errorMessage": "get out"
  },
  "invocationResult": "SUCCESS"
  }
}

סכימות

כל סוג מדיניות מוגדר על ידי סכימת XML ‏ (.xsd). סכימות מדיניות זמינות ב-GitHub.