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 Anda Google Cloud .

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 Feature Store Platform Agen Gemini Enterprise, 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 akan disertakan dalam versi berikutnya, yang akan menimpa nilai dalam versi indeks yang lebih lama.

Berikut adalah contoh embedding 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 diinterpretasikan sebagai objek JSON terpisah.
  • Setiap kumpulan data harus berisi kolom id untuk menentukan ID vektor.
  • Setiap kumpulan data harus berisi setidaknya salah satu dari embedding atau sparse_embedding.
  • Kolom embedding adalah array dari N angka floating point yang mewakili vektor fitur, dengan N adalah dimensi vektor fitur yang dikonfigurasi saat indeks dibuat. Kolom ini hanya dapat digunakan untuk embedding 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 angka floating point yang mewakili vektor fitur dan kolom dimensions adalah daftar bilangan bulat yang mewakili dimensi tempat nilai yang sesuai berada. Misalnya, embedding renggang 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 embedding renggang.
    • Panjang sparse_embedding.values harus sama dengan panjang sparse_embedding.dimensions. Panjangnya tidak harus 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.
    • Kolom ini tidak boleh memiliki kolom bernama op. Kolom ini hanya untuk kueri.

Avro

  • Gunakan file Avro yang valid.
  • Untuk merepresentasikan titik data khusus renggang, berikan embedding renggang 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 salah satu dari embedding padat atau embedding renggang harus ditentukan.
  • Untuk embedding padat, N nilai berikutnya mewakili vektor fitur, dengan N adalah dimensi vektor fitur yang dikonfigurasi saat indeks dibuat.
  • Untuk embedding renggang, berapa pun jumlah dimension:value dapat ditentukan, dengan value diuraikan sebagai float dan dimension diuraikan sebagai long.
  • Untuk embedding hybrid yang memiliki embedding padat dan renggang, embedding padat harus ditentukan sebelum embedding renggang.
  • Nilai vektor fitur harus berupa literal floating point sebagaimana ditentukan dalam spesifikasi bahasa Java.
  • Nilai tambahan dapat berupa name=value.
  • Nama crowding_tag diinterpretasikan sebagai tag kepadatan dan hanya dapat muncul sekali dalam kumpulan data.

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

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

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

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

    Misalnya, color=!red mewakili TokenNamespace ini:

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

  • Pasangan #name=numericValue dengan akhiran jenis angka diinterpretasikan 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 mewakili 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 tidak diizinkan 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