‫SemanticCacheLookup policy

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

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

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

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

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

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

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

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

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

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

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

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

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

כדי לקבל את ההרשאות שנדרשות להחלה של המדיניות SemanticCacheLookup ולשימוש בה, צריך לבקש מהאדמין להקצות לכם ב-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

רכיב <SemanticCacheLookup>

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

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

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

תחביר

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

<SemanticCacheLookup async="false" continueOnError="false" enabled="true" name="SCL-lookup">
  <DisplayName>SCL-lookup</DisplayName>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <UserPromptSource>{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}</UserPromptSource>
  <Embeddings>
    <VertexAI>
      <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/{MODEL_ID}:predict</URL>
    </VertexAI>
  </Embeddings>
  <SimilaritySearch>
    <VertexAI>
      <URL>https://{PUBLIC_DOMAIN_NAME}/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexEndpoints/{INDEX_ENDPOINT_ID}:findNeighbors</URL>
      <DeployedIndexID>{DEPLOYED_INDEX_ID}</DeployedIndexID>
      <Threshold>0.95</Threshold>
    </VertexAI>
  </SimilaritySearch>
</SemanticCacheLookup>

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

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

<SemanticCacheLookup async="false" continueOnError="false"enabled="true" name="SCL-lookup">
  <DisplayName>SCL-lookup</DisplayName>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <UserPromptSource>{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}</UserPromptSource>
  <Embeddings>
    <VertexAI>
      <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/{MODEL_ID}:predict
      </URL>
    </VertexAI>
  </Embeddings>
  <SimilaritySearch>
    <VertexAI>
      <URL>https://{PUBLIC_DOMAIN_NAME}/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexEndpoints/{INDEX_ENDPOINT_ID}:findNeighbors</URL>
      <Threshold>0.9</Threshold>
      <DeployedIndexID>{DEPLOYED_INDEX_ID}</DeployedIndexID>
    </VertexAI>
  </SimilaritySearch>
</SemanticCacheLookup>

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

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

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

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

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

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

רכיב צאצא חובה? תיאור
<DisplayName> אופציונלי שם המדיניות.
<IgnoreUnresolvedVariables> אופציונלי קובעת אם העיבוד ייפסק כשמשתנה לא נפתר. הגדרה ל-true גורמת להתעלמות ממשתנים שלא נפתרו ולהמשך העיבוד.
<UserPromptSource> אופציונלי המיקום של מטען הייעודי (payload) של טקסט הנחיית המשתמש לחילוץ. המערכת תומכת רק בערכי טקסט של מחרוזת.

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

לדוגמה: 

{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}

<Embeddings> חובה רכיב שמכיל את המידע שנדרש ליצירת הטמעה.
<SimilaritySearch> חובה רכיב שמכיל את המידע שנדרש לביצוע חיפושים של דמיון.

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

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

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

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

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

<UserPromptSource>

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

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

לדוגמה: 

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

<Embeddings>

הרכיב הזה מכיל את המידע שנדרש ליצירת הטמעה של טקסט.

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

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

<Embeddings>
  <VertexAI>
    <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/{MODEL_ID}:predict</URL>
  </VertexAI>
</Embeddings>

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

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

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

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

<VertexAI>
  <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/{MODEL_ID}:predict</URL>
</VertexAI>

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

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

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

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

<URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/{MODEL_ID}:predict</URL>

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

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

<SimilaritySearch>

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

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

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

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

<SimilaritySearch>
  <VertexAI>
    <URL>https://{PUBLIC_DOMAIN_NAME}/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexEndpoints/{INDEX_ENDPOINT_ID}:findNeighbors
    </URL>
    <Threshold>0.9</Threshold>
    <DeployedIndexID>{DEPLOYED_INDEX_ID}</DeployedIndexID>
  </VertexAI>
</SimilaritySearch>

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

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

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

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

<VertexAI>
  <URL>https://{PUBLIC_DOMAIN_NAME}/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexEndpoints/{INDEX_ENDPOINT_ID}:findNeighbors</URL>
  <Threshold>0.9</Threshold>
  <DeployedIndexID>{DEPLOYED_INDEX_ID}</DeployedIndexID>
</VertexAI>

בטבלה הבאה מופיע תיאור כללי של רכיבי המשנה של <VertexAI>.

רכיב צאצא חובה? תיאור
<URL> חובה String

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

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

<URL>https://{URL_VARIABLE}</URL>
<Threshold> אופציונלי String

ציון הדמיון שמשמש לקביעה אם שתי הנחיות נחשבות זהות. ערך בין 0 ל-1.

ערך ברירת המחדל הוא 0.9.

לראות

<DeployedIndexID> חובה String

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

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

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

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

שם המשתנה תיאור
request.content מכיל את התוכן המלא של בקשת ה-API הנכנסת.
request.url המשתנה מכיל את כתובת ה-URL של בקשת ה-API הנכנסת.
semanticcache.lookup.policy_name.user_prompt המאפיין מכיל רכיבים ספציפיים שחולצו מההנחיה לבקשה, שמשמשת ליצירת הטמעות או לביצוע חיפושים של דמיון.
semanticcache.lookup.policy_name.embeddings_request מכיל את מטען הייעודי (payload) של הבקשה שנשלחה אל Vertex AI Embeddings API כדי ליצור הטמעות טקסט לטקסט הקלט.
semanticcache.lookup.policy_name.embeddings_response מכיל את התשובה מ-Vertex AI Embeddings API, שכוללת את הטמעות הטקסט שנוצרו.
semanticcache.lookup.policy_name.dense_embeddings מכיל את ערכי ההטמעה המספריים בפועל שנוצרו על ידי Vertex AI Embeddings API.
semanticcache.lookup.policy_name.is_nearest_neighbor_hit מציין אם נמצא שכן קרוב במסד הנתונים של הווקטורים עבור הבקשה ונקודת הנתונים הנתונות, ועומד בסף הדמיון.
semanticcache.lookup.policy_name.cache_hit מציין אם התשובה נמצאה במטמון הסמנטי.
semanticcache.lookup.policy_name.cached_llm_response מכיל את התשובה שאוחזרה מהמטמון הסמנטי (אם התרחש פגיעה במטמון).

הפניה לשגיאה

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

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

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

קוד תקלה סטטוס HTTP מטרה
steps.semanticcache.lookup.MessageTemplateExtractionFailed 400 החילוץ של הנתונים מהבקשה באמצעות הביטוי JSON Path נכשל.
steps.semanticcache.lookup.FailedToExtractUserPrompt 500 לא ניתן לחלץ את ההנחיה למשתמש מבקשת ה-API.
steps.semanticcache.lookup.EmbeddingsServiceUnavailable 400 השירות Vertex AI Embeddings לא זמין כרגע.
steps.semanticcache.lookup.EmbeddingsAPIFailed 400 השירות Vertex AI Embeddings נכשל.
steps.semanticcache.lookup.VectorSearchServiceUnavailable 400 השירות Vertex AI Vector Search לא זמין כרגע.
steps.semanticcache.lookup.VectorSearchAPIFailed 400 השירות Vertex AI Vector Search נכשל.
steps.semanticcache.lookup.AuthenticationFailure 500 לחשבון השירות אין את ההרשאות הנדרשות.
steps.semanticcache.lookup.InternalError 500 אירעה שגיאה לא צפויה במדיניות SemanticCacheLookup.
steps.semanticcache.lookup.CalloutError 500 הקריאה לשירות Vertex AI נכשלה.

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

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

שם השגיאה מטרה
The Embeddings/VertexAI element is required. השגיאה מתרחשת אם הרכיב <VertexAI> ב-<Embeddings> ריק.
The SimilaritySearch/VertexAI element is required. השגיאה מתרחשת אם האלמנט <VertexAI> ב-<SimilaritySearch> ריק.
The Embeddings/URL element is required. השגיאה הזו מתרחשת אם האלמנט <URL> ב-<Embeddings> ריק.
The SimilaritySearch/URL element is required. השגיאה מתרחשת אם האלמנט <URL> ב-<SimilaritySearch> ריק.
Embeddings URL {url} is invalid. השגיאה מתרחשת אם האלמנט <URL> ב-<Embeddings> ריק או לא תקין.
The SimilaritySearch URL {url} is invalid. השגיאה הזו מתרחשת אם האלמנט <URL> ב-<SimilaritySearch> ריק או לא תקין.
The scheme {http-scheme} of Embeddings URL {url} must be one of http, https. השגיאה מתרחשת אם הסכימה http של רכיב ההטמעה [URL] לא תקינה.
The scheme {http-scheme} of SimilaritySearch URL {url} must be one of http, https. השגיאה מתרחשת אם הסכימה http של רכיב ה-<URL> של SimilaritySearch לא תקינה.
SimilaritySearch/Threshold element must be >= 0 and <= 1. אם ערך המאפיין לא בין 0 ל-1, פריסת ה-proxy ל-API נכשלת.
SimilaritySearch/DeployedIndexID element is required. השגיאה הזו מתרחשת אם האלמנט <DeployedIndexID> ב-<SimilaritySearch> ריק.
SimilaritySearch/DeployedIndexID element must not contain spaces. מתרחש אם הרכיב <DeployedIndexID> ב-<SimilaritySearch> מכיל רווחים.

משתני תקלות

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

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

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

{
  "fault": {
    "faultstring": "SemanticCacheLookup[SC-lookup]: unable to resolve variable [variable_name]",
    "detail": {
      "errorcode": "steps.semanticcachelookup.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.