Vector Search embeddings with metadata

במדריך הזה מפורט מידע על מטא-נתונים אופציונליים להטמעות וקטוריות. באמצעות Vector Search אפשר להגדיר מטא-נתונים לכל הטמעה.

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

  • פרטי המוצר, כמו שם, מחיר וכתובת URL של תמונה.

  • תיאורים, תקצירים, תאריכים ופרטי מחבר להטמעות טקסט.

  • מידע על משתמשים להטמעות של משתמשים.

  • קואורדינטות של הטמעות של מקומות.

תכונות ויתרונות עיקריים

התכונות והיתרונות של שימוש במטא-נתונים כוללים:

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

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

  • לא ניתן לסינון: מטא-נתונים של הטמעת וקטורים משמשים לאחסון ולאחזור של מידע שלא ניתן לסינון, ושונה מ-restricts ומ-numeric_restricts.

  • עדכונים יעילים: השדה update_mask מאפשר לציין שממשקי ה-API רק מעדכנים את המטא-נתונים כדי להימנע משליחה מחדש של וקטורים להטמעה.

  • מידע מופרד: אפשר להפריד מידע שלא ניתן לסינון ממאפיינים שניתנים לסינון כמו restricts.

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

פורמט נתונים

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

דוגמה למבנה של נקודת נתונים:

    {
        "id": "movie_001",
        "embedding": [0.1, 0.2, ..., 0.3],
        "sparse_embedding": {
            "values": [-0.4, 0.2, -1.3],
            "dimensions": [10, 20, 30]
        },
        "numeric_restricts": [{'namespace': 'year', 'value_int': 2022}],
        "restricts": [{'namespace': 'genre', 'allow': ['action', 'comedy']}],

        # --- New embedding_metadata field ---
        "embedding_metadata": {
            "title": "Ballet Train",
            "runtime": {
                "hours": 2,
                "minutes": 6
            },
            "review_info": {
                "review": "This movie is fun and...",
                "rotten_potatoes_rating": 76
            }
        }
        # ------------------------------------
    },
    # ... other data points

הטמעת נתונים באמצעות embedding_metadata

כשמוסיפים נקודות נתונים, אפשר לכלול את embedding_metadata כשמתרחשת אחת מהפעולות הבאות:

  • העלאת קובץ (Cloud Storage):
  • באמצעות upsertDatapoints API:
    • מעבירים אובייקטים של נקודות נתונים (כולל embedding_metadata) במטען הייעודי (payload) של בקשת ה-API.

אחזור של embedding_metadata במהלך שאילתות

כשמבצעים חיפוש רגיל של השכן הקרוב ביותר באמצעות API‏ findNeighbors, השדה embedding_metadata של כל שכן נכלל אוטומטית בתגובה אם הערך של returnFullDatapoint מוגדר כ-True.

curl

curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://${PUBLIC_ENDPOINT_DOMAIN}/v1/projects/${PROJECT_ID}/locations/${LOCATION}/indexEndpoints/${INDEX_ENDPOINT_ID}:findNeighbors" \
-d '{deployedIndexId:"${DEPLOYED_INDEX_ID}", "queries":[{datapoint:{"featureVector":"<FEATURE_VECTOR>"}}], returnFullDatapoint:true}'

מתבצע עדכון של embedding_metadata

מעדכנים את המטא-נתונים באמצעות upsertDatapoints API ו-update_mask עם הערך embedding_metadata. יכול להיות שהשדה update_mask יכלול גם ערכי מסכה נוספים. לדוגמאות לשימוש במסכת שדות, אפשר לעיין במאמר בנושא עדכון מטא-נתונים של הטמעה.

השדה update_mask עוזר לוודא שרק embedding_metadata מתעדכן, וכך נמנעת שליחה מחדש של השדות restrict ו-embedding.

בדוגמה הבאה אפשר לראות איך מגדירים ומעדכנים מטא-נתונים כדי ליצור IndexDatapoint ממוקד, מציינים את update_mask ומפעילים את upsertDatapoints.

curl

curl -H "Content-Type: application/json" -H "Authorization: Bearer `gcloud auth print-access-token`" https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/indexes/${INDEX_ID}:upsertDatapoints \
-d '{
datapoints:[
    {
        datapoint_id: "'${DATAPOINT_ID_1}'",
        feature_vector: [...],
        embedding_metadata:{"title": "updated title", "rating": 4.5, "tags": ["updated", "reviewed"]
    }, update_mask: "embedding_metadata"}'