Format et structure des données d'entrée

Pour créer un index ou mettre à jour un index existant, vous devez fournir des vecteurs à Vector Search, dont le format et la structure sont décrits dans les sections suivantes.

Stockage de données d'entrée et organisation des fichiers

Conditions préalables

Stockez vos données d'entrée dans un bucket Cloud Storage, dans votre projet Google Cloud.

Les fichiers de données d'entrée doivent être organisés comme suit :

  • Chaque lot de fichiers de données d'entrée doit se trouver dans un seul et même répertoire Cloud Storage.
  • Les fichiers de données doivent être placés directement sous batch_root et nommés avec les suffixes suivants : .csv, .json et .avro.
  • Le répertoire racine de lot peut contenir jusqu'à 5 000 objets (fichiers).
  • Chaque fichier de données est interprété comme un ensemble d'enregistrements. Le format de l'enregistrement est déterminé par le suffixe du nom de fichier et les exigences inhérentes au format sont décrites. Consultez la page Formats de fichiers de données.
  • Chaque enregistrement doit avoir un id et un vecteur de caractéristiques en plus de vos champs facultatifs compatibles avec Vertex AI Feature Store, tels que les restrictions et le regroupement.
  • Un sous-répertoire nommé delete peut être présent. Chaque fichier situé directement sous batch_root/delete est traité sous la forme d'un fichier texte d'enregistrements id, avec un id sur chaque ligne.
  • Tous les autres répertoires et fichiers sont ignorés.

Traitement des données d'entrée

  • Tous les enregistrements de tous les fichiers de données, y compris ceux situés sous delete, constituent un seul et même lot d'entrées.
  • L'ordre relatif des enregistrements dans un fichier de données est sans importance.
  • Un ID ne doit apparaître qu'une seule fois dans un lot. S'il existe un doublon avec le même ID, ces deux éléments ne seront affichés et comptabilisés que comme un seul vecteur.
  • Un ID ne peut pas figurer à la fois dans un fichier de données standard et dans un fichier de données de suppression.
  • Tous les ID d'un fichier de données sous "delete" sont supprimés de la version d'index suivante.
  • Les enregistrements issus de fichiers de données standards sont inclus dans la version suivante, en écrasant une valeur présente dans une ancienne version d'index.

Voici des exemples d'embeddings denses, creux et hybrides :

  • Embeddings denses

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

  • Embeddings creux (version Preview publique) :

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

  • Embeddings hybrides (version Preview publique) :

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

Voici un exemple d'organisation de fichiers de données d'entrée valide :

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

Les fichiers feature_file_1.csv et feature_file_2.csv contiennent des enregistrements au format CSV. Le fichier delete_file.txt contient la liste des identifiants d'enregistrement à supprimer de la prochaine version d'index.

Formats de fichiers de données

JSON

  • Encodez le fichier JSON en UTF-8.
  • Chaque ligne du fichier JSON est interprétée comme un objet JSON distinct.
  • Chaque enregistrement doit contenir un champ id pour spécifier l'ID du vecteur.
  • Chaque enregistrement doit contenir au moins l'un des éléments embedding ou sparse_embedding.
  • Le champ embedding est un tableau de nombres à virgule flottante N qui représente le vecteur de caractéristiques, où N est la dimension du vecteur de caractéristiques configuré au moment de la création de l'index. Ce champ ne peut être utilisé que pour les embeddings denses.
    • configs.dimensions, spécifié au moment de la création de l'index, doit être de la même longueur que embeddings. configs.dimensions s'applique uniquement à embedding, et non à sparse_embedding.
  • Le champ sparse_embedding est un objet comportant les champs values et dimensions. Le champ values est une liste de nombres à virgule flottante qui représente le vecteur de caractéristiques, et le champ dimensions est une liste d'entiers qui représentent la dimension dans laquelle se trouve la valeur correspondante. Par exemple, un embedding creux semblable à [0,0.1,0,0,0.2] peut être représenté par "sparse_embedding": {"values": [0.1, 0.2], "dimensions": [1,4]}. Ce champ ne peut être utilisé que pour les embeddings creux.
    • La longueur de sparse_embedding.values doit être identique à celle de sparse_embedding.dimensions. Elles n'ont pas besoin d'avoir la même longueur que configs.dimensions, qui est spécifié au moment de la création de l'index et ne s'applique pas à sparse_embedding.
  • Vous pouvez inclure un champ restricts facultatif qui spécifie un tableau d'objets TokenNamespace dans les restrictions. Pour chaque objet :
    • Spécifiez un champ namespace qui correspond à TokenNamespace.namespace.
    • Un champ allow facultatif peut être défini sur un tableau de chaînes correspondant à la liste de TokenNamespace.string_tokens.
    • Un champ deny facultatif peut être défini sur un tableau de chaînes correspondant à la liste de TokenNamespace.string_blacklist_tokens.
    • La valeur du champ crowding_tag, s'il est présent, doit correspondre à une chaîne.
  • Vous pouvez inclure un champ numeric_restricts facultatif qui spécifie un tableau de NumericRestrictNamespace. Pour chaque objet :
    • Spécifiez un champ namespace qui correspond à NumericRestrictNamespace.namespace.
    • L'un des champs de valeur value_int, value_float et value_double.
    • Il ne doit pas comporter de champ nommé "op". Ce champ est réservé aux requêtes.

Avro

  • Utilisez un fichier Avro valide.
  • Pour représenter un point de données creux uniquement, fournissez un embedding creux dans le champ sparse_embedding et saisissez une liste vide dans le champ embedding.

  • Créez des enregistrements conformes au schéma suivant :

    {
  "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
  • Encodez le fichier CSV en UTF-8.
  • Chaque ligne du fichier CSV doit contenir exactement un enregistrement.
  • La première valeur de chaque ligne doit être l'ID de vecteur, qui doit être une chaîne UTF-8 valide.
  • Après l'ID, au moins un embedding dense ou creux doit être spécifié.
  • Pour un embedding dense, les valeurs N suivantes représentent le vecteur de caractéristiques, où N est la dimension du vecteur de caractéristiques configuré au moment de la création de l'index.
  • Pour un embedding creux, vous pouvez spécifier n'importe quel nombre de valeurs dimension:value. Dans ce cas, value est analysé en tant que nombre à virgule flottante et dimension en tant que valeur long.
  • Pour un embedding hybride présentant des embeddings creux et denses, les embeddings denses doivent être spécifiés avant les embeddings creux.
  • Les valeurs de vecteur de caractéristiques doivent être des littéraux à virgule flottante, tels que définis dans les spécifications du langage Java.
  • Les valeurs supplémentaires peuvent être au format name=value.
  • Le nom crowding_tag est interprété comme le tag de regroupement et ne peut apparaître qu'une seule fois dans l'enregistrement.

  • Toutes les autres paires name=value sont interprétées comme des restrictions d'espace de noms. Le même nom peut être répété s'il existe plusieurs valeurs dans un espace de noms.

    Par exemple, color=red,color=blue représente ce TokenNamespace :

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

  • Si la valeur commence par !, le reste de la chaîne est interprété comme une valeur exclue.

    Par exemple, color=!red représente ce TokenNamespace :

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

  • Les paires #name=numericValue avec un suffixe de type numérique sont interprétées comme des restrictions d'espace de noms numérique. Le suffixe de type numérique est i pour "int", f pour "float" et d pour "double". Le même nom ne doit pas être répété, car une seule valeur doit être associée par espace de noms.

    Par exemple, #size=3i représente ce NumericRestrictNamespace :

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

    #ratio=0.1f représente ce NumericRestrictNamespace :

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

    #weight=0.3d représente ce NumericRestriction :

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

  • L'exemple suivant est un point de données avec id: "6", embedding: [7, -8.1], sparse_embedding: {values: [0.1, -0.2, 0.5], dimensions: [40, 901, 1111]}}, le tag de regroupement test, la liste d'autorisation de jetons color: red, blue, la liste de blocage des jetons color: purple et une valeur numérique de restriction de ratio avec le nombre à virgule flottante 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

Étapes suivantes