

# 向量索引故障排除

下表列出了使用向量索引时的常见问题及解决方法。


| 症状 | 原因 | 解决方案 | 
| --- | --- | --- | 
| ValidationException: SearchConditionExpression must be provided when SearchSchema has a HASH key | 索引在其 SearchSchema 中定义了向量索引分区键 (HASH)，但搜索并未提供其值。 | 将向量索引分区键的等值条件添加到 SearchConditionExpression，例如 Category = :cat，并附上匹配的 ExpressionAttributeValues 条目。 | 
| ValidationException: One element in SearchSchema is not defined in attribute definitions | SearchSchema 属性（向量索引分区键或内联筛选条件）未在表的 AttributeDefinitions 中声明。 | 采用与为全局二级索引声明键属性相同的方法，将每个 SearchSchema 属性及其类型添加到 AttributeDefinitions 中。 | 
| ValidationException: Invalid comparator used in SearchConditionExpression | 使用了除 = 之外的运算符。当前仅支持对向量索引分区键和内联筛选条件属性使用相等运算符。 | 重新编写条件，仅使用 =。比较、范围和集合成员资格运算符目前不可用。 | 
| ValidationException: Provided TopK value is out of valid range | TopK 超出了 1 到 100 的范围。 | 将 TopK 设置为 1 到 100 之间（含）的值。 | 
| ValidationException: Cannot search backfilling vector index: <indexName> 或 ValidationException: The table does not have the specified index: <indexName> | 向量索引尚未准备好进行搜索。IndexStatus 为 CREATING，可以在预调配索引时，也可以在回填现有数据时。 | 使用 DescribeTable 并等待，直至 IndexStatus 为 ACTIVE 且 Backfilling 不为 true，然后重试搜索。在创建索引期间，将 ValidationException 视为可重试。 | 
| ValidationException: The table does not have the specified index: <indexName>（当索引存在且 DescribeTable 报告 IndexStatus ACTIVE 时） | 专用搜索端点尚未开始为索引提供服务。DescribeTable 和 SearchVectors 由不同的端点提供服务，在索引变为 ACTIVE 后，搜索端点可能会短暂滞后。 | 重试搜索。在索引变为 ACTIVE 后，立即将 ValidationException 视为可重试。如果错误仍然存在，请确认索引名称，并确认您的网络是否允许使用搜索端点主机名。 | 
| 写入带有向量的项目时，写入被拒绝 | 对于索引，向量的维度数量不正确。 | 确保向量长度与索引 Dimensions 匹配。请参阅[写入带有向量数据的项目](VectorSearchWorkingWith.md#VectorSearchWorkingWith.Write)。 | 
| 写入被拒绝，并显示“参数类型无效” | 向量属性的数据类型错误。DynamoDB 需要使用 32 位浮点数的列表。常见原因包括发送了字符串 (S)、数字标量 (N)、数字集 (NS) 或包含非数字元素的列表。当单个成员的类型错误时，错误消息会精准确定违规的元素索引。 | 将向量属性作为数字 (N) 列表 (L) 发送。验证列表中的每个元素是否均为有效数字，并且列表长度与索引 Dimensions 匹配。 | 
| 删除或省略向量索引分区键属性后，SearchVectors 不再返回项目 | 从项目中移除向量索引分区键属性（通过 UpdateItem 中的 REMOVE）或在 PutItem 中省略该属性不会产生错误。但是，尽管基表项目及其向量嵌入仍然存在，该项目仍会被静默地取消索引，并且不再出现在搜索结果中。 | 对于每个要使其可供搜索的项目，确保都保留了向量索引分区键属性。如果某个项目意外从搜索结果中消失，请验证其分区键属性是否仍然存在于基表项目中。 | 
| 写入被拒绝，原因是“不能包含空字符串值”或者向量索引分区键的类型不匹配 | 向量索引分区键属性被设置为空字符串，或者使用错误的数据类型写入。DynamoDB 会拒绝这些写入，因为索引键属性不能为空，并且必须与声明的类型匹配。 | 为向量索引分区键属性使用具有正确数据类型的有效非空值。检查索引定义以确认所需的类型。 | 
| 搜索结果中缺少属性 | 向量索引未投影此属性。 | 您只能检索投影到索引中的属性。要返回其他属性，请使用更大范围的投影重新创建索引，或者将 ProjectionType 设置为 ALL。 | 

## 将分区键添加到现有向量索引
<a name="VectorSearchTroubleshooting.ChangePartitionKey"></a>

向量索引的 `SearchSchema` 在创建时固定。创建索引后，您无法添加、移除或更改分区键 (`HASH`)。您也无法更改内联筛选条件属性。要更改架构，请创建新索引并迁移到该索引。

要添加分区键或更改其他 `SearchSchema` 属性，请完成以下步骤。

1. 使用所需的分区键创建新向量索引。在 `VectorIndexUpdates` 参数中，将 `UpdateTable` API 与 `Create` 操作一起使用。为新索引指定不同的名称。有关说明，请参阅[将向量索引添加到现有表](VectorSearchWorkingWith.md#VectorSearchWorkingWith.Create.ExistingTable)。

1. 等待新索引完成回填。调用 `DescribeTable` 并确认 `IndexStatus` 为 `ACTIVE` 且 `Backfilling` 为 `false`。

1. 更新应用程序，向新索引发送 `SearchVectors` 请求。将分区键值包含在 `SearchConditionExpression` 中。有关更多信息，请参阅 [使用 SearchConditionExpression 进行筛选](VectorSearchWorkingWith.md#VectorSearchWorkingWith.Search.Filtering)。

1. 确认结果正确后，删除旧索引以停止支付其存储空间的费用。在 `VectorIndexUpdates` 参数中，将 `UpdateTable` API 与 `Delete` 操作一起使用。有关说明，请参阅[删除向量索引](VectorSearchWorkingWith.md#VectorSearchWorkingWith.Delete)。

**索引操作不影响基表数据**  
创建或删除向量索引不会影响基表或其项目。在回填期间，DynamoDB 会从基表项目重新派生向量数据。