Struktur dan format data input

Untuk membuat indeks baru atau memperbarui indeks yang sudah ada, sediakan vektor ke Vector Search dalam format dan struktur yang dijelaskan di bagian berikut.

Prasyarat

Simpan data input Anda di bucket Cloud Storage, di project Google Cloud Anda.

File data input harus diatur sebagai berikut:

  • Setiap batch file data input harus berada di satu direktori Cloud Storage.
  • File data harus ditempatkan langsung di batch_root dan diberi nama dengan akhiran berikut: .csv, .json, dan .avro.
  • Ada batas 5.000 objek (file) dalam direktori root batch.
  • Setiap file data diinterpretasikan sebagai kumpulan data. Format kumpulan data ditentukan oleh akhiran nama file dan persyaratan format tersebut dijelaskan. Lihat Format file data.
  • Setiap kumpulan data harus memiliki id, vektor fitur, dan kolom opsional yang didukung oleh Vertex AI Feature Store, seperti pembatasan dan kepadatan.
  • Mungkin ada subdirektori bernama delete. Setiap file yang berada di batch_root/delete dianggap sebagai file teks dari kumpulan data id yang berisi satu id di setiap baris.
  • Semua subdirektori lainnya tidak diizinkan.
  • Transcoding file yang dikompresi dengan gzip tidak didukung sebagai data input.

Pemrosesan data input

  • Semua kumpulan data dari semua file data, termasuk data di delete, terdiri dari satu batch input.
  • Urutan relatif kumpulan data dalam file data tidaklah penting.
  • Satu ID hanya boleh muncul sekali dalam satu batch. Jika terdapat duplikat dengan ID yang sama, maka duplikat tersebut akan ditampilkan sebagai satu vektor.
  • ID tidak dapat muncul dalam file data reguler dan file data penghapusan.
  • Semua ID dari file data penghapusan akan dihapus dari versi indeks berikutnya.
  • Kumpulan data dari file data reguler disertakan dalam versi berikutnya, yang akan menimpa nilai dalam versi indeks yang lebih lama.

Berikut adalah contoh sematan padat, renggang, dan hybrid:

  • Embedding padat:

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

  • Embedding renggang:

    {"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]}}

  • Embedding hybrid:

    {"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]}}

Berikut adalah contoh penyusunan file data input yang valid:

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

File feature_file_1.csv dan feature_file_2.csv berisi kumpulan data dalam format CSV. File delete_file.txt berisi daftar ID kumpulan data yang akan dihapus dari versi indeks berikutnya.

Format file data

JSON

  • Enkode file JSON menggunakan UTF-8.
  • Setiap baris file JSON akan ditafsirkan sebagai objek JSON terpisah.
  • Setiap data harus berisi kolom id untuk menentukan ID vektor.
  • Setiap data harus berisi setidaknya salah satu dari embedding atau sparse_embedding.
  • Kolom embedding adalah array bilangan floating point N yang merepresentasikan vektor fitur, dengan N adalah dimensi vektor fitur yang dikonfigurasi saat indeks dibuat. Kolom ini hanya dapat digunakan untuk sematan padat.
    • configs.dimensions, yang ditentukan pada waktu pembuatan indeks, harus memiliki panjang yang sama dengan embeddings. configs.dimensions hanya berlaku untuk embedding, bukan untuk sparse_embedding.
  • Kolom sparse_embedding adalah objek dengan kolom values dan dimensions. Kolom values adalah daftar bilangan floating point yang merepresentasikan vektor fitur dan kolom dimensions adalah daftar bilangan bulat yang merepresentasikan dimensi tempat nilai yang sesuai berada. Misalnya, sematan jarang yang terlihat seperti [0,0.1,0,0,0.2] dapat direpresentasikan sebagai "sparse_embedding": {"values": [0.1, 0.2], "dimensions": [1,4]}. Kolom ini hanya dapat digunakan untuk sematan jarang.
    • Panjang sparse_embedding.values harus sama dengan panjang sparse_embedding.dimensions. Panjangnya tidak harus sama dengan configs.dimensions, yang ditentukan pada saat pembuatan indeks dan tidak berlaku untuk sparse_embedding.
  • Kolom restricts opsional dapat disertakan yang menentukan array objek TokenNamespace dalam batasan. Untuk setiap objek:
    • Tentukan kolom namespace yang merupakan TokenNamespace.namespace.
    • Kolom allow opsional dapat disetel ke array string yang merupakan daftar TokenNamespace.string_tokens.
    • Kolom deny opsional dapat disetel ke array string yang merupakan daftar TokenNamespace.string_blacklist_tokens.
    • Nilai kolom crowding_tag, jika ada, harus berupa string.
  • Kolom numeric_restricts opsional dapat disertakan yang menentukan array NumericRestrictNamespace. Untuk setiap objek:
    • Tentukan kolom namespace yang merupakan NumericRestrictNamespace.namespace.
    • Salah satu kolom nilai value_int, value_float, dan value_double.
    • Tidak boleh memiliki kolom bernama op. Kolom ini hanya untuk kueri.

Avro

  • Gunakan file Avro yang valid.
  • Untuk merepresentasikan titik data khusus jarang, berikan sematan jarang di kolom sparse_embedding dan masukkan daftar kosong di kolom embedding.

  • Buat kumpulan data yang sesuai dengan skema berikut:

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

  • Format: ID,N feature vector values,Any number of dimension:value sparse values,name=value lists
  • Enkode file CSV menggunakan UTF-8.
  • Setiap baris CSV harus berisi tepat satu catatan.
  • Nilai pertama di setiap baris harus berupa ID vektor, yang harus berupa string UTF-8 yang valid.
  • Setelah ID, setidaknya satu penyematan padat atau penyematan jarang harus ditentukan.
  • Untuk embedding padat, N nilai berikutnya mewakili vektor fitur, dengan N adalah dimensi vektor fitur yang dikonfigurasi saat indeks dibuat.
  • Untuk penyematan jarang, sejumlah dimension:value dapat ditentukan, dengan value diuraikan sebagai float dan dimension diuraikan sebagai long.
  • Untuk penyematan hibrida yang memiliki penyematan padat dan jarang, penyematan padat harus ditentukan sebelum penyematan jarang.
  • Nilai vektor fitur harus berupa literal floating point sebagaimana ditentukan dalam spesifikasi bahasa Java.
  • Nilai tambahan dapat berupa name=value.
  • Nama crowding_tag ditafsirkan sebagai tag kepadatan dan hanya dapat muncul sekali dalam catatan.

  • Semua pasangan name=value lainnya ditafsirkan sebagai batasan namespace token. Nama yang sama dapat diulang jika terdapat beberapa nilai dalam satu namespace.

    Misalnya, color=red,color=blue merepresentasikan TokenNamespace ini:

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

  • Jika nilai dimulai dengan !, string lainnya akan ditafsirkan sebagai nilai yang dikecualikan.

    Misalnya, color=!red merepresentasikan TokenNamespace ini:

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

  • Pasangan #name=numericValue dengan akhiran jenis angka ditafsirkan sebagai batasan namespace numerik. Sufiks jenis angka adalah i untuk int, f untuk float, dan d untuk double. Nama yang sama tidak boleh diulang karena hanya boleh ada satu nilai yang terkait per namespace.

    Misalnya, #size=3i merepresentasikan NumericRestrictNamespace ini:

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

    #ratio=0.1f merepresentasikan NumericRestrictNamespace ini:

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

    #weight=0.3d merepresentasikan NumericRestriction ini:

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

  • Contoh berikut adalah titik data dengan id: "6", embedding: [7, -8.1], sparse_embedding: {values: [0.1, -0.2, 0.5], dimensions: [40, 901, 1111]}, tag keramaian test, daftar yang diizinkan token color: red, blue, daftar yang ditolak token color: purple, dan batasan numerik ratio dengan float 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

Langkah berikutnya