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

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

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

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

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

• כל קבוצה של קובצי נתוני קלט צריכה להיות בספרייה אחת ב-Cloud Storage.
• צריך למקם את קובצי הנתונים ישירות מתחת ל-batch_root ולתת להם שמות עם הסיומות הבאות: .csv,‏ .json ו-.avro.
• יש מגבלה של 5,000 אובייקטים (קבצים) בספריית השורש של האצווה.
• כל קובץ נתונים מתפרש כקבוצה של רשומות. הפורמט של הרשומה נקבע לפי הסיומת של שם הקובץ, והדרישות לגבי הפורמט מתוארות. פורמטים של קובצי נתונים
• לכל רשומה צריכים להיות id, וקטור תכונות והשדות האופציונליים שלכם שנתמכים על ידי Feature Store של Gemini Enterprise Agent Platform, כמו הגבלות וצפיפות.
• יכולה להיות ספריית משנה בשם 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 עם סיומת של סוג מספר מפורשים כמגבלות של מרחב שמות מספרי. סיומת של סוג מספר היא 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
  

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

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