הפורמט והמבנה של נתוני הקלט

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

דרישות מוקדמות

מאחסנים את נתוני הקלט בקטגוריה של Cloud Storage, בפרויקט Google Cloud .

קבצי נתוני הקלט צריכים להיות מאורגנים באופן הבא:

• כל קבוצה של קובצי נתוני קלט צריכה להיות בספרייה אחת ב-Cloud Storage.
• צריך למקם את קובצי הנתונים ישירות מתחת ל-batch_root ולתת להם שמות עם הסיומות הבאות: .csv, .json ו-.avro.
• יש מגבלה של 5,000 אובייקטים (קבצים) בספריית השורש של החבילה.
• כל קובץ נתונים מתפרש כקבוצה של רשומות. הפורמט של הרשומה נקבע לפי הסיומת של שם הקובץ, והדרישות לגבי הפורמט מתוארות. פורמטים של קובצי נתונים
• כל רשומה צריכה לכלול id, וקטור תכונות ושדות אופציונליים שנתמכים על ידי Vertex AI Feature Store, כמו restrictions ו-crowding.
• יכול להיות שקיימת תת-ספרייה בשם delete. כל קובץ שנמצא ישירות מתחת ל-batch_root/delete נחשב לקובץ טקסט של id רשומות, כשכל שורה מכילה id.
• אסור להשתמש בכל שאר תיקיות המשנה.
• אין תמיכה בהמרת קידוד של קבצים דחוסים באמצעות gzip כנתוני קלט.

עיבוד נתוני הקלט

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

דוגמאות להטמעות צפופות, דלילות והיברידיות:

• הטמעות צפופות:

  {"id": "1", "embedding": [1,1,1]}
  {"id": "2", "embedding": [2,2,2]}
  

• הטמעות דלילות:

  {"id": "3", "sparse_embedding": {"values": [0.1, 0.2], "dimensions": [1, 4]}}
  {"id": "4", "sparse_embedding": {"values": [-0.4, 0.2, -1.3], "dimensions": [10, 20, 20]}}
  

• הטמעות היברידיות:

  {"id": "5", "embedding": [5, 5, -5], "sparse_embedding": {"values": [0.1], "dimensions": [500]}}
  {"id": "6", "embedding": [6, 7, -8.1], "sparse_embedding": {"values": [0.1, -0.2], "dimensions": [40, 901]}}
  

דוגמה לארגון קובץ נתוני קלט תקין:

batch_root/
  feature_file_1.csv
  feature_file_2.csv
  delete/
    delete_file.txt

הקבצים feature_file_1.csv ו-feature_file_2.csv מכילים רשומות בפורמט CSV. הקובץ delete_file.txt מכיל רשימה של מזהי רשומות שיימחקו מהגרסה הבאה של האינדקס.

פורמטים של קובצי נתונים

JSON

• מקודדים את קובץ ה-JSON באמצעות UTF-8.
• כל שורה בקובץ ה-JSON תפורש כאובייקט JSON נפרד.
• כל רשומה צריכה לכלול שדה id כדי לציין את המזהה של הווקטור.
• כל רשומה צריכה להכיל לפחות אחד מהערכים embedding או sparse_embedding.
• השדה embedding הוא מערך של N מספרים עשרוניים שמייצגים את וקטור התכונות, כאשר N הוא הממד של וקטור התכונות שהוגדר כשנוצר האינדקס. אפשר להשתמש בשדה הזה רק להטמעות צפופות.
  • ‫configs.dimensions, שמוגדר בזמן יצירת האינדקס, חייב להיות באורך זהה לזה של embeddings. הפונקציה configs.dimensions חלה רק על embedding, ולא על sparse_embedding.
• השדה sparse_embedding הוא אובייקט עם השדות values ו-dimensions. השדה values הוא רשימה של מספרים עם נקודה עשרונית שמייצגים את וקטור התכונות, והשדה dimensions הוא רשימה של מספרים שלמים שמייצגים את המימד שבו נמצא הערך התואם. לדוגמה, אפשר לייצג הטמעה דלילה שנראית כך: [0,0.1,0,0,0.2], באופן הבא: "sparse_embedding": {"values": [0.1, 0.2], "dimensions": [1,4]}. אפשר להשתמש בשדה הזה רק להטמעות דלילות.
  • האורך של sparse_embedding.values חייב להיות זהה לאורך של sparse_embedding.dimensions. הם לא צריכים להיות באורך זהה ל-configs.dimensions, שמצוין בזמן יצירת האינדקס ולא חל על sparse_embedding.
• אפשר לכלול שדה אופציונלי restricts שמציין מערך של אובייקטים TokenNamespace ב-restricts. לכל אובייקט:
  • מציינים שדה namespace שהוא TokenNamespace.namespace.
  • אפשר להגדיר שדה אופציונלי allow כמערך של מחרוזות שהן רשימת TokenNamespace.string_tokens.
  • אפשר להגדיר שדה אופציונלי deny כמערך של מחרוזות שהן רשימת TokenNamespace.string_blacklist_tokens.
  • אם השדה crowding_tag קיים, הערך שלו חייב להיות מחרוזת.
• אפשר לכלול שדה אופציונלי numeric_restricts שמציין מערך של NumericRestrictNamespace. לכל אובייקט:
  • מציינים שדה namespace שהוא NumericRestrictNamespace.namespace.
  • אחד משדות הערך value_int, value_float ו-value_double.
  • אסור שיהיה בו שדה בשם op. השדה הזה מיועד רק לשאילתות.

Avro

• צריך להשתמש בקובץ Avro תקין.
• כדי לייצג נקודת נתונים דלילה בלבד, מספקים הטמעה דלילה בשדה sparse_embedding ומזינים רשימה ריקה בשדה embedding.

• יוצרים רשומות לפי הסכימה הבאה:

  {
    "type": "record",
    "name": "FeatureVector",
    "fields": [
      {
        "name": "id",
        "type": "string"
      },
      {
        "name": "embedding",
        "type": {
          "type": "array",
          "items": "float"
        }
      },
      {
        "name": "sparse_embedding",
        "type": [
          "null",
          {
            "type": "record",
            "name": "sparse_embedding",
            "fields": [
              {
                "name": "values",
                "type": {
                  "type": "array",
                  "items": "float"
                }
              },
              {
                "name": "dimensions",
                "type": {
                  "type": "array",
                  "items": "long"
                }
              }
            ]
          }
        ]
      },
      {
        "name": "restricts",
        "type": [
          "null",
          {
            "type": "array",
            "items": {
              "type": "record",
              "name": "Restrict",
              "fields": [
                {
                  "name": "namespace",
                  "type": "string"
                },
                {
                  "name": "allow",
                  "type": [
                    "null",
                    {
                      "type": "array",
                      "items": "string"
                    }
                  ]
                },
                {
                  "name": "deny",
                  "type": [
                    "null",
                    {
                      "type": "array",
                      "items": "string"
                    }
                  ]
                }
              ]
            }
          }
        ]
      },
      {
        "name": "numeric_restricts",
        "type": [
          "null",
          {
            "type": "array",
            "items": {
              "name": "NumericRestrict",
              "type": "record",
              "fields": [
                {
                  "name": "namespace",
                  "type": "string"
                },
                {
                  "name": "value_int",
                  "type": [ "null", "int" ],
                  "default": null
                },
                {
                  "name": "value_float",
                  "type": [ "null", "float" ],
                  "default": null
                },
                {
                  "name": "value_double",
                  "type": [ "null", "double" ],
                  "default": null
                }
              ]
            }
          }
        ],
        "default": null
      },
      {
        "name": "crowding_tag",
        "type": [
          "null",
          "string"
        ]
      }
    ]
  }
  

CSV

• פורמט: ID,N feature vector values,Any number of dimension:value sparse values,name=value lists
• מקודדים את קובץ ה-CSV באמצעות UTF-8.
• כל שורה בקובץ ה-CSV צריכה להכיל רשומה אחת בדיוק.
• הערך הראשון בכל שורה חייב להיות מזהה הווקטור, שחייב להיות מחרוזת UTF-8 תקינה.
• אחרי המזהה, צריך לציין לפחות הטמעה צפופה אחת או הטמעה דלילה אחת.
• במקרה של הטמעה צפופה, N הערכים הבאים מייצגים את וקטור התכונות, כאשר N הוא המימד של וקטור התכונות שהוגדר כשנוצר האינדקס.
• בהטמעה דלילה, אפשר לציין כל מספר של dimension:value, כאשר value מנותח כמספר עשרוני ו-dimension מנותח כ-long.
• בהטמעה היברידית שכוללת גם הטמעות צפופות וגם הטמעות דלילות, צריך לציין את ההטמעות הצפופות לפני ההטמעות הדלילות.
• ערכי הווקטור של התכונות צריכים להיות מספרים עשרוניים קבועים, כמו שמוגדר במפרט של שפת Java.
• ערכים נוספים יכולים להיות בפורמט name=value.
• השם crowding_tag מתפרש כתג ריווח, והוא יכול להופיע רק פעם אחת ברשומה.

• כל שאר הזוגות name=value מפורשים כהגבלות של מרחב שמות של טוקנים. יכול להיות ששם יחזור על עצמו אם יש כמה ערכים במרחב שמות.

  לדוגמה, color=red,color=blue מייצג את TokenNamespace:

  {
    "namespace": "color"
    "string_tokens": ["red", "blue"]
  }
  

• אם הערך מתחיל ב-!, שאר המחרוזת מתפרשת כערך מוחרג.

  לדוגמה, color=!red מייצג את TokenNamespace:

  {
    "namespace": "color"
    "string_blacklist_tokens": ["red"]
  }
  

• ‫#name=numericValue pairs with number type suffix is interpreted as numeric namespace restricts. הסיומת של סוג המספר היא i עבור int,‏ f עבור float ו-d עבור double. אסור לחזור על אותו שם כי לכל מרחב שמות צריך להיות משויך ערך יחיד.

  לדוגמה, #size=3i מייצג את NumericRestrictNamespace:

  {
    "namespace": "size"
    "value_int": 3
  }
  

  #ratio=0.1f מייצג את NumericRestrictNamespace:

  {
    "namespace": "ratio"
    "value_float": 0.1
  }
  

  #weight=0.3d מייצג את NumericRestriction:

  {
    "namespace": "weight"
    "value_double": 0.3
  }
  

• בדוגמה הבאה מוצג נתון עם id: "6", embedding: [7, -8.1], sparse_embedding: {values: [0.1, -0.2, 0.5], dimensions: [40, 901, 1111]}, תג הצפיפות test, רשימת הטוקנים המותרים color: red, blue, רשימת הטוקנים האסורים color: purple וההגבלה המספרית ratio עם הערך 0.1:

  6,7,-8.1,40:0.1,901:-0.2,1111:0.5,crowding_tag=test,color=red,color=blue,color=!purple,ratio=0.1f
  

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

• איך יוצרים ומנהלים את האינדקס