입력 데이터 형식 및 구조

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

입력 데이터 저장소 및 파일 구성

기본 요건

입력 데이터를 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.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
  

다음 단계

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