创建和搜索向量索引

本节介绍如何创建和管理向量索引、写入带有向量数据的项目以及使用 SearchVectors API 执行相似性搜索。

开始前的准备工作

在使用向量索引之前，请验证以下事项：

SearchVectors 端点

SearchVectors 请求使用专用的向量搜索端点，这些端点不同于您用来创建和管理向量索引的标准 DynamoDB 端点（例如，使用 CreateTable、UpdateTable 和 DescribeTable）。AWS SDK 和 AWS CLI 自动将 SearchVectors 请求路由到正确的端点。您无需在应用程序代码中配置或覆盖端点。

如果您正在构建一个直接调用 DynamoDB API 的自定义 HTTP 客户端，且不使用 AWS SDK，请使用以下向量搜索端点之一，并根据实际情况替换 account-id 和 region：

生成向量嵌入

DynamoDB 存储和搜索向量嵌入，但不会生成它们。您可以使用 Amazon Bedrock Titan Text Embeddings 模型或 Cohere Embed 模型等嵌入模型生成嵌入，也可以通过您使用的任何嵌入模型生成嵌入。然后将生成的向量存储在 DynamoDB 项目中，并将查询向量传递给 SearchVectors。

典型的流程是：

您选择的距离函数与模型生成嵌入的方式相互作用。COSINE 比较方向并忽略模长，因此无论嵌入是否标准化，它都可以处理嵌入。DOT_PRODUCT 区分模长：如果您的嵌入没有标准化为单位长度，那么无论方向如何，较大的向量始终会获得更高的分数。如果您使用 DOT_PRODUCT 并想要基于方向的相似性，请在存储嵌入之前将其标准化为单位长度。请参阅距离函数如何排名结果。

创建向量索引

您可以在创建新表时创建向量索引，也可以向现有表添加向量索引。

创建带有向量索引的表

使用 CreateTable API 和 VectorIndexes 参数来创建带有向量索引的表。以下 AWS CLI 示例创建一个 Products 表并带有名为 ProductEmbeddingIndex 的向量索引。

aws dynamodb create-table \
    --table-name Products \
    --attribute-definitions AttributeName=ProductId,AttributeType=S \
                            AttributeName=Category,AttributeType=S \
                            AttributeName=Brand,AttributeType=S \
    --key-schema AttributeName=ProductId,KeyType=HASH \
    --billing-mode PAY_PER_REQUEST \
    --vector-indexes \
        "[
            {
                \"IndexName\": \"ProductEmbeddingIndex\",
                \"VectorAttribute\": {\"AttributeName\": \"Embedding\"},
                \"SearchSchema\": [{\"AttributeName\":\"Category\",\"SearchSchemaElementType\":\"HASH\"},
                                  {\"AttributeName\":\"Brand\",\"SearchSchemaElementType\":\"INLINE_FILTER\"}],
                \"Projection\": {\"ProjectionType\": \"ALL\"},
                \"Dimensions\": 1536,
                \"DistanceFunction\": \"COSINE\"
            }
        ]"

在本示例中：

将向量索引添加到现有表

使用 UpdateTable API 和 VectorIndexUpdates 参数向现有表添加向量索引。此示例将名为 ProductEmbeddingIndexV2 的第二个独立索引添加到同一个 Products 表中。

aws dynamodb update-table \
    --table-name Products \
    --vector-index-updates \
        "[
            {
                \"Create\": {
                    \"IndexName\": \"ProductEmbeddingIndexV2\",
                    \"VectorAttribute\": {\"AttributeName\": \"Embedding\"},
                    \"Projection\": {\"ProjectionType\": \"ALL\"},
                    \"Dimensions\": 1536,
                    \"DistanceFunction\": \"EUCLIDEAN\"
                }
            }
        ]"

向现有表添加向量索引时，DynamoDB 会在 DescribeTable 响应中通过两个字段报告索引进度：IndexStatus 值和单独的 Backfilling 布尔值。

写入带有向量数据的项目

您可以使用标准 DynamoDB 写入 API（PutItem、UpdateItem、BatchWriteItem、TransactWriteItems），写入带有向量数据的项目。将向量嵌入存储为数字列表（包含 N 元素的 L 类型）。

由于向量包含许多值，因此请将项目保存到文件中（例如 item.json），然后将文件传递给 AWS CLI。

{
    "ProductId": { "S": "prod-123" },
    "Category": { "S": "Electronics" },
    "Title": { "S": "Wireless Headphones" },
    "Embedding": {
        "L": [
            { "N": "0.1234" },
            { "N": "-0.5678" },
            { "N": "0.9012" },
            ...
        ]
    }
}

aws dynamodb put-item \
    --table-name Products \
    --item file://item.json

当您将项目写入具有向量索引的表时，DynamoDB 会验证向量数据。下表描述了验证行为。

使用 SearchVectors 进行搜索

使用 SearchVectors API，在向量索引中寻找与查询向量最相似的项目。结果按相关性进行排序，最相似的项目排在最前面。搜索结果具有最终一致性：从写入或更新向量到它出现在搜索结果中，可能会有短暂的延迟。有关更多信息，请参阅 持续进行的写入同步。

基本搜索

以下示例在 ProductEmbeddingIndex 索引中搜索最相似的 10 个项目。由于此索引在其 SearchSchema 中定义了向量索引分区键 (Category)，因此 SearchConditionExpression 必须包含向量索引分区键值。

将查询向量作为由数值构成的普通 JSON 数组保存到文件中（例如 query-vector.json）。

[
    { "N": "0.1234" },
    { "N": "-0.5678" },
    { "N": "0.9012" },
    ...
]

aws dynamodb search-vectors \
    --table-name Products \
    --index-name ProductEmbeddingIndex \
    --search-vector file://query-vector.json \
    --top-k 10 \
    --search-condition-expression "Category = :cat" \
    --expression-attribute-values "{\":cat\": {\"S\": \"Electronics\"}}"

响应包含一个 SearchResults 数组。每个元素都包含匹配的 Item 和一个 Score，表示项目与查询向量的相似程度。

{
    "SearchResults": [
        {
            "Item": {
                "ProductId": { "S": "prod-456" },
                "Category": { "S": "Electronics" },
                "Title": { "S": "Bluetooth Speaker" }
            },
            "Score": 0.0023
        },
        {
            "Item": {
                "ProductId": { "S": "prod-789" },
                "Category": { "S": "Electronics" },
                "Title": { "S": "Noise Cancelling Earbuds" }
            },
            "Score": 0.0145
        }
    ]
}

Score 的含义取决于您在创建索引时选择的距离函数。对于 COSINE 和 EUCLIDEAN，分数越低表示相似度越高。对于 DOT_PRODUCT，分数越高表示相似度越高。

使用 SearchConditionExpression 进行筛选

使用 SearchConditionExpression，根据 SearchSchema 中定义的向量索引分区键和内联筛选条件属性来筛选搜索结果。此表达式使用与其他 DynamoDB 表达式参数相同的语法。

以下示例使用 Brand 内联筛选条件，搜索 Electronics 类别（向量索引分区键）中的项目。

aws dynamodb search-vectors \
    --table-name Products \
    --index-name ProductEmbeddingIndex \
    --search-vector file://query-vector.json \
    --top-k 10 \
    --search-condition-expression "Category = :cat AND Brand = :brand" \
    --expression-attribute-values "{\":cat\": {\"S\": \"Electronics\"}, \":brand\": {\"S\": \"Acme\"}}"

如果您的向量索引在 SearchSchema 中定义了分区键，则必须将其包含在 SearchConditionExpression 中。内联筛选条件属性是可选的。

支持在 SearchConditionExpression 中对向量索引分区键和内联筛选条件属性使用相等运算符 (=)。比较、范围和集合成员资格运算符（<>、<、<=、>、>=、IN）目前不可用。

通过此筛选，您可以将相似性搜索范围限定为数据的子集，这是多租户和检索增强生成（RAG）应用程序中的常见要求。例如，要仅在一个租户内寻找与查询相似的文档，请在 SearchSchema 中将租户属性定义为向量索引分区键 (HASH)，并在每次搜索中传递其值。这会将结果隔离到该租户。这还可以提高性能，因为搜索仅检查相关数据。在路由到的分区中，要想应用额外的等式约束（例如文档类型或状态），请使用内联筛选条件属性。

使用 ProjectionExpression

使用 ProjectionExpression 可仅在搜索结果中返回特定属性。当您不需要所有投影的属性时，这可以减小响应大小。由于 ProductEmbeddingIndex 在其 SearchSchema 中定义了向量索引分区键 (Category)，因而在此示例中，SearchConditionExpression 仍包含向量索引分区键值。

aws dynamodb search-vectors \
    --table-name Products \
    --index-name ProductEmbeddingIndex \
    --search-vector file://query-vector.json \
    --top-k 5 \
    --search-condition-expression "Category = :cat" \
    --expression-attribute-values "{\":cat\": {\"S\": \"Electronics\"}}" \
    --projection-expression "ProductId, Title"

删除向量索引

使用 UpdateTable API 和 VectorIndexUpdates 参数来删除向量索引。

aws dynamodb update-table \
    --table-name Products \
    --vector-index-updates \
        "[
            {\"Delete\": {\"IndexName\": \"ProductEmbeddingIndex\"}}
        ]"

删除向量索引时，DynamoDB 会移除索引及其所有数据。此操作不影响基表或其项目。