‫SemanticCacheLookup policy

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

הפעלת ממשקי ה-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>
      <DistanceMeasureType>DOT_PRODUCT_DISTANCE</DistanceMeasureType>
    </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>
      <DistanceMeasureType>DOT_PRODUCT_DISTANCE</DistanceMeasureType>
    </VertexAI>
  </SimilaritySearch>
</SemanticCacheLookup>

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

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

מאפיין ברירת מחדל חובה? תיאור
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>

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

אפשר להריץ את החיפוש לפי דמיון באינדקס החיפוש של חיפוש וקטורי שנפרס בנקודת קצה ציבורית או בנקודת קצה פרטית (Private Service Connect). צריך לציין אמצעי תחבורה אחד בלבד מבין האפשרויות הבאות ברכיב <VertexAI>:

  • ‫<URL> – לנקודת קצה ציבורית, באמצעות REST (:findNeighbors).
  • ‫<PrivateServiceConnect> – לנקודת קצה פרטית, דרך gRPC. נקודת קצה פרטית (Private Service Connect) של אינדקס פרוס מקבלת רק gRPC.

מידע נוסף זמין במאמרים שליחת שאילתה לאינדקס ציבורי כדי לקבל את השכנים הקרובים ביותר ושמירה במטמון סמנטי עם נקודת קצה פרטית (Private Service Connect).

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

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

נקודת קצה ציבורית (REST):

<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>
    <DistanceMeasureType>DOT_PRODUCT_DISTANCE</DistanceMeasureType>
  </VertexAI>
</SimilaritySearch>

נקודת קצה פרטית (Private Service Connect, ‏ gRPC):

<SimilaritySearch>
  <VertexAI>
    <PrivateServiceConnect>
      <GrpcEndpoint>grpc://{TARGET_HOST}:10000</GrpcEndpoint>
    </PrivateServiceConnect>
    <Threshold>0.9</Threshold>
    <DeployedIndexID>{DEPLOYED_INDEX_ID}</DeployedIndexID>
  </VertexAI>
</SimilaritySearch>

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

מכיל את המאפיינים הספציפיים ל-Vertex AI שמשמשים לביצוע החיפוש לפי דמיון. צריך לציין בדיוק אחד מהטרנספורטים הבאים: רכיב <URL> (לנקודת קצה ציבורית, דרך REST) או רכיב <PrivateServiceConnect> (לנקודת קצה פרטית, דרך gRPC).

ערך ברירת המחדל לא רלוונטי
חובה? חובה
סוג 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>
  <DistanceMeasureType>DOT_PRODUCT_DISTANCE</DistanceMeasureType>
</VertexAI>

עבור נקודת קצה פרטית (Private Service Connect), התחביר של רכיב VertexAI הוא:

<VertexAI>
  <PrivateServiceConnect>
    <GrpcEndpoint>grpc://{TARGET_HOST}:10000</GrpcEndpoint>
  </PrivateServiceConnect>
  <Threshold>0.9</Threshold>
  <DeployedIndexID>{DEPLOYED_INDEX_ID}</DeployedIndexID>
</VertexAI>

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

רכיב צאצא חובה? תיאור
<URL> חובה (צריך לציין <URL> או <PrivateServiceConnect>) String

כתובת ה-URL שמשמשת לביצוע חיפושי דמיון בנקודת קצה (endpoint) ציבורית של אינדקס חיפוש וקטורי, באמצעות REST‏ (:findNeighbors). המערכת משתמשת רק בנקודה על הגרף עם ההתאמה הכי גבוהה, על סמך מידת דמיון מינימלית בין המשתמשים.

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

<URL>https://{URL_VARIABLE}</URL>
<PrivateServiceConnect> חובה (צריך לציין <URL> או <PrivateServiceConnect>) אובייקט מורכב

מכיל את פרטי החיבור שמשמשים לביצוע חיפושי דמיון באינדקס החיפוש פרטי של חיפוש וקטורי שנפרס בנקודת קצה (endpoint) של Private Service Connect. נקודת קצה פרטית של deployed-index מקבלת רק gRPC.

הרכיב הזה מכיל רכיב צאצא יחיד, <GrpcEndpoint>:

<PrivateServiceConnect>
  <GrpcEndpoint>grpc://{TARGET_HOST}:10000</GrpcEndpoint>
</PrivateServiceConnect>

רכיב <GrpcEndpoint> מציין את כתובת ה-gRPC של נקודת הקצה הפרטית. הכללים הבאים חלים:

  • הפורמט הוא grpc://TARGET_HOST:PORT. הסכימה חייבת להיות grpc://; grpcs:// (TLS) לא נתמכת בגרסה הזו. ‫TARGET_HOST היא כתובת ה-IP של נקודת הקצה של הקישור או רשומת DNS פרטית בתחום Cloud DNS מקושר.
  • היציאה היא 10000 עבור נקודות קצה של מישור הנתונים של Vector Search Private Service Connect.
  • הדילוג של gRPC הוא טקסט פשוט ולא מאומת, והוא מאובטח באמצעות בידוד הרשת.

מידע נוסף זמין במאמר שמירה סמנטית במטמון עם נקודת קצה פרטית (Private Service Connect).
<Threshold> אופציונלי String

הערך שהשכן הקרוב ביותר צריך להגיע אליו כדי להיחשב כהתאמה. ‫<DistanceMeasureType> מגדיר את כיוון ההשוואה.

ערך ברירת המחדל הוא 0.9, שמתאים ל-DOT_PRODUCT_DISTANCE.

בחירת ערך סף למדד המרחק
<DeployedIndexID> חובה String

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

מדד המרחק שבאמצעותו נוצר האינדקס ב-Vertex AI Vector Search. הוא מגדיר את הכיוון של ההשוואה ב-<Threshold>.

הערכים התקפים הם DOT_PRODUCT_DISTANCE, ‏ COSINE_DISTANCE,‏ SQUARED_L2_DISTANCE ו-L1_DISTANCE, בהתאמה מדויקת. כל ערך אחר יגרום לפריסה להיכשל. מידע על מה כל מדד מחשב זמין במאמר בנושא פרמטרים של הגדרת אינדקס.

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

בחירת ערך סף למדד המרחק

בחירת סף למדד המרחק

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

מדידת מרחק סף המטמון
DOT_PRODUCT_DISTANCE (ברירת מחדל) value >= threshold
COSINE_DISTANCE value <= threshold
SQUARED_L2_DISTANCE value <= threshold
L1_DISTANCE value <= threshold

כדי למצוא את המדד שבאמצעותו נבנה האינדקס, מריצים את הפקודה gcloud ai indexes describe INDEX_ID --region=REGION וקוראים את השדה distanceMeasureType. כדי לוודא שהמדיניות הוחלה, שולחים את אותה בקשה פעמיים ובודקים את semanticcache.lookup.policy_name.measure_type ואת semanticcache.lookup.policy_name.nearest_neighbor_measure בסשן ניפוי באגים.

משתני זרימה

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

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

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

הפניה לשגיאה

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

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

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

קוד תקלה סטטוס HTTP מטרה
steps.semanticcache.lookup.MessageTemplateExtractionFailed 400 לא הצלחנו לחלץ נתונים מהבקשה באמצעות הביטוי של נתיב ה-JSON.
steps.semanticcache.lookup.FailedToExtractUserPrompt 500 לא ניתן לחלץ את ההנחיה למשתמש מבקשת ה-API.
steps.semanticcache.lookup.EmbeddingsServiceUnavailable 400 שירות ההטמעות של Vertex AI לא זמין כרגע.
steps.semanticcache.lookup.EmbeddingsAPIFailed 400 שירות ההטמעות של Vertex AI נכשל.
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> ריק.
Embeddings/VertexAI cannot have both URL and PrivateServiceConnect elements. השגיאה הזו מתרחשת אם ציינתם גם את הרכיב <URL> וגם את הרכיב <PrivateServiceConnect> ב-<Embeddings>.
SimilaritySearch/VertexAI cannot have both URL and PrivateServiceConnect elements. השגיאה הזו מתרחשת אם הרכיבים <URL> ו-<PrivateServiceConnect> מצוינים ב-<SimilaritySearch>.
Embeddings/VertexAI/URL or Embeddings/PrivateServiceConnect/GrpcEndpoint element is required. השגיאה הזו מתרחשת אם לא מציינים את הרכיב <URL> או את הרכיב <GrpcEndpoint> ב-<Embeddings>.
SimilaritySearch/VertexAI/URL or SimilaritySearch/PrivateServiceConnect/GrpcEndpoint element is required. השגיאה הזו מתרחשת אם לא צוין הרכיב <URL> או הרכיב <GrpcEndpoint> ב-<SimilaritySearch>.
The Embeddings/VertexAI/PrivateServiceConnect element is not supported. Use URL instead. האירוע מתרחש אם נעשה שימוש ברכיב <PrivateServiceConnect> ב-<Embeddings>.
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 של הרכיב SimilaritySearch <URL> לא תקינה.
The SimilaritySearch /VertexAI/PrivateServiceConnect/GrpcEndpoint {grpc-endpoint} must be in the format "grpc://TARGET_HOST:PORT". השגיאה הזו מתרחשת אם הרכיב <GrpcEndpoint> ב-<SimilaritySearch> לא בפורמט grpc://TARGET_HOST:PORT.
The scheme {grpc-scheme} of SimilaritySearch /VertexAI/PrivateServiceConnect/GrpcEndpoint {grpc-endpoint} must be "grpc". השגיאה מתרחשת אם הסכימה grpc של רכיב ה-SimilaritySearch‏ <GrpcEndpoint> לא תקינה.
SimilaritySearch/Threshold element must not be NaN. השגיאה הזו מתרחשת אם הרכיב <Threshold> ב-<SimilaritySearch> הוא NaN. מותר להעלות Infinity וגם -Infinity.
Invalid DistanceMeasureType {value}. Supported values are DOT_PRODUCT_DISTANCE, COSINE_DISTANCE, SQUARED_L2_DISTANCE and L1_DISTANCE השגיאה הזו מתרחשת אם הרכיב <DistanceMeasureType> ב-<SimilaritySearch> הוא לא אחד מארבעת הערכים הנתמכים. ההתאמה מדויקת. מידע נוסף זמין במאמר בנושא פרמטרים של הגדרת אינדקס.
SimilaritySearch/DeployedIndexID element is required. השגיאה הזו מתרחשת אם הרכיב <DeployedIndexID> ב-<SimilaritySearch> ריק.
SimilaritySearch/DeployedIndexID element must not contain spaces. השגיאה הזו מתרחשת אם הרכיב <DeployedIndexID> ב-<SimilaritySearch> מכיל רווחים.

משתני תקלות

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

משתנים כאשר: דוגמה
fault.name="FAULT_NAME" ‫FAULT_NAME הוא שם התקלה, כמו שמופיע בטבלה שגיאות זמן ריצה שלמעלה. שם התקלה הוא החלק האחרון של קוד התקלה. 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.