# 벡터 각 벡터는 벡터 인덱스의 각 벡터를 고유하게 식별하는 키로 구성됩니다. 또한 메타데이터(예: 연도, 작성자, 장르, 위치)를 키 값 페어로 각 벡터에 연결할 수 있습니다. 벡터 데이터 작업에는 벡터 삽입, 나열, 쿼리 및 삭제가 포함됩니다. 비정형 데이터의 새 벡터 임베딩을 생성하려면 Amazon Bedrock의 [InvokeModel](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModel.html) API 작업을 사용하여 사용하려는 임베딩 모델의 모델 ID를 지정할 수 있습니다. 또한 오픈 소스 Amazon S3 Vectors Embed CLI 도구는 명령줄에서 임베딩을 생성하고 시맨틱 검색을 수행하는 간소화된 방법을 제공합니다. Amazon Bedrock 파운데이션 모델을 사용한 벡터 임베딩 생성과 S3 벡터 인덱스 내의 시맨틱 검색 작업을 모두 자동화하는 이 오픈 소스 도구에 대한 자세한 내용은 [`s3vectors-embed-cli`를 사용하여 벡터 임베딩 생성 및 시맨틱 검색 수행](s3-vectors-cli.md) 섹션을 참조하세요. ## 벡터 개념 **벡터 키**: 각 벡터는 인덱스 내의 고유한 벡터 키로 식별됩니다. 벡터 키는 최대 1,024자까지 가능하며 벡터 인덱스 내에서 고유해야 합니다. 키는 대/소문자를 구분하며 UTF-8 문자를 포함할 수 있습니다. **벡터 차원**: 차원은 벡터의 값 수입니다. 차원이 클수록 스토리지 공간이 더 많이 필요합니다. 인덱스의 모든 벡터는 인덱스를 생성할 때 지정된 동일한 수의 차원을 가져야 합니다. 차원은 1에서 4,096 사이의 정수여야 합니다. **메타데이터**: 벡터에 메타데이터를 키-값 페어로 연결하여 추가 컨텍스트를 제공하고 쿼리 중에 필터링을 활성화할 수 있습니다. 메타데이터에는 필터링 가능한 메타데이터 키와 필터링 불가능한 메타데이터 키가 모두 포함됩니다. 필터링 가능한 메타데이터는 쿼리 필터링에 사용됩니다. 필터링 불가능한 메타데이터 키는 벡터 인덱스를 만드는 중에 지정되며, 추가 컨텍스트를 제공하지만 필터링에 사용할 수 없습니다. 메타데이터는 문자열, 숫자 및 부울 유형을 지원합니다. 필터링 가능한 메타데이터와 필터링 불가능한 메타데이터에 대한 자세한 내용은 [메타데이터 필터링](s3-vectors-metadata-filtering.md) 섹션을 참조하세요. 벡터당 크기 제한 및 벡터당 최대 메타데이터 키를 포함한 메타데이터 제한에 대한 자세한 내용은 [한계 및 제한](s3-vectors-limitations.md)을 참조하세요. **Topics** + [벡터 개념](#s3-vectors-concepts) + [벡터 인덱스에 벡터 삽입](s3-vectors-index-create.md) + [벡터 나열](s3-vectors-list.md) + [벡터 쿼리](s3-vectors-query.md) + [벡터 인덱스에서 벡터 삭제](s3-vectors-delete.md) + [메타데이터 필터링](s3-vectors-metadata-filtering.md) # 벡터 인덱스에 벡터 삽입 [PutVectors](https://docs.aws.amazon.com/AmazonS3/latest/API/API_S3VectorBuckets_PutVectors.html) API 작업을 사용하여 벡터 인덱스에 벡터를 추가할 수 있습니다. 각 벡터는 벡터 인덱스의 각 벡터를 고유하게 식별하는 키로 구성됩니다. 인덱스에 이미 있는 키로 벡터를 배치하면 기존 벡터를 완전히 덮어쓰므로 이전 벡터를 더 이상 검색할 수 없습니다. 쓰기 처리량을 극대화하고 비용을 최적화하려면 벡터를 `PutVectors`에 대한 최대 배치 크기까지 대량 배치로 삽입하는 것이 좋습니다. 그러나 라이브와 같이 더 작은 배치를 사용해야 하는 워크로드의 경우 수신 벡터 데이터를 즉시 검색할 수 있어야 합니다. 더 많은 수의 동시 `PutVectors` 요청을 초당 허용되는 최대 요청 한도까지 사용하여 쓰기 처리량을 높일 수 있습니다. `PutVectors` API 직접 호출당 벡터의 제한인 `PutVectors`의 최대 배치 크기와 최대 요청 및 초당 벡터 제한에 대한 자세한 내용은 [한계 및 제한](s3-vectors-limitations.md) 섹션을 참조하세요. 또한 메타데이터(예: 연도, 작성자, 장르, 위치)를 키-값 페어로 각 벡터에 연결할 수 있습니다. 기본적으로 벡터에 연결된 모든 메타데이터 키는 필터링이 가능하며, 유사성 쿼리에서 필터로 사용할 수 있습니다. 벡터 인덱스 만들기 중에 필터링 불가능한 것으로 지정된 메타데이터 키만 필터링에서 제외됩니다. S3 벡터 인덱스는 문자열, 숫자, 부울 및 목록 유형의 메타데이터를 지원합니다. 벡터당 총 메타데이터 크기 제한 및 벡터당 필터링 가능한 메타데이터 크기 제한에 대한 자세한 내용은 [한계 및 제한](s3-vectors-limitations.md) 섹션을 참조하세요. 메타데이터 크기가 이러한 제한을 초과하면 `PutVectors` API 작업에서 `400 Bad Request` 오류가 반환됩니다. `PutVectors` API 작업을 사용하여 벡터 인덱스에 벡터 데이터를 추가하기 전에 원시 데이터를 부동 소수점 숫자의 배열로 콘텐츠를 숫자로 표현한 벡터 임베딩으로 변환해야 합니다. 벡터 임베딩은 콘텐츠의 시맨틱 의미를 캡처하여 `PutVectors` 작업을 통해 벡터 인덱스에 저장된 유사성 검색을 가능하게 합니다. 데이터 유형 및 사용 사례에 따라 다양한 방법을 사용하여 벡터 임베딩을 생성할 수 있습니다. 이러한 방법에는 기계 학습 프레임워크, 특수 임베딩 라이브러리 또는 Amazon Bedrock과 같은 AWS 서비스 사용이 포함됩니다. 예를 들어 Amazon Bedrock을 사용하는 경우 [InvokeModel](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModel.html) API 작업 및 선호하는 임베딩 모델을 사용하여 임베딩을 생성할 수 있습니다. 또한 Amazon Bedrock 지식 기반은 Amazon Bedrock이 S3 데이터 소스에서 데이터를 자동으로 가져오고, 콘텐츠를 텍스트 블록으로 변환하고, 임베딩을 생성하고, 벡터 인덱스에 저장하는 포괄적인 완전관리형 RAG 워크플로를 제공합니다. 그런 다음 지식 기반을 쿼리하고 소스 데이터에서 검색된 청크를 기반으로 응답을 생성할 수 있습니다. 또한 오픈 소스 Amazon S3 Vectors Embed CLI 도구는 명령줄에서 임베딩을 생성하고 시맨틱 검색을 수행하는 간소화된 방법을 제공합니다. Amazon Bedrock 파운데이션 모델을 사용한 벡터 임베딩 생성과 S3 벡터 인덱스 내의 시맨틱 검색 작업을 모두 자동화하는 이 오픈 소스 도구에 대한 자세한 내용은 [`s3vectors-embed-cli`를 사용하여 벡터 임베딩 생성 및 시맨틱 검색 수행](s3-vectors-cli.md) 섹션을 참조하세요. **참고** 벡터 데이터를 벡터 인덱스에 삽입할 때 벡터 데이터를 `float32`(32비트 부동 소수점) 값으로 제공해야 합니다. 더 높은 정밀도 값을 AWS SDK에 전달하면 S3 Vectors는 값을 저장하기 전에 값을 32비트 부동 소수점으로 변환하고 [GetVectors](https://docs.aws.amazon.com/AmazonS3/latest/API/API_S3VectorBuckets_GetVectors.html), [ListVectors](https://docs.aws.amazon.com/AmazonS3/latest/API/API_S3VectorBuckets_ListVectors.html) 및 [QueryVectors](https://docs.aws.amazon.com/AmazonS3/latest/API/API_S3VectorBuckets_QueryVectors.html) 작업은 `float32` 값을 반환합니다. AWS SDKs마다 기본 숫자 유형이 다를 수 있으므로 사용 중인 SDK에 관계없이 벡터에 `float32` 형식이 올바르게 지정되었는지 확인합니다. 예를 들어 Python에서 `numpy.float32`를 사용하거나 값을 명시적으로 캐스팅합니다. ## AWS SDK 사용 ------ #### [ SDK for Python ] ``` # Populate a vector index with embeddings from Amazon Titan Text Embeddings V2. import boto3 import json # Create Bedrock Runtime and S3 Vectors clients in the AWS Region of your choice. bedrock = boto3.client("bedrock-runtime", region_name="us-west-2") s3vectors = boto3.client("s3vectors", region_name="us-west-2") # Texts to convert to embeddings. texts = [ "Star Wars: A farm boy joins rebels to fight an evil empire in space", "Jurassic Park: Scientists create dinosaurs in a theme park that goes wrong", "Finding Nemo: A father fish searches the ocean to find his lost son" ] # Generate vector embeddings. embeddings = [] for text in texts: response = bedrock.invoke_model( modelId="amazon.titan-embed-text-v2:0", body=json.dumps({"inputText": text}) ) # Extract embedding from response. response_body = json.loads(response["body"].read()) embeddings.append(response_body["embedding"]) # Write embeddings into vector index with metadata. s3vectors.put_vectors( vectorBucketName="media-embeddings", indexName="movies", vectors=[ { "key": "Star Wars", "data": {"float32": embeddings[0]}, "metadata": {"source_text": texts[0], "genre":"scifi"} }, { "key": "Jurassic Park", "data": {"float32": embeddings[1]}, "metadata": {"source_text": texts[1], "genre":"scifi"} }, { "key": "Finding Nemo", "data": {"float32": embeddings[2]}, "metadata": {"source_text": texts[2], "genre":"family"} } ] ) ``` ------ # 벡터 나열 [ListVectors](https://docs.aws.amazon.com/AmazonS3/latest/API/API_S3VectorBuckets_ListVectors.html) API 작업을 사용하여 벡터 인덱스에 벡터를 나열할 수 있습니다. 페이지당 반환할 수 있는 최대 벡터 수에 대한 자세한 내용은 [한계 및 제한](s3-vectors-limitations.md) 섹션을 참조하세요. 응답에는 결과가 잘릴 때 페이지 매김 토큰이 포함됩니다. `ListVectors`의 응답 요소에 대한 자세한 내용은 *Amazon S3 API 참조*의 [ListVectors](https://docs.aws.amazon.com/AmazonS3/latest/API/API_S3VectorBuckets_ListVectors)를 참조하세요. `ListVectors`를 사용하여 지정된 벡터 인덱스에서 벡터 데이터를 내보낼 수도 있습니다. `ListVectors`는 강력히 일관됩니다. WRITE 작업 후 모든 변경 사항이 반영된 벡터를 즉시 나열할 수 있습니다. ## AWS CLI 사용 벡터를 나열하려면 다음 예제 명령을 사용합니다. *user input placeholders*를 사용자의 정보로 대체합니다. `segment-count` 및 `segment-index` 파라미터를 사용하면 여러 병렬 요청에서 나열 작업을 파티셔닝할 수 있습니다. `segment-count` 값(예: `2`)을 지정할 때 인덱스를 여러 세그먼트로 나눕니다. `segment-index` 파라미터(0부터 시작)에 따라 나열할 세그먼트가 결정됩니다. 이 접근 방식은 병렬 처리를 활성화하여 큰 벡터 인덱스를 나열할 때 성능을 개선하는 데 도움이 됩니다. `segment-count` 및 `segment-index`에 대한 자세한 내용은 *Amazon S3 API 참조*의 [ListVectors](https://docs.aws.amazon.com/AmazonS3/latest/API/API_S3VectorBuckets_ListVectors)를 참조하세요. **인덱스의 모든 벡터 나열** 요청 예제: ``` aws s3vectors list-vectors \ --vector-bucket-name "amzn-s3-demo-vector-bucket" \ --index-name "idx" \ --segment-count 2 \ --segment-index 0 \ --return-data \ --return-metadata ``` 응답 예제: ``` { "vectors": [ { "key": "vec3", "data": { "float32": [0.4000000059604645] }, "metadata": { "nonFilterableKey": "val4", "filterableKey": "val2" } } ] } ``` **페이지 매김이 있는 벡터 나열** 요청 예제: ``` aws s3vectors list-vectors \ --vector-bucket-name "amzn-s3-demo-vector-bucket" \ --index-name "idx" \ --segment-count 2 \ --segment-index 0 \ --return-data \ --return-metadata \ --next-token "zWfh7e57H2jBfBtRRmC7OfMwl209G9dg3j2qM6kM4t0rps6ClYzJykgMOil9eGqU5nhf_gTq53IfoUdTnsg" ``` 응답 예제: ``` { "vectors": [ { "key": "vec1", "data": { "float32": [0.5] }, "metadata": { "nonFilterableKey": "val2", "filterableKey": "val1" } } ] } ``` ## AWS SDK 사용 ------ #### [ SDK for Python ] 예: 벡터 인덱스에 벡터 나열 ``` import boto3 # Create a S3 Vectors client in the AWS Region of your choice. s3vectors = boto3.client("s3vectors", region_name="us-west-2") #List vectors in your vector index response = s3vectors.list_vectors( vectorBucketName="media-embeddings", indexName="movies", maxResults = 600, returnData = True, returnMetadata = True ) vectors = response["vectors"] print(vectors) ``` 예: 벡터 인덱스의 모든 벡터를 병렬로 나열 ``` import boto3 # Create a S3 Vectors client in the AWS Region of your choice. s3vectors = boto3.client("s3vectors", region_name="us-west-2") #List vectors in the 1st half of vectors in the index. response = s3vectors.list_vectors( vectorBucketName="media-embeddings", indexName="movies", segmentCount=2, segmentIndex=1, maxResults = 600, returnData = True, returnMetadata = True ) vectors = response["vectors"] #List vectors starting from the 2nd half of vectors in the index. # This can be ran in parallel with the first `list_vectors` call. response = s3vectors.list_vectors( vectorBucketName="media-embeddings", indexName="movies", segmentCount=2, segmentIndex=1, maxResults = 600, returnData = True, returnMetadata = True ) vectors = response["vectors"] print(vectors) ``` ------ # 벡터 쿼리 쿼리 벡터, 반환할 관련 결과 수(가장 가까운 Top K 근사치), 인덱스 ARN을 지정하는 [QueryVectors](https://docs.aws.amazon.com/AmazonS3/latest/API/API_S3VectorBuckets_QueryVectors.html) API 작업을 사용하여 유사성 쿼리를 실행할 수 있습니다. 또한 쿼리에서 메타데이터 필터를 사용하여 필터와 일치하는 벡터만 검색할 수 있습니다. 필터링 불가능한 메타데이터 필드를 기준으로 필터링하도록 요청하면 요청이 `400 Bad Request` 오류를 반환합니다. 메타데이터 필터링에 대한 자세한 내용은 [메타데이터 필터링](s3-vectors-metadata-filtering.md) 섹션을 참조하세요. 응답에서 벡터 키는 기본적으로 반환됩니다. 필요에 따라 응답에 거리와 메타데이터를 포함할 수 있습니다. 쿼리 벡터를 생성할 때 벡터 인덱스에 저장된 초기 벡터를 생성하는 데 사용된 것과 동일한 벡터 임베딩 모델을 사용해야 합니다. 예를 들어 Amazon Bedrock에서 Amazon Titan Text Embeddings V2 모델을 사용하여 문서의 벡터 임베딩을 만드는 경우 동일한 임베딩 모델을 사용하여 질문을 쿼리 벡터로 변환합니다. 또한 Amazon Bedrock 지식 기반은 Amazon Bedrock이 S3 데이터 소스에서 데이터를 자동으로 가져오고, 콘텐츠를 텍스트 블록으로 변환하고, 임베딩을 생성하고, 벡터 인덱스에 저장하는 포괄적인 완전관리형 RAG 워크플로를 제공합니다. 그런 다음 지식 기반을 쿼리하고 소스 데이터에서 검색된 청크를 기반으로 응답을 생성할 수 있습니다. 콘솔의 Amazon Bedrock 지식 기반에서 벡터를 쿼리하는 방법에 대한 자세한 내용은 [(선택 사항) S3 Vectors를 Amazon Bedrock 지식 기반과 통합](s3-vectors-getting-started.md#s3-vectors-bedrock-kb-tutorial) 섹션을 참조하세요. 또한 오픈 소스 Amazon S3 Vectors Embed CLI 도구는 명령줄에서 시맨틱 검색을 수행하는 간소화된 방법을 제공합니다. 이 오픈 소스 도구는 Amazon Bedrock 파운데이션 모델을 사용하여 벡터 임베딩 생성을 처리하고 S3 벡터 인덱스에 대해 시맨틱 검색 작업을 실행하여 쿼리 프로세스를 간소화합니다. 이 도구를 사용하여 벡터 데이터를 쿼리하는 방법에 대한 자세한 내용은 [`s3vectors-embed-cli`를 사용하여 벡터 임베딩 생성 및 시맨틱 검색 수행](s3-vectors-cli.md) 섹션을 참조하세요. S3 Vectors는 콜드 쿼리에 대해 1초 미만의 응답 시간을 제공하여 Amazon S3 탄력적 처리량을 활용하여 수백만 개의 벡터를 효율적으로 검색합니다. 따라서 쿼리 빈도가 낮은 워크로드에 매우 비용 효율적입니다. 웜 쿼리의 경우 S3 Vectors는 최소 100ms의 응답 시간을 제공할 수 있으므로 반복되거나 빈번한 쿼리 패턴이 있는 워크로드에 도움이 됩니다. 벡터 임베딩에 대한 유사성 쿼리를 수행하려면 벡터 임베딩 모델, 벡터 데이터세트 크기(벡터 및 차원 수), 쿼리 분포 등 몇 가지 요인이 평균 재현율 성능에 영향을 미칠 수 있습니다. S3 Vectors는 대부분의 데이터세트에 대해 90% 이상의 평균 재현율을 제공합니다. 평균 재현율은 쿼리 결과의 품질을 측정합니다. 평균 재현율 90%는 응답에 쿼리 벡터를 기준으로 벡터 인덱스에 저장된 실제 가장 가까운 벡터(실측 정보)의 90%가 포함되어 있음을 의미합니다. 그러나 실제 성능은 특정 사용 사례에 따라 다를 수 있으므로 대표 데이터 및 쿼리를 사용하여 자체 테스트를 수행함으로써 S3 Vectors가 재현 요구 사항을 충족하는지 검증하는 것이 좋습니다. ## AWS SDK 사용 ------ #### [ SDK for Python ] ``` # Query a vector index with an embedding from Amazon Titan Text Embeddings V2. import boto3 import json # Create Bedrock Runtime and S3 Vectors clients in the AWS Region of your choice. bedrock = boto3.client("bedrock-runtime", region_name="us-west-2") s3vectors = boto3.client("s3vectors", region_name="us-west-2") # Query text to convert to an embedding. input_text = "adventures in space" # Generate the vector embedding. response = bedrock.invoke_model( modelId="amazon.titan-embed-text-v2:0", body=json.dumps({"inputText": input_text}) ) # Extract embedding from response. model_response = json.loads(response["body"].read()) embedding = model_response["embedding"] # Query vector index. response = s3vectors.query_vectors( vectorBucketName="media-embeddings", indexName="movies", queryVector={"float32": embedding}, topK=3, returnDistance=True, returnMetadata=True ) print(json.dumps(response["vectors"], indent=2)) # Query vector index with a metadata filter. response = s3vectors.query_vectors( vectorBucketName="media-embeddings", indexName="movies", queryVector={"float32": embedding}, topK=3, filter={"genre": "scifi"}, returnDistance=True, returnMetadata=True ) print(json.dumps(response["vectors"], indent=2)) ``` ------ # 벡터 인덱스에서 벡터 삭제 [DeleteVectors](https://docs.aws.amazon.com/AmazonS3/latest/API/API_S3VectorBuckets_DeleteVectors.html) API를 사용해 벡터 키를 지정하여 벡터 인덱스에서 특정 벡터를 삭제할 수 있습니다. 이 작업은 나머지 벡터 데이터를 보존하면서 오래된 데이터나 잘못된 데이터를 제거하는 데 유용합니다. ## AWS CLI 사용 벡터를 삭제하려면 다음 예제 명령을 사용합니다. *user input placeholders*를 사용자의 정보로 대체합니다. ``` aws s3vectors delete-vectors \ --vector-bucket-name "amzn-s3-demo-vector-bucket" \ --index-name "idx" \ --keys '["vec2","vec3"]' ``` ## AWS SDK 사용 ------ #### [ SDK for Python ] ``` import boto3 # Create a S3 Vectors client in the AWS Region of your choice. s3vectors = boto3.client("s3vectors", region_name="us-west-2") #Delete vectors in a vector index response = s3vectors.delete_vectors( vectorBucketName="media-embeddings", indexName="movies", keys=["Star Wars", "Finding Nemo"]) ``` ------ # 메타데이터 필터링 메타데이터 필터링을 사용하면 벡터에 연결된 특정 속성을 기반으로 쿼리 결과를 필터링할 수 있습니다. 쿼리 작업과 함께 메타데이터 필터를 사용하여 유사성 기준 및 특정 메타데이터 조건과 모두 일치하는 벡터를 찾을 수 있습니다. S3 Vectors는 필터링 가능한 메타데이터와 필터링 불가능한 메타데이터라는 두 가지 유형의 메타데이터를 지원합니다. 주요 차이점은 필터링 가능한 메타데이터는 쿼리 필터에 사용할 수 있지만 크기 제한이 더 엄격한 반면, 필터링 불가능한 메타데이터는 필터에 사용할 수 없지만 크기 제한 내에 더 많은 양의 데이터를 저장할 수 있다는 것입니다. 벡터당 크기 제한 및 벡터당 최대 메타데이터 키를 포함하여 메타데이터 제한에 대한 자세한 내용은 [한계 및 제한](s3-vectors-limitations.md) 섹션을 참조하세요. S3 Vectors는 벡터 검색과 필터 평가를 동시에 수행합니다. S3 Vectors는 인덱스의 후보 벡터를 검색하여 유사한 상위 K개 벡터를 찾는 동시에 각 후보 벡터가 메타데이터 필터 조건과 일치하는지 검증합니다. 예를 들어 유사한 영화 임베딩을 검색하고 genre='mystery'로 필터링하면 S3 Vectors는 장르 메타데이터가 'mystery'와 일치하는 유사한 영화 임베딩만 반환합니다. 벡터 검색 후 메타데이터 필터를 적용하는 것과 달리 이 필터링 방식은 일치하는 결과를 찾을 가능성이 더 높습니다. 참고: 벡터 인덱스에 일치하는 결과가 매우 적은 경우 필터가 있는 쿼리는 상위 K개보다 적은 결과를 반환할 수 있습니다. **Topics** + [필터링 가능한 메타데이터](#s3-vectors-metadata-filtering-filterable) + [필터링 가능한 유효한 메타데이터의 예](#s3-vectors-metadata-filtering-examples) + [필터링 불가능한 메타데이터 키](#s3-vectors-metadata-filtering-non-filterable) ## 필터링 가능한 메타데이터 필터링 가능한 메타데이터를 사용하면 특정 메타데이터 값을 기반으로 쿼리 결과를 필터링할 수 있습니다. 기본적으로 모든 메타데이터 필드는 벡터 인덱스를 만드는 중에 필터링 불가능한 것으로 명시적으로 지정되지 않는 한 유사성 쿼리에서 필터링할 수 있습니다. S3 Vectors는 벡터당 크기 제한이 있는 메타데이터의 문자열, 숫자, 부울 및 목록 유형을 지원합니다. 메타데이터 유형은 범주, 타임스탬프 또는 상태 값과 같이 필터링 기준으로 사용하려는 속성에 적합합니다. 메타데이터 크기가 지원되는 제한을 초과하면 [PutVectors](https://docs.aws.amazon.com/AmazonS3/latest/API/API_S3VectorBuckets_PutVectors.html) API 작업이 `400 Bad Request` 오류를 반환합니다. 벡터당 필터링 가능한 메타데이터 크기 제한에 대한 자세한 내용은 [한계 및 제한](s3-vectors-limitations.md) 섹션을 참조하세요. 다음 작업은 필터링 가능한 메타데이터와 함께 사용할 수 있습니다. | 연산자 | 유효한 입력 유형 | 설명 | | --- | --- | --- | | \$1eq | 문자열, 숫자, 부울 | 단일 값에 대한 정확한 일치 비교입니다.배열 메타데이터 값과 비교할 때 입력 값이 배열의 요소와 일치하면 true를 반환합니다. 예를 들어 `{"category": {"$eq": "documentary"}}`는 벡터를 `"category": ["documentary", "romance"]` 메타데이터와 일치시킵니다. | | \$1ne | 문자열, 숫자, 부울 | 같지 않음 비교 | | \$1gt | 숫자 | 초과 비교 | | \$1gte | 숫자 | 초과 또는 같음 비교 | | \$1lt | 숫자 | 미만 비교 | | \$1lte | 숫자 | 미만 또는 같음 비교 | | \$1in | 비어 있지 않은 프리미티브 배열 | 배열의 값 중 하나 이상과 일치 | | \$1nin | 비어 있지 않은 프리미티브 배열 | 배열의 값과 일치하지 않음 | | \$1exists | 부울 | 필드가 존재하는지 확인 | | \$1and | 비어 있지 않은 필터 배열 | 여러 조건의 논리적 AND | | \$1or | 비어 있지 않은 필터 배열 | 여러 조건의 논리적 OR | ## 필터링 가능한 유효한 메타데이터의 예 **단순 동등성** ``` {"genre": "documentary"} ``` 이 필터는 장르 메타데이터 키가 ‘documentary’와 같은 벡터와 일치합니다. 연산자를 지정하지 않으면 S3 Vectors는 \$1eq 연산자를 자동으로 사용합니다. **명시적 동등성** ``` // Example: Exact match {"genre": {"$eq": "documentary"}} ``` ``` // Example: Not equal to {"genre": {"$ne": "drama"}} ``` **숫자 비교** ``` {"year": {"$gt": 2019}} ``` ``` {"year": {"$gte": 2020}} ``` ``` {"year": {"$lt": 2020}} ``` ``` {"year": {"$lte": 2020}} ``` **배열 연산자** ``` {"genre": {"$in": ["comedy", "documentary"]}} ``` ``` {"genre": {"$nin": ["comedy", "documentary"]}} ``` **존재 확인** ``` {"genre": {"$exists": true}} ``` `$exists` 필터는 해당 메타데이터 키에 대해 저장된 값에 관계없이 ‘genre’ 메타데이터 키가 있는 벡터와 일치합니다. **논리 연산자** ``` {"$and": [{"genre": {"$eq": "drama"}}, {"year": {"$gte": 2020}}]} ``` ``` {"$or": [{"genre": {"$eq": "drama"}}, {"year": {"$gte": 2020}}]} ``` **가격 범위(동일한 필드의 여러 조건)** ``` {"price": {"$gte": 10, "$lte": 50}} ``` 메타데이터 필터링을 사용하여 벡터를 쿼리하는 방법에 대한 자세한 내용은 [메타데이터 필터링](s3-vectors.md#s3-vectors-filtering-metadata) 섹션을 참조하세요. ## 필터링 불가능한 메타데이터 키 필터링 불가능한 메타데이터는 쿼리 필터에 사용할 수 없지만 필터링 가능한 메타데이터보다 많은 양의 컨텍스트 데이터를 저장할 수 있습니다. 검색할 필요는 없지만 쿼리 결과와 함께 반환할 수 있는 큰 텍스트 청크, 자세한 설명 또는 기타 컨텍스트 정보를 저장하는 데 적합합니다. 예를 들어 전체 문서 텍스트, 이미지 설명 또는 자세한 제품 사양을 필터링 불가능한 메타데이터로 저장할 수 있습니다. 필터링 불가능한 메타데이터 키는 벡터 인덱스 생성 중에 명시적으로 구성해야 합니다. 메타데이터 키가 인덱스 생성 중에 필터링 불가능으로 지정되면 나중에 필터링 가능으로 변경할 수 없습니다. 여러 메타데이터 키를 벡터 인덱스당 필터링 불가능한 것으로 구성할 수 있으며, 각 메타데이터 키 이름은 63자로 제한됩니다. 벡터 인덱스당 허용되는 필터링 불가능한 메타데이터 키의 최대 수에 대한 자세한 내용은 [한계 및 제한](s3-vectors-limitations.md) 섹션을 참조하세요. 필터링 불가능한 메타데이터는 필터링할 수 없지만 `return-metadata` 파라미터를 사용하여 쿼리 결과와 함께 검색할 수 있습니다. 다음과 같이 일부 사용 사례에 필터링 불가능한 메타데이터를 사용할 수 있습니다. + 별도의 데이터 소스를 구문 분석하지 않고 애플리케이션에 컨텍스트를 제공하는 데 사용합니다. + 필터링 가능한 메타데이터 크기 제한을 초과하는 더 큰 텍스트 청크를 저장합니다. + [ListVectors](https://docs.aws.amazon.com/AmazonS3/latest/API/API_S3VectorBuckets_ListVectors.html) API 작업을 사용하여 벡터 내보내기에 포함합니다. 필터링 불가능한 메타데이터 구성에 대한 자세한 내용은 [벡터 버킷에서 벡터 인덱스 만들기](s3-vectors-create-index.md) 섹션을 참조하세요.