המדיניות SemanticCachePopulate

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

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

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

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

המדיניות משתמשת ב-Text embeddings API של Vertex AI כדי ליצור הטמעות של טקסט וב-Vector Search כדי לשמור במטמון תשובות של API על סמך דמיון סמנטי, ולא על סמך התאמות מדויקות.

המדיניות SemanticCachePopulate יכולה לקצר את זמני התגובה לשאילתות חוזרות ולבצע אופטימיזציה של העלויות על ידי צמצום נפח השיחות עם מודלים גדולים של שפה (LLM).

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

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

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

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

• יוצרים פרויקט Vertex AI.
• יוצרים אינדקס של Vector Search.
• יוצרים נקודת קצה של Vertex AI לאינדקס.
• יוצרים מדיניות SemanticCachePopulate.

מידע נוסף על השלמת המשימות האלה זמין במאמר תחילת העבודה עם מדיניות שמירה במטמון סמנטי.

תפקידים והרשאות

כדי לקבל את ההרשאות שנדרשות להחלה ולשימוש במדיניות SemanticCachePopulate, צריך לבקש מהאדמין להקצות לכם ב-IAM את התפקיד AI Platform User (roles/aiplatform.user) בחשבון השירות שבו אתם משתמשים כדי לפרוס פרוקסי של Apigee. כדי לקרוא הסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.

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

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

מפעילים את ממשקי ה-API של Compute Engine,‏ Vertex AI ו-Cloud Storage.

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

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

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

רכיב <SemanticCachePopulate>

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

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

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

תחביר

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

<SemanticCachePopulate async="false" continueOnError="false"enabled="true" name="SCP-populate">
  <DisplayName>SCP-populate</DisplayName>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <SimilaritySearch>
    <VertexAI>
      <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexes/{INDEX_ID}:upsertDatapoints</URL>
    </VertexAI>
  </SimilaritySearch>
  <TTLInSeconds>{EXPIRATION_TIME_IN_SECONDS}</TTLInSeconds>
</SemanticCachePopulate>

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

בדוגמה הבאה מוצגות הגדרות ברירת המחדל כשמוסיפים מדיניות SemanticCachePopulate ל-proxy ל-API בממשק המשתמש של Apigee:

<SemanticCachePopulate async="false" continueOnError="false"enabled="true" name="SCP-populate">
  <DisplayName>SCP-populate</DisplayName>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <SimilaritySearch>
    <VertexAI>
      <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexes/{INDEX_ID}:upsertDatapoints</URL>
    </VertexAI>
  </SimilaritySearch>
  <TTLInSeconds>60</TTLInSeconds>
</SemanticCachePopulate>

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

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

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

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

רכיב צאצא	חובה?	תיאור
<DisplayName>	אופציונלי	שם המדיניות.
<IgnoreUnresolvedVariables>	אופציונלי	ההגדרה הזו קובעת אם העיבוד ייפסק כשקבוצת מאפיינים לא נפתרת.
<SimilaritySearch>	חובה	רכיב שמכיל את המידע שנדרש לעדכון אינדקס הווקטורים. מידע נוסף זמין במאמר Upsert datapoints. זמן התפוגה של נקודות הנתונים הוא <TTLInSeconds> מרגע ההזנה.
<TTLInSeconds>	אופציונלי	אורך החיים (TTL) של התשובות שנשמרו במטמון, בשניות. ערך ברירת המחדל הוא 60.

דוגמה

בקטע הזה מופיעה דוגמה לשימוש ב-<SemanticCachePopulate>.

<SemanticCachePopulate async="false" continueOnError="false"enabled="true" name="SCP-populate">
  <DisplayName>SCP-populate</DisplayName>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <SimilaritySearch>
    <VertexAI>
      <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexes/{INDEX_ID}:upsertDatapoints</URL>
    </VertexAI>
  </SimilaritySearch>
  <TTLInSeconds>60</TTLInSeconds>
</SemanticCachePopulate>

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

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

<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 כדי להתעלם ממשתנים שלא נפתרו ולהמשיך בעיבוד.

המאפיין IgnoreUnresolvedVariables לא רלוונטי כשמציינים את <DefaultValue>.

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

<SimilaritySearch>

רכיב שמכיל את המידע שנדרש לעדכון אינדקס הווקטורים.

מידע נוסף זמין במאמר Upsert datapoints.

תאריך התפוגה של נקודות הנתונים הוא <TTLInSeconds> מרגע ההזנה.

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

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

<SimilaritySearch>
  <VertexAI>
    <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexes/{INDEX_ID}:upsertDatapoints</URL>
  </VertexAI>
</SimilaritySearch>

‫<VertexAI> (צאצא של <SimilaritySearch>)

מכיל את האלמנט <URL> למאפיינים ספציפיים ל-Vertex AI.

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

רכיב VertexAI משתמש בתחביר הבא:

<VertexAI>
  <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexes/{INDEX_ID}:upsertDatapoints</URL>
</VertexAI>

‫<URL> (צאצא של <VertexAI>)

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

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

רכיב URL משתמש בתחביר הבא:

<URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexes/{INDEX_ID}:upsertDatapoints</URL>

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

<URL>https://{URL_VARIABLE}</URL>

<TTLInSeconds>

רכיב שמציין את הזמן לחיים (TTL) של התשובות שנשמרו במטמון, בשניות. ערך ברירת המחדל הוא 60.

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

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

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

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

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

שם המשתנה	תיאור
response.content	כולל את כל התוכן של תגובת ה-API.
semanticcache.populate.policy_name.upsert_index_request	מכיל את מטען הייעודי (payload) של הבקשה שנשלחה אל Vertex AI Vector Search API כדי לעדכן את אינדקס הווקטורים עם הטמעות ומטא-נתונים חדשים.
semanticcache.populate.policy_name.upsert_index_response	מכיל את התשובה מ-Vertex AI Vector Search API, שמציינת אם פעולת עדכון האינדקס הצליחה או נכשלה.

הפניה לשגיאה

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

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

השגיאות האלה יכולות להתרחש כשהמדיניות מופעלת.

קוד תקלה	סטטוס HTTP	מטרה
steps.semanticcachepopulate.VectorSearchUpsertServiceUnavailable	400	השגיאה הזו מתרחשת אם Vector Search Upsert Datapoints API לא זמין.
steps.semanticcache.populate.VectorSearchUpsertAPIFailed	500	השגיאה הזו מתרחשת אם שירות ה-API של Vector Search Upsert Datapoints נכשל.
steps.semanticcache.populate.AuthenticationFailure	500	השגיאה הזו מתרחשת אם לחשבון השירות אין את ההרשאות הנדרשות.
steps.semanticcache.populate.CalloutError	500	הקריאה לשירות Vertex AI נכשלה.
steps.semanticcache.populate.InternalError	500	השגיאה הזו מתרחשת במקרה של שגיאה לא צפויה במדיניות <SemanticCachePopulate>.

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

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

שם השגיאה	מטרה
The SimilaritySearch URL {url} is invalid.	השגיאה הזו מתרחשת אם האלמנט <URL> ב-<SimilaritySearch> ריק או לא תקין.
The scheme {http-scheme} of SimilaritySearch URL {url} must be one of http, https.	השגיאה מתרחשת אם הסכימה http של רכיב ה-<URL> של SimilaritySearch לא תקינה.
The TTLInSeconds element must be >= 0.	אם הערך מוגדר כ-0 או כמספר שלילי, פריסת ה-proxy ל-API נכשלת.

משתני תקלות

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

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

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

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

{
"fault": {
  "faultstring": "SemanticCacheLookup[SC-populate]: unable to resolve variable [variable_name]",
  "detail": {
    "errorcode": "steps.semanticcachepopulate.UnresolvedVariable"
  }
}
}

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

<FaultRule name="SemanticCacheLookup Faults">
  <Step>
      <Name>SCL-CustomSetVariableErrorResponse</Name>
      <Condition>(fault.name = "SetVariableFailed")</Condition>
  </Step>
  <Condition>(semanticcachelookup.failed = true)</Condition>
</FaultRule>

סכימות

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