שמירת נתונים במטמון סמנטי עם נקודת קצה פרטית (Private Service Connect)

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

לצפייה במאמרי העזרה של Apigee Edge.

בדף הזה מוסבר איך להגדיר את כללי המדיניות של Apigee לשמירה סמנטית במטמון ולהשתמש בהם כדי לאפשר שימוש חוזר חכם בתשובות על סמך דמיון סמנטי. בדוגמה הזו, כללי המדיניות מריצים את החיפוש לפי דמיון באינדקס של Vector Search שנפרס בנקודת קצה פרטית (Private Service Connect). שימוש בכללי המדיניות האלה ב-proxy ל-API של Apigee מצמצם את הקריאות המיותרות ל-API לקצה העורפי, מקצר את זמן האחזור ומפחית את עלויות התפעול.

המדריך הזה רלוונטי גם ל-Apigee וגם ל-Apigee Hybrid. הגדרת המדיניות זהה בשתי הפלטפורמות, ורק הדרך שבה סביבת זמן הריצה מגיעה לנקודת הקצה הפרטית שונה, כפי שמתואר בשלב 2: התחברות לחיבור השירות. ב-Apigee Hybrid, יש תמיכה בשמירה סמנטית במטמון בנקודת קצה פרטית (Private Service Connect) בגרסה 1.16.11 ואילך ובגרסה 1.17.0 ואילך. מידע נוסף זמין במאמר הגדרה ב-Apigee Hybrid.

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

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

  1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  2. Verify that billing is enabled for your Google Cloud project.

  3. Enable the Compute Engine, AI Platform, and Cloud Storage APIs, if any are not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the APIs

  4. מפעילים ומגדירים את API של הטמעת טקסט ב-Vertex AI בפרויקט ב- Google Cloud .
  5. יוצרים אינדקס החיפוש של חיפוש וקטורי (או מקבלים גישה לאינדקס כזה) שנפרס בנקודת קצה פרטית (Private Service Connect). במדריך הזה לא מפורטים שלבי ההגדרה של החיפוש הווקטורי. כדי לראות את הדרישות הספציפיות ל-SemanticCacheLookup וקישורים למסמכי התיעוד של החיפוש הווקטורי, עיינו במאמר דרישות מוקדמות לאינדקס החיפוש הווקטורי.
  6. מוודאים שיש לכם סביבה בינונית או מקיפה במכונה של Apigee. אפשר לפרוס כללי מדיניות של שמירה סמנטית במטמון רק בסביבות בינוניות או מקיפות.
  7. מוודאים שיש לכם קבוצת סביבות עם שם מארח של סביבת זמן ריצה, שבו אתם יכולים להשתמש כדי לשלוח בקשות ל-proxy ל-API.

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

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

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

הגדרה של משתני סביבה

בפרויקט Google Cloud שמכיל את המכונה של Apigee, משתמשים בפקודה הבאה כדי להגדיר משתני סביבה: 

export PROJECT_ID=PROJECT_ID
export REGION=REGION
export RUNTIME_HOSTNAME=RUNTIME_HOSTNAME

כאשר:

  • ‫PROJECT_ID הוא מזהה הפרויקט עם המכונה של Apigee.
  • ‫REGION הוא Google Cloud האזור של המכונה של Apigee.
  • ‫RUNTIME_HOSTNAME הוא שם המארח של סביבת זמן הריצה של Apigee.

כדי לוודא שמשתני הסביבה מוגדרים בצורה נכונה, מריצים את הפקודה הבאה ובודקים את הפלט: 

echo $PROJECT_ID $REGION $RUNTIME_HOSTNAME

הגדרת הפרויקט

מגדירים את הפרויקט ב- Google Cloud בסביבת הפיתוח: 

    gcloud auth login
    gcloud config set project $PROJECT_ID

דרישות מוקדמות לאינדקס ב-Vector Search

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

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

  • האינדקס חייב להשתמש ב-STREAM_UPDATE ("indexUpdateMethod": "STREAM_UPDATE") כדי שניתן יהיה לשלוח שאילתות לקריאות upsertDatapoints של המדיניות SemanticCachePopulate כמעט בזמן אמת.
  • האינדקס dimensions חייב להתאים למאפייני הפלט של מודל ההטמעות שבו משתמשים במדיניות SemanticCacheLookup. במדריך הזה משתמשים במודל gemini-embedding-001, שיוצר כברירת מחדל הטמעות עם 3,072 מאפיינים. אם מקצרים את הפלט למספר קטן יותר של ממדים (לדוגמה, 768 או 1,536), צריך להגדיר את dimensions לאותו ערך.
  • יוצרים את האינדקס עם מדד המרחק (distanceMeasureType) שתואם ל-<DistanceMeasureType> של המדיניות. הרכיב <SimilaritySearch><VertexAI><DistanceMeasureType> במדיניות SemanticCacheLookup הוא אופציונלי, וערך ברירת המחדל שלו הוא DOT_PRODUCT_DISTANCE. גם COSINE_DISTANCE נתמך. מדד המרחק של האינדקס והמדיניות <DistanceMeasureType> חייבים להיות זהים.

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

ACCESS_TOKEN=$(gcloud auth print-access-token) && curl -X POST \
  "https://$REGION-aiplatform.googleapis.com/v1/projects/$PROJECT_ID/locations/$REGION/indexes" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "semantic-cache-index",
    "metadata": {
      "config": {
        "dimensions": 3072,
        "distanceMeasureType": "DOT_PRODUCT_DISTANCE"
      }
    },
    "indexUpdateMethod": "STREAM_UPDATE"
  }'

שימו לב לערך המספרי INDEX_ID שמוחזר בתגובה. אתם משתמשים בו במדיניות SemanticCachePopulate. אחרי שיוצרים את האינדקס, יוצרים נקודת קצה של אינדקס Private Service Connect ופורסים בה את האינדקס.

כשיוצרים את נקודת הקצה של האינדקס ב-Private Service Connect, היא צריכה לעמוד בדרישות הבאות שספציפיות ל-SemanticCacheLookup:

  • הפרויקט ב-Apigee שממנו מתחיל החיבור חייב להיות חלק מprojectAllowlist:
    • ‫Apigee: משתמשים בפרויקט הדייר (tenant) של Apigee. משיגים את מזהה הפרויקט של הדייר מ-Organizations API (השדה apigeeProjectId).
    אי אפשר לשנות את projectAllowlist אחרי שיוצרים את נקודת הקצה של האינדקס. אם הוספתם לרשימת ההיתרים את הפרויקט הלא נכון, תצטרכו למחוק את נקודת הקצה של האינדקס וליצור אותה מחדש.

שימו לב לערך המספרי של INDEX_ENDPOINT_ID בנקודת הקצה של האינדקס.

הגדרת חשבון השירות לשרת ה-proxy של Apigee

שרת ה-proxy של Apigee משתמש בחשבון שירות לקריאות ל-Vertex AI REST: ‏Embeddings API במדיניות SemanticCacheLookup, ‏upsertDatapoints במדיניות SemanticCachePopulate ויעד המודל. מקצים לחשבון השירות את התפקיד AI Platform User (roles/aiplatform.user):

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:SERVICE_ACCOUNT" \
  --role="roles/aiplatform.user"

כאשר SERVICE_ACCOUNT הוא כתובת האימייל של חשבון השירות שבו משתמש שרת ה-proxy. אתם מפנים לחשבון השירות הזה כשאתם פורסים את שרת ה-proxy בשלב 4: ייבוא ופריסה של שרת ה-proxy ל-API.

דרישות מוקדמות נוספות לפריסות של Apigee Hybrid

בפריסות של Apigee Hybrid, צריך לוודא שהדרישות הנוספות הבאות מתקיימות:

  • סביבת זמן ריצה היברידית בגרסה 1.16.11 ואילך, או בגרסה 1.17.0 ואילך, שמותקנת באשכול Kubernetes משלכם. הוראות להתקנת Apigee Hybrid התכונה הזו לא מוסיפה דרישות משלה לאשכול – כל אשכול היברידי נתמך יעבוד.
  • סביבה בינונית או מקיפה וקבוצת סביבות עם שם מארח של סביבת זמן ריצה, כמו ב-Apigee. אפשר לפרוס כללי מדיניות של שמירה סמנטית במטמון רק בסביבות בינוניות או מקיפות.
  • נגישות הרשת מסביבת זמן הריצה לנקודת הקצה הפרטית. מעבד הבקשות צריך להיות מסוגל לפתוח חיבור gRPC בטקסט פשוט לנקודת הקצה של Private Service Connect של החיפוש הווקטורי ב-TARGET_HOST:10000.
  • תעבורת נתונים יוצאת (egress) לקריאות REST. הקריאות Embeddings,‏ Populate ו-model-target מגיעות לממשק הציבורי של REGION-aiplatform.googleapis.com, ולכן זמן הריצה צריך גם נתיב ל-Google APIs – ישירות או דרך נתיב פרטי אם לאשכול אין תעבורת נתונים יוצאת ציבורית.

הגדרה ב-Apigee Hybrid

אפשר להשתמש בשמירה סמנטית במטמון בנקודת קצה פרטית (Private Service Connect) ב-Apigee Hybrid מגרסה 1.16.11 ואילך וב-גרסה 1.17.0 ואילך. הגדרת המדיניות והשלבים של החיפוש הווקטורי במדריך הזה זהים ל-Apigee, אבל ב-Apigee Hybrid אתם מריצים את סביבת זמן הריצה ומספקים את הקישוריות בעצמכם. מכיוון שפריסות היברידיות משתנות מאוד, הקטע הזה הוא הנחיה כללית ולא פקודות מדויקות. הדרישה היחידה שהתכונה הזו מוסיפה היא שסביבת זמן הריצה צריכה להיות מסוגלת להגיע לנקודת הקצה הפרטית דרך gRPC בטקסט פשוט.

לספק נגישות לרשת

בפריסות היברידיות, צריך לנהל את הקישוריות באופן ידני כי אין נקודת קצה של קישור שמנוהלת על ידי Apigee. יוצרים נקודת קצה (endpoint) של Private Service Connect ב-VPC של הצרכן שמפנה אל SERVICE_ATTACHMENT של החיפוש הווקטורי, ומשתמשים בכתובת ה-IP הפנימית שלה בתור TARGET_HOST בשרת ה-proxy. מידע נוסף זמין בקטע שלב 2: התחברות לצירוף השירות. הניתוב הספציפי (למשל, VPC משותף או GKE מקורי ב-VPC) תלוי בהגדרות של האשכול.

אם לאשכול אין תעבורת נתונים לאינטרנט הציבורי, ודאו שלסביבת זמן הריצה יש נתיב פרטי ל-Google APIs, כמו גישה פרטית ל-Google, כדי לטפל בתקשורת REST.

אחרי שיוצרים קישוריות ל-grpc://TARGET_HOST:10000, פועלים לפי השלבים הבאים – יצירה ופריסה של האינדקס, פיתוח שרת ה-proxy ובדיקה – שהם זהים גם ל-Apigee וגם ל-Apigee Hybrid.

סקירה כללית

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

כללי המדיניות SemanticCacheLookup ו-SemanticCachePopulate מצורפים לתהליכי הבקשה והתגובה, בהתאמה, של שרת proxy ל-API ב-Apigee. כשהשרת מקבל בקשה, מדיניות SemanticCacheLookup מחלצת את ההנחיה של המשתמש מהבקשה וממירה אותה לייצוג מספרי באמצעות Text embeddings API. חיפוש דמיון סמנטי מתבצע באמצעות חיפוש וקטורי כדי למצוא הנחיות דומות. אם נמצאת נקודת נתונים דומה של הנחיה, מתבצע חיפוש במטמון. אם נמצאו נתונים במטמון, התגובה מהמטמון מוחזרת ללקוח.

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

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

בקטעים הבאים מוסבר איך ליצור ולהגדיר את כללי המדיניות לשמירה במטמון סמנטי:

  1. מאמתים את המשאבים ומקבלים את הערכים שנדרשים ל-Apigee.
  2. מתחברים לצירוף השירות.
  3. יוצרים את חבילת ה-proxy ל-API.
  4. מייבאים ופורסים את ה-proxy ל-API.
  5. בודקים את כללי המדיניות של השמירה במטמון לפי משמעות.

שלב 1: מאמתים את המשאבים ומקבלים את הערכים שנדרשים ל-Apigee

לפני שמגדירים את Apigee, צריך לוודא שנקודת הקצה של אינדקס החיפוש ב-חיפוש וקטורי מופעלת ב-Private Service Connect ושהאינדקס פרוס. לאחר מכן קוראים את שני הערכים שמשמשים את שרת ה-proxy של Apigee: חיבור השירות ו-DEPLOYED_INDEX_ID.

מוודאים שהאינדקס נפרס ושנקודת הקצה חושפת קובץ מצורף של שירות Private Service Connect:

gcloud ai index-endpoints describe INDEX_ENDPOINT_ID \
  --project=$PROJECT_ID --region=$REGION \
  --format="value(deployedIndexes.privateEndpoints.serviceAttachment)"

הפקודה מחזירה שם משאב של צירוף שירות בפורמט projects/TENANT_PROJECT/regions/REGION/serviceAttachments/SERVICE_ATTACHMENT_NAME. במדריך הזה הערך הזה נקרא SERVICE_ATTACHMENT. אם הפקודה מחזירה ערך ריק, האינדקס עדיין לא נפרס בנקודת קצה של Private Service Connect. חוזרים אל הדרישות המוקדמות לאינדקס החיפוש ב-Vector Search ומסיימים לפרוס את האינדקס לפני שממשיכים.

קוראים את DEPLOYED_INDEX_ID של האינדקס שנפרס בנקודת הקצה:

gcloud ai index-endpoints describe INDEX_ENDPOINT_ID \
  --project=$PROJECT_ID --region=$REGION \
  --format="value(deployedIndexes.id)"

במדריך הזה הערך הזה נקרא DEPLOYED_INDEX_ID. משתמשים בו במדיניות SemanticCacheLookup בשלב 3: יצירת חבילת ה-proxy ל-API.

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

שלב 2: התחברות לצירוף השירות

בשלב הזה מקבלים את המארח הפרטי שאליו מתבצעות הקריאות של <GrpcEndpoint> בשרת ה-proxy. אופן היצירה של הקובץ תלוי בפלטפורמה שבה אתם משתמשים. הגדרת שרת ה-proxy בשלבים הבאים זהה בשתי הדרכים.

‫Apigee: יצירת נקודת קצה של קישור

ב-Apigee, יוצרים קובץ מצורף של נקודת קצה (endpoint) ב-Apigee. נקודת הקצה של הקישור היא צד הצרכן של Private Service Connect ב-Apigee. הוא מתחבר לקובץ המצורף של שירות החיפוש הווקטורי ונותן לכם מארח פרטי שהשרת proxy קורא לו.

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
        "location": "'"$REGION"'",
        "serviceAttachment": "SERVICE_ATTACHMENT"
      }' \
  "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/endpointAttachments?endpointAttachmentId=ENDPOINT_ATTACHMENT"

מבצעים סקר עד שהערך של state של הקובץ המצורף הוא ACTIVE והערך של connectionState הוא ACCEPTED, ואז מציינים את המארח: 

curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/endpointAttachments/ENDPOINT_ATTACHMENT"

התשובה מכילה את המארח בשדה host. במדריך הזה הערך הזה נקרא TARGET_HOST.

כדי להתחבר לחיבור של שירות החיפוש הווקטורי מהשרת proxy, אתם יכולים להשתמש באחת מהאפשרויות הבאות:

  • כתובת ה-IP: משתמשים בכתובת ה-IP שמוחזרת בשדה host ישירות בתור TARGET_HOST (לדוגמה, 7.0.3.4).
  • רשומת DNS פרטית: אם הגדרתם תחום Cloud DNS פרטי בפרויקט Google Cloud עם קישור בין רשתות שכנות (peering) ב-DNS ל-Apigee, אתם יכולים ליצור רשומת A בתחום הפרטי שמפנה לכתובת ה-IP של נקודת הקצה של הקישור, ולהשתמש בשם הדומיין הזה (למשל vectorsearch.example.com) בתור TARGET_HOST. מידע נוסף זמין במאמרים שימוש ברשומת DNS והתחברות באמצעות אזורי קישור בין רשתות שכנות (peering) ב-DNS פרטי.

נקודת קצה מסוג Private Service Connect ל-Apigee Hybrid

ב-Apigee, ‏ Google מספקת משאב מסוג "נקודת קצה של קישור" שמטפל בחיבור של Private Service Connect. עם זאת, ב-Apigee Hybrid אתם מנהלים את סביבת זמן הריצה ואת סביבת הרשת. לא משנה איפה האשכול פועל, הוא צריך להיות מסוגל להגיע לנקודת הקצה של Private Service Connect של החיפוש הווקטורי דרך חיבור gRPC בטקסט פשוט אל host:10000.

ב-Apigee Hybrid, יוצרים נקודת קצה (endpoint) של Private Service Connect ב- Google Cloud VPC של הצרכן שמפנה אל SERVICE_ATTACHMENT של החיפוש הווקטורי. משתמשים בכתובת ה-IP הפנימית של נקודת הקצה בתור TARGET_HOST בהגדרת ה-proxy. מוודאים שהפרויקט Google Cloud שמארח את נקודת הקצה הזו נכלל ב-projectAllowlist של נקודת הקצה של אינדקס החיפוש ב-חיפוש וקטורי. פרטים נוספים זמינים במאמר דרישות מוקדמות לאינדקס החיפוש של חיפוש וקטורי.

שלב 3: יוצרים את חבילת ה-proxy ל-API

יצירת חבילת ה-proxy

יוצרים את פריסת הספרייה הבאה: 

apiproxy/
├── PROXY_NAME.xml
├── proxies/default.xml
├── targets/default.xml
└── policies/
    ├── SCL-1.xml
    └── SCP-1.xml

‫policies/SCL-1.xml – המדיניות SemanticCacheLookup. הבלוק <SimilaritySearch> משתמש ב-<PrivateServiceConnect><GrpcEndpoint> (בלי <URL>).

הערה: כללי <GrpcEndpoint>:

  • הפורמט הוא grpc://TARGET_HOST:PORT, והסכימה חייבת להיות grpc://. ‫grpcs:// (TLS) לא נתמך בגרסה הזו.
  • היציאה היא 10000 לחיפוש וקטורי. נקודות הקצה של מישור הנתונים של Private Service Connect משרתות את gRPC ביציאה 10000, כך שנקודת הקצה היא תמיד grpc://TARGET_HOST:10000.
  • ‫TARGET_HOST יכול להיות כתובת ה-IP של נקודת הקצה של הקישור (משלב 2) או רשומת DNS בהתאמה אישית שנוצרה בתחום ה-DNS הפרטי.
  • הדילוג של gRPC הוא טקסט פשוט ולא מאומת (מאובטח באמצעות בידוד רשת).
<SemanticCacheLookup async="false" continueOnError="false" enabled="true" name="SCL-1">
  <DisplayName>SCL-1</DisplayName>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <UserPromptSource>{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}</UserPromptSource>
  <Embeddings>
    <VertexAI>
      <URL>https://REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/publishers/google/models/gemini-embedding-001:predict</URL>
    </VertexAI>
  </Embeddings>
  <SimilaritySearch>
    <VertexAI>
      <PrivateServiceConnect>
        <GrpcEndpoint>grpc://TARGET_HOST:10000</GrpcEndpoint>
      </PrivateServiceConnect>
      <DeployedIndexID>DEPLOYED_INDEX_ID</DeployedIndexID>
      <Threshold>0.95</Threshold>
    </VertexAI>
  </SimilaritySearch>
</SemanticCacheLookup>

‫policies/SCP-1.xml – המדיניות SemanticCachePopulate. האכלוס הוא REST בלבד וחייב להשתמש ב-<URL> (הוא דוחה את <PrivateServiceConnect> בזמן הפריסה): 

<SemanticCachePopulate async="false" continueOnError="true" enabled="true" name="SCP-1">
  <DisplayName>SCP-1</DisplayName>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <SimilaritySearch>
    <VertexAI>
      <URL>https://REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/indexes/INDEX_ID:upsertDatapoints</URL>
    </VertexAI>
  </SimilaritySearch>
  <TTLInSeconds>3600</TTLInSeconds>
</SemanticCachePopulate>

‫targets/default.xml – היעד של המודל. היעד שולח קריאה ל-Google API, ולכן הוא צריך אסימון. <GoogleAccessToken> משתמש בחשבון השירות של הפריסה: 

<TargetEndpoint name="default">
  <PreFlow name="PreFlow"><Request/><Response/></PreFlow>
  <PostFlow name="PostFlow"><Request/><Response/></PostFlow>
  <HTTPTargetConnection>
    <Authentication>
      <GoogleAccessToken>
        <Scopes>
          <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
        </Scopes>
      </GoogleAccessToken>
    </Authentication>
    <URL>https://REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/publishers/google/models/gemini-2.5-flash:generateContent</URL>
  </HTTPTargetConnection>
</TargetEndpoint>

‫proxies/default.xml – הפעלת המדיניות SemanticCacheLookup בבקשה והמדיניות SemanticCachePopulate בתגובה: 

<ProxyEndpoint name="default">
  <PreFlow name="PreFlow">
    <Request><Step><Name>SCL-1</Name></Step></Request>
    <Response><Step><Name>SCP-1</Name></Step></Response>
  </PreFlow>
  <PostFlow name="PostFlow"><Request/><Response/></PostFlow>
  <HTTPProxyConnection>
    <BasePath>/PROXY_NAME</BasePath>
  </HTTPProxyConnection>
  <RouteRule name="default">
    <TargetEndpoint>default</TargetEndpoint>
  </RouteRule>
</ProxyEndpoint>

‫PROXY_NAME.xml – תיאור החבילה: 

<APIProxy name="PROXY_NAME">
  <BasePaths>/PROXY_NAME</BasePaths>
  <Policies><Policy>SCL-1</Policy><Policy>SCP-1</Policy></Policies>
  <ProxyEndpoints><ProxyEndpoint>default</ProxyEndpoint></ProxyEndpoints>
  <TargetEndpoints><TargetEndpoint>default</TargetEndpoint></TargetEndpoints>
</APIProxy>

שלב 4: מייבאים ופורסים את ה-proxy ל-API

מכווצים את החבילה, מייבאים אותה כדי ליצור גרסה חדשה ופורסים את הגרסה באמצעות חשבון השירות: 

TOKEN=$(gcloud auth print-access-token)
(cd BUNDLE_DIR && zip -r ../PROXY_NAME.zip apiproxy)
curl -X POST -H "Authorization: Bearer $TOKEN" \
  -F "file=@PROXY_NAME.zip" \
  "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/apis?action=import&name=PROXY_NAME"
curl -X POST -H "Authorization: Bearer $TOKEN" \
  "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/ENV/apis/PROXY_NAME/revisions/REVISION/deployments?override=true&serviceAccount=SERVICE_ACCOUNT"

כאשר:

  • ‫BUNDLE_DIR היא הספרייה שמכילה את התיקייה apiproxy/. הארכיון חייב להכיל את התיקייה apiproxy/ ברמה הבסיסית (root).
  • ‫ENV היא סביבת Apigee שבה פורסים את שרת ה-Proxy. הסביבה חייבת להיות סביבה בינונית או מקיפה.
  • ‫REVISION הוא מספר הגרסה שמוחזר על ידי קריאת הייבוא.
  • ‫SERVICE_ACCOUNT היא כתובת האימייל של חשבון השירות שמשמש לפריסת שרת ה-proxy.

מחכים עד שהפריסה תדווח על READY: 

curl -s -H "Authorization: Bearer $TOKEN" \
  "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/ENV/apis/PROXY_NAME/revisions/REVISION/deployments" | jq .state

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

שולחים הנחיה חדשה. זהו מצב של אי מציאה במטמון: המודל נקרא והתשובה נשמרת במטמון. 

curl -X POST "https://$RUNTIME_HOSTNAME/PROXY_NAME" \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"role":"user","parts":[{"text":"Explain in one sentence why the sky appears blue."}]}]}'

לשלוח שוב את אותה הנחיה. זוהי מציאה במטמון (cache hit): התשובה נשלחת מהמטמון והמודל לא נקרא. 

curl -i -X POST "https://$RUNTIME_HOSTNAME/PROXY_NAME" \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"role":"user","parts":[{"text":"Explain in one sentence why the sky appears blue."}]}]}'

במקרה של היט, התשובה כוללת את הכותרת Cached-content: true, אותה תשובה וזמן אחזור נמוך באופן משמעותי.

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

משתנה ערך בהיט
SemanticCacheLookup.SCL-1.dense_embeddings וקטור ההטמעה של ההנחיה.
SemanticCacheLookup.SCL-1.is_nearest_neighbor_hit true
SemanticCacheLookup.SCL-1.cache_hit true
SemanticCacheLookup.SCL-1.cached_llm_response התשובה שנשמרה במטמון.

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

פתרון בעיות

לרשימה המלאה של השגיאות, קראו את המדיניות SemanticCacheLookup.

מגבלות

המגבלות הבאות חלות על כללי המדיניות של שמירה סמנטית במטמון:

  • גודל הטקסט המקסימלי שאפשר לשמור במטמון הוא 256KB. מידע נוסף זמין בקטע גודל ערך המטמון בדף המגבלות של Apigee.
  • ‫Apigee מתעלמת מכל כותרות cache-control שהיא מקבלת ממודל ה-LLM.
  • אם המטמון לא מבוטל כמו שצריך או אם אלגוריתם הדמיון הסמנטי לא מספיק מדויק כדי להבדיל בין קלטים עם משמעויות דומות מאוד, התשובה עשויה להחזיר מידע מיושן או שגוי.
  • התכונה "חיפוש וקטורי" לא נתמכת בכל האזורים. רשימת האזורים הנתמכים מופיעה בקטע זמינות התכונות בדף המיקומים של Vertex AI. אם הארגון שלכם ב-Apigee נמצא באזור שלא נתמך, תצטרכו ליצור נקודות קצה (endpoints) של אינדקסים באזור אחר.
  • כללי המדיניות של שמירה סמנטית במטמון לא נתמכים לשימוש עם שרתי proxy ל-API שמשתמשים ב-EventFlows לסטרימינג רציף של תגובות של אירועים שנשלחים מהשרת (SSE).
  • כללי המדיניות של שמירה במטמון סמנטי משתמשים בממשקי API של LLM, מה שעלול לגרום לזמני אחזור ארוכים יותר של מאות אלפיות השנייה.
  • בהתקנות של Apigee hybrid, התמיכה במדיניות של שמירה סמנטית במטמון מוגבלת להתקנות ב-Google Cloud Platform.
  • כשמגדירים את המדיניות SemanticCacheLookup כך שתשתמש בנקודת קצה פרטית של חיפוש וקטורי דרך Private Service Connect ‏ (PSC), הקריאה לחיפוש דמיון נשלחת דרך חיבור gRPC ישיר לנקודת הקצה הפרטית ולא עוברת דרך שרת פרוקסי להעברה שהוגדר.

המאמרים הבאים