입력 데이터 형식 및 구조

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

기본 요건

입력 데이터를 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 하나가 포함됩니다.
• 다른 모든 하위 디렉터리는 허용되지 않습니다.
• gzip 압축 파일의 트랜스코딩은 입력 데이터로 지원되지 않습니다.

입력 데이터 처리

• 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.csv 및 feature_file_2.csv 파일에는 CSV 형식의 레코드가 포함되어 있습니다. delete_file.txt 파일에는 다음 색인 버전에서 삭제할 레코드 ID 목록이 포함되어 있습니다.

데이터 파일 형식

JSON

• UTF-8을 사용하여 JSON 파일을 인코딩합니다.
• JSON 파일의 각 행은 별도의 JSON 객체로 해석됩니다.
• 각 레코드에는 벡터의 ID를 지정하는 id 필드가 포함되어야 합니다.
• 각 레코드는 embedding 또는 sparse_embedding 중 하나 이상을 포함해야 합니다.
• embedding 필드는 N 부동 소수점 수의 배열로 특성 벡터를 나타냅니다. 여기서 N은 색인이 생성될 때 구성된 특성 벡터의 차원입니다. 이 필드는 밀집 임베딩에만 사용할 수 있습니다.
  • 색인 생성 시 지정되는 configs.dimensions는 embeddings와 길이가 같아야 합니다. configs.dimensions는 sparse_embedding이 아닌 embedding에만 적용됩니다.
• sparse_embedding 필드는 values 및 dimensions 필드가 있는 객체입니다. values 필드는 특성 벡터를 나타내는 부동 소수점 수의 목록이며 dimensions 필드는 해당 값이 위치한 차원을 나타내는 정수 목록입니다. 예를 들어 [0,0.1,0,0,0.2]와 같은 희소 임베딩은 "sparse_embedding": {"values": [0.1, 0.2], "dimensions": [1,4]}와 같이 나타낼 수 있습니다. 이 필드는 희소 임베딩에만 사용할 수 있습니다.
  • sparse_embedding.values의 길이는 sparse_embedding.dimensions의 길이와 같아야 합니다. 인덱스 생성 시 지정되는 configs.dimensions와 길이가 같을 필요는 없으며 sparse_embedding에는 적용되지 않습니다.
• 제한에 TokenNamespace 객체의 배열을 지정하는 선택적 restricts 필드를 포함할 수 있습니다. 각 객체의 대해 다음을 수행합니다.
  • TokenNamespace.namespace인 namespace 필드를 지정합니다.
  • 선택적 allow 필드는 TokenNamespace.string_tokens 목록인 문자열 배열로 설정할 수 있습니다.
  • 선택적 deny 필드는 TokenNamespace.string_blacklist_tokens 목록인 문자열 배열로 설정할 수 있습니다.
  • crowding_tag 필드의 값(있는 경우)은 문자열이어야 합니다.
• NumericRestrictNamespace 배열을 지정하는 선택적 numeric_restricts 필드를 포함할 수 있습니다. 각 객체에 대해 다음을 수행합니다.
  • NumericRestrictNamespace.namespace인 namespace 필드를 지정합니다.
  • 값 필드 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는 부동 소수점으로 파싱되고 dimension은 long으로 파싱됩니다.
• 밀집 임베딩과 희소 임베딩이 모두 있는 하이브리드 임베딩의 경우 밀집 임베딩이 희소 임베딩보다 먼저 지정되어야 합니다.
• 특성 벡터 값은 자바 언어 사양에 정의된 부동 소수점 리터럴이어야 합니다.
• 추가 값은 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
  

다음 단계

• 색인 만들기 및 관리 방법 알아보기