입력 데이터 형식 및 구조

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

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

기본 요건

입력 데이터를 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는 다음 색인 버전에서 삭제됩니다.
일반 데이터 파일의 레코드가 다음 버전에 포함되며 이전 색인 버전의 값을 덮어씁니다.

다음은 JSON 예시입니다.

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

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

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 필드가 포함되어야 합니다.
각 레코드에는 특성 벡터를 나타내는 N 부동 소수점 숫자의 배열인 embedding 필드가 포함되어야 합니다. 여기서 N은 색인을 만들 때 구성된 특성 벡터의 차원입니다.
제한에 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 파일을 사용합니다.

다음 스키마를 준수하는 레코드를 만듭니다.

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

UTF-8을 사용하여 CSV 파일을 인코딩합니다.
CSV의 각 줄에는 정확히 하나의 레코드가 포함되어야 합니다.
각 행의 첫 번째 값은 벡터 ID(유효한 UTF-8 문자열이어야 함)여야 합니다.
ID 뒤의 다음 N 값은 특징 벡터를 나타내며 여기서 N은 색인이 생성될 때 구성된 특성 벡터의 차원입니다.
특성 벡터 값은 자바 언어 사양에 정의된 부동 소수점 리터럴이어야 합니다.
추가 값은 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
}
```

다음 단계

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