입력 데이터 형식 및 구조

새 색인을 빌드하거나 기존 색인을 업데이트하려면 다음 섹션에 설명된 형식과 구조로 벡터 검색에 벡터를 제공하세요.

입력 데이터 스토리지 및 파일 구성

기본 요건

입력 데이터를 Google Cloud 프로젝트의 Cloud Storage 버킷에 저장합니다.

입력 데이터 파일은 다음과 같이 구성해야 합니다.

  • 입력 데이터 파일의 각 배치는 단일 Cloud Storage 디렉터리 아래에 있어야 합니다.
  • 데이터 파일은 batch_root 바로 아래에 있고 이름에 .csv, .json, .avro 서픽스를 붙여야 합니다.
  • 일괄 루트 디렉터리에는 5,000개의 객체(파일) 한도가 적용됩니다.
  • 각 데이터 파일은 레코드 모음으로 해석됩니다. 레코드 형식은 파일 이름 서픽스에 의해 결정되며 이러한 형식 요구사항은 설명되어 있습니다. 데이터 파일 형식을 참조하세요.
  • 각 레코드에는 id, 특성 벡터가 있어야 하며 restricts 및 crowding 등 Vertex AI Feature Store에서 지원하는 옵션 필드가 있어야 합니다.
  • delete라는 하위 디렉터리가 있을 수 있습니다. batch_root/delete 바로 아래에 있는 각 파일은 id 레코드의 텍스트 파일로 사용되며 행마다 id 하나가 포함됩니다.
  • 다른 모든 디렉터리와 파일은 무시됩니다.

입력 데이터 처리

  • delete 아래의 레코드를 포함하여 모든 데이터 파일의 모든 레코드는 단일 입력 배치로 구성됩니다.
  • 데이터 파일 내에서 레코드의 상대적 순서는 중요하지 않습니다.
  • 단일 ID는 배치에 한 번만 나타나야 합니다. 동일한 ID의 중복이 있을 경우 하나의 벡터 수로 표시됩니다.
  • 일반 데이터 파일과 delete 데이터 파일 모두에 ID를 표시할 수는 없습니다.
  • 삭제할 데이터 파일의 모든 ID가 다음 색인 버전에서 삭제됩니다.
  • 일반 데이터 파일의 레코드가 다음 버전에 포함되며 이전 색인 버전의 값을 덮어씁니다.

다음은 밀집, 희소, 하이브리드 임베딩의 예시입니다.

  • 밀집 임베딩

    {"id": "1", "embedding": [1,1,1]}
    {"id": "2", "embedding": [2,2,2]}
    
  • 희소 임베딩(공개 미리보기):

    {"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]}}
    
  • 하이브리드 임베딩(공개 미리보기):

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

다음은 유효한 입력 데이터 파일 구성의 예시입니다.

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

feature_file_1.csvfeature_file_2.csv 파일에는 CSV 형식의 레코드가 포함되어 있습니다. delete_file.txt 파일에는 다음 색인 버전에서 삭제할 레코드 ID 목록이 포함되어 있습니다.

데이터 파일 형식

JSON

  • UTF-8을 사용하여 JSON 파일을 인코딩합니다.
  • JSON 파일의 각 줄은 별도의 JSON 객체로 해석됩니다.
  • 각 레코드에는 벡터 ID를 지정하는 id 필드가 포함되어야 합니다.
  • 각 레코드는 embedding 또는 sparse_embedding 중 하나 이상을 포함해야 합니다.
  • embedding 필드는 N 부동 소수점 수의 배열로 특성 벡터를 나타냅니다. 여기서 N은 색인이 생성될 때 구성된 특성 벡터의 차원입니다. 이 필드는 밀집 임베딩에만 사용할 수 있습니다.
    • 색인 생성 시 지정되는 configs.dimensionsembeddings와 길이가 같아야 합니다. configs.dimensionssparse_embedding이 아닌 embedding에만 적용됩니다.
  • sparse_embedding 필드는 valuesdimensions 필드가 있는 객체입니다. values 필드는 특성 벡터를 나타내는 부동 소수점 수의 목록이며 dimensions 필드는 해당 값이 위치한 차원을 나타내는 정수 목록입니다. 예를 들어 [0,0.1,0,0,0.2]와 같은 희소 임베딩은 "sparse_embedding": {"values": [0.1, 0.2], "dimensions": [1,4]}와 같이 나타낼 수 있습니다. 이 필드는 희소 임베딩에만 사용할 수 있습니다.
    • sparse_embeddings.values의 길이는 sparse_embeddings.dimensions의 길이와 같아야 합니다. 인덱스 생성 시 지정되는 configs.dimensions와 길이가 같을 필요는 없으며 sparse_embeddings에는 적용되지 않습니다.
  • 제한에 TokenNamespace 객체의 배열을 지정하는 선택적 restricts 필드를 포함할 수 있습니다. 각 객체의 대해 다음을 수행합니다.
    • TokenNamespace.namespacenamespace 필드를 지정합니다.
    • 선택적 allow 필드는 TokenNamespace.string_tokens 목록인 문자열 배열로 설정할 수 있습니다.
    • 선택적 deny 필드는 TokenNamespace.string_blacklist_tokens 목록인 문자열 배열로 설정할 수 있습니다.
    • crowding_tag 필드의 값(있는 경우)은 문자열이어야 합니다.
  • NumericRestrictNamespace 배열을 지정하는 선택적 numeric_restricts 필드를 포함할 수 있습니다. 각 객체에 대해 다음을 수행합니다.
    • NumericRestrictNamespace.namespacenamespace 필드를 지정합니다.
    • 값 필드 value_int, value_float, value_double 중 하나
    • 이름이 op인 필드가 없어야 합니다. 이 필드는 쿼리 전용입니다.

Avro

  • 유효한 Avro 파일을 사용합니다.
  • 희소 전용 데이터 포인트를 나타내려면 sparse_embedding 필드에 희소 임베딩을 입력하고 embedding 필드에 빈 목록을 입력합니다.
  • 다음 스키마를 준수하는 레코드를 만듭니다.

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

  • 형식: ID,N feature vector values,Any number of dimension:value sparse values,name=value lists
  • UTF-8을 사용하여 CSV 파일을 인코딩합니다.
  • CSV의 각 행에는 정확히 하나의 레코드가 포함되어야 합니다.
  • 각 행의 첫 번째 값은 벡터 ID(유효한 UTF-8 문자열이어야 함)여야 합니다.
  • ID 뒤에 밀집 임베딩 또는 희소 임베딩 중 하나 이상을 지정해야 합니다.
  • 밀집 임베딩의 경우 다음 N 값은 특성 벡터를 나타내며 여기서 N은 색인이 생성될 때 구성된 특성 벡터의 차원입니다.
  • 희소 임베딩의 경우 dimension:value를 원하는 수만큼 지정할 수 있습니다. 여기서 value는 부동 소수점으로 파싱되고 dimensionlong으로 파싱됩니다.
  • 밀집 임베딩과 희소 임베딩이 모두 있는 하이브리드 임베딩의 경우 밀집 임베딩이 희소 임베딩보다 먼저 지정되어야 합니다.
  • 특성 벡터 값은 자바 언어 사양에 정의된 부동 소수점 리터럴이어야 합니다.
  • 추가 값은 name=value 형식일 수 있습니다.
  • crowding_tag라는 이름은 크라우딩 태그로 해석되며 레코드에 한 번만 표시될 수 있습니다.
  • 다른 모든 name=value 쌍은 토큰 네임스페이스 제한으로 해석됩니다. 네임스페이스에 여러 개의 값이 있는 경우 동일한 이름이 반복될 수 있습니다.

    예를 들어 color=red,color=blue는 이 TokenNamespace를 나타냅니다.

    {
      "namespace": "color"
      "string_tokens": ["red", "blue"]
    }
    
  • 값이 !로 시작하는 경우 문자열의 나머지는 제외된 값으로 해석됩니다.

    예를 들어 color=!red는 이 TokenNamespace를 나타냅니다.

    {
      "namespace": "color"
      "string_blacklist_tokens": ["red"]
    }
    
  • 숫자 유형 서픽스가 있는 #name=numericValue 쌍은 숫자 네임스페이스 제한으로 해석됩니다. 숫자 유형 서픽스는 int의 i, float의 f, double의 d입니다. 네임스페이스마다 값 하나가 연결되어야 하므로 동일한 이름을 반복하면 안 됩니다.

    예를 들어 #size=3i는 이 NumericRestrictNamespace를 나타냅니다.

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

    #ratio=0.1f는 이 NumericRestrictNamespace를 나타냅니다.

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

    #weight=0.3d는 이 NumericRestriction를 나타냅니다.

    {
      "namespace": "weight"
      "value_double": 0.3
    }
    
  • 다음 예시는 id: "6", embedding: [7, -8.1], sparse_embedding: {values: [0.1, -0.2, 0.5], dimensions: [40, 901, 1111]}}, 크라우딩 태그 test, 토큰 허용 목록 color: red, blue, 토큰 차단 목록 color: purple, ratio의 숫자 제한이 부동 소수점 수 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
    

다음 단계