המדיניות SemanticCachePopulate

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

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

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

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

המדיניות משתמשת ב-Text embeddings API של Vertex AI כדי ליצור הטמעות לטקסט, וב-חיפוש וקטורי כדי לשמור במטמון תגובות מה-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, צריך את ההרשאה serviceusage.services.enable. אם יצרתם את הפרויקט, סביר להניח שכבר יש לכם את ההרשאה הזו דרך התפקיד 'בעלים' (roles/owner). אחרת, תוכלו לקבל את ההרשאה הזו דרך התפקיד 'אדמין בממשק 'שימוש בשירות'' (roles/serviceusage.serviceUsageAdmin). איך מקצים תפקידים

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

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

מאפיין ברירת מחדל חובה? תיאור
name לא רלוונטי חובה

השם הפנימי של המדיניות. הערך של מאפיין name יכול להכיל אותיות, מספרים, רווחים, מקפים, קווים תחתונים ונקודות. הערך הזה לא יכול להיות ארוך מ-255 תווים.

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

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

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

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

תאריך התפוגה של נקודות על הגרף הוא <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>

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

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

תאריך התפוגה של נקודות על הגרף הוא <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>
רכיבי צאצא אין

משתני זרימה

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

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

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

הפניה לשגיאה

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

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

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

קוד השגיאה סטטוס HTTP מטרה
steps.semanticcachepopulate.VectorSearchUpsertServiceUnavailable 400

השגיאה הזו מתרחשת אם ה-API של חיפוש וקטורי Upsert Datapoints לא זמין.
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/VertexAI/PrivateServiceConnect element is not supported in SemanticCachePopulate. השגיאה מתרחשת אם נעשה שימוש ברכיב <PrivateServiceConnect> ב-<SemanticCachePopulate>.
The SimilaritySearch/VertexAI/URL element is required. השגיאה הזו מתרחשת אם הרכיב <URL> ברכיב <SimilaritySearch> ריק.
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. אם הערך מוגדר כאפס או כמספר שלילי, פריסת ה-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.