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

Prérequis

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 un exemple en JSON :

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

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 un champ embedding qui est un tableau de N nombres à virgule flottante représentant 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.
  • 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.

  • 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": "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

  • 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, les N valeurs 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.
  • 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
}

Étapes suivantes