# 向量 每个向量都由一个键组成，该键唯一标识向量索引中的每个向量。此外，可以将元数据（例如年份、作者、流派、地点）作为键值对附加到每个向量。 向量数据操作包括插入、列出、查询和删除向量。要生成非结构化数据的新向量嵌入，可以使用 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)。 ## 向量概念 **向量键**：每个向量都由索引中的唯一向量键标识。向量键最多可包含 1024 个字符，并且向量索引中必须是唯一的。键区分大小写，并可以包含任何 UTF-8 字符。 **向量维度**：维度是向量中值的数量。维度越大，需要的存储空间越多。索引中的所有向量必须具有相同数量的维度，这是在创建索引时指定的。维度必须是 1 和 4096 之间的整数。 **元数据**：可以将元数据作为键值对附加到向量，以提供其它上下文并在查询期间启用筛选。元数据同时包括可筛选和不可筛选的元数据键。可筛选的元数据用于查询筛选。不可筛选的元数据键是在创建向量索引时指定的，可提供其它上下文，但不能用于筛选。元数据支持字符串、数字和布尔值类型。有关可筛选和不可筛选的元数据的更多信息，请参阅[元数据筛选](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` 的最大批量大小（即每次 `PutVectors` API 调用的向量数限制）的更多信息，请参阅[限制和局限性](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 知识库提供一个完全托管式的端到端 RAG 工作流程，其中 Amazon Bedrock 自动从 S3 数据来源获取数据、将内容转换为文本块、生成嵌入并将其存储在向量索引中。然后，可以查询知识库，并根据从源数据中检索的分块生成响应。 此外，开源 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 SDK 可能具有不同的默认数值类型，因此，无论使用哪个 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 Reference》**中的 [ListVectors](https://docs.aws.amazon.com/AmazonS3/latest/API/API_S3VectorBuckets_ListVectors)。也可以使用 `ListVectors` 从指定的向量索引导出向量数据。`ListVectors` 为强一致性。执行 WRITE 操作后，可以立即列出反映了所有变化的向量。 ## 使用 AWS CLI 要列出向量，请使用以下示例命令。将*用户输入占位符*替换为您自己的信息。 `segment-count` 和 `segment-index` 参数支持您跨多个并行请求对列出操作进行分区。指定 `segment-count` 值（例如 `2`）时，可以将索引划分为许多分段。`segment-index` 参数（从 0 开始）决定要列出哪个分段。这种方法通过启用并行处理来协助提高列出大型向量索引时的性能。有关 `segment-count` 和 `segment-index` 的更多信息，请参阅《Amazon S3 API Reference》**中的 [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) ``` ------ # 查询向量 查询向量 可以使用 [QueryVectors](https://docs.aws.amazon.com/AmazonS3/latest/API/API_S3VectorBuckets_QueryVectors.html) API 操作运行相似性查询，其中，您可以指定查询向量、要返回的相关结果数（前 K 个最近邻居）和索引 ARN。此外，可以在查询中使用元数据筛选条件，以便仅搜索与筛选条件匹配的向量。如果您发出请求来对不可筛选的元数据字段进行筛选，则该请求将返回 `400 Bad Request` 错误。有关元数据筛选的更多信息，请参阅[元数据筛选](s3-vectors-metadata-filtering.md)。 在响应中，默认情况下返回向量键。可以选择在响应中包含距离和元数据。 生成查询向量时，所使用的向量嵌入模型应与生成存储在向量索引中的初始向量所用的模型相同。例如，如果您使用 Amazon Bedrock 中的 Amazon Titan 文本嵌入 V2 模型来生成文档的向量嵌入，请使用相同的嵌入模型将问题转换为查询向量。此外，Amazon Bedrock 知识库提供一个完全托管式的端到端 RAG 工作流程，其中 Amazon Bedrock 自动从 S3 数据来源获取数据、将内容转换为文本块、生成嵌入并将其存储在向量索引中。然后，可以查询知识库，并根据从源数据中检索的分块生成响应。有关在控制台中如何从 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 利用 Amazon S3 的弹性吞吐量在数百万个向量中高效搜索，从而实现亚秒级冷查询响应时间。因此，它对查询频率较低的工作负载极具成本效益。对于热查询，S3 Vectors 的响应时间可低至 100 ms，尤其适合具有重复或频繁查询模式的工作负载。 要对向量嵌入执行相似性查询，有几个因素可能会影响平均召回性能，包括向量嵌入模型、向量数据集的大小（向量和维度的数量）以及查询的分布。对于大多数数据集，S3 Vectors 的平均召回率为 90%\$1。平均召回率衡量查询结果的质量。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 要删除向量索引，请使用以下示例命令。将*用户输入占位符*替换为您自己的信息。 ``` 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 仅返回 genre 元数据与“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"} ``` 此筛选条件匹配 genre 元数据键等于“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)。