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

לדוגמה: 

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

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

אפשר להריץ את החיפוש לפי דמיון באינדקס של Vector Search שנפרס בנקודת קצה (endpoint) ציבורית או פרטית (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 לנקודות קצה של מישור הנתונים של Private Service Connect ב-חיפוש וקטורי.
  • הדילוג של gRPC הוא טקסט פשוט ולא מאומת, והוא מאובטח באמצעות בידוד הרשת.

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

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

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

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

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

מדד המרחק ששימש ליצירת אינדקס החיפוש הווקטורי ב-Vertex AI. הוא מגדיר את הכיוון של ההשוואה ב-<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.