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.

Pengaturan file dan penyimpanan data input

Prasyarat

Simpan data input Anda di bucket Cloud Storage, dalam 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) di 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.

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 penyematan rapat, jarang, dan campuran:

  • Embedding rapat:

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

  • Embed jarang (Pratinjau publik):

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

  • Penyematan campuran (Pratinjau publik):

    {"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 kumpulan data harus berisi kolom id untuk menentukan ID vektor.
  • Setiap data harus berisi minimal salah satu dari embedding atau sparse_embedding.
  • Kolom embedding adalah array bilangan floating point N yang mewakili vektor fitur, dengan N adalah dimensi vektor fitur yang dikonfigurasi saat indeks dibuat. Kolom ini hanya dapat digunakan untuk penyematan 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 mewakili vektor fitur dan kolom dimensions adalah daftar bilangan bulat yang mewakili dimensi tempat nilai yang sesuai berada. Misalnya, penyematan 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 penyematan jarang.
    • Panjang sparse_embedding.values harus sama dengan sparse_embedding.dimensions. Panjangnya tidak perlu sama dengan configs.dimensions, yang ditentukan pada waktu 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 ditetapkan ke array string yang merupakan daftar TokenNamespace.string_tokens.
    • Kolom deny opsional dapat ditetapkan 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 penyematan 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 kumpulan data.
  • Nilai pertama di setiap baris harus berupa ID vektor, yang harus berupa string UTF-8 yang valid.
  • Setelah ID, setidaknya satu penyematan rapat atau penyematan jarang harus ditentukan.
  • Untuk penyematan padat, nilai N berikutnya mewakili vektor fitur, dengan N adalah dimensi vektor fitur yang dikonfigurasi saat indeks dibuat.
  • Untuk penyematan jarang, jumlah dimension:value apa pun dapat ditentukan, dengan value diuraikan sebagai float dan dimension diuraikan sebagai long.
  • Untuk penyematan campuran 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 data.

  • Semua pasangan name=value lainnya ditafsirkan sebagai batasan namespace token. Nama yang sama dapat diulang jika terdapat beberapa nilai dalam 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. Akhiran jenis angka adalah i untuk int, f untuk float, dan d untuk double. Nama yang sama tidak boleh diulang karena harus ada satu nilai yang terkait per namespace.

    Misalnya, #size=3i merepresentasikan NumericRestrictNamespace ini:

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

    #ratio=0.1f mewakili NumericRestrictNamespace ini:

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

    #weight=0.3d mewakili 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 kepadatan test, daftar yang diizinkan token color: red, blue, daftar yang ditolak token color: purple, dan batasan numerik ratio dengan 0.1 float:

    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 selanjutnya