המדיניות 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 (roles/aiplatform.user) בחשבון השירות שבו אתם משתמשים כדי לפרוס פרוקסי של Apigee. להסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.

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

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

Enable the Compute Engine, Vertex AI, and Cloud Storage APIs.

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 APIs

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

משתני 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 הוא שם התקלה, כפי שמופיע בטבלה שגיאות בזמן ריצה שלמעלה. שם התקלה הוא החלק האחרון של קוד התקלה. fault.name Matches "UnresolvedVariable"
semanticcachepopulate.POLICY_NAME.failed ‫POLICY_NAME הוא השם שהמשתמש נתן למדיניות שגרמה לשגיאה. semanticcachepopulate.SC-populate.failed = true

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

{
"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.