《Agent记忆错误的100个案例手册》第 31–35 案例
本辑为《Agent记忆错误的100个案例手册》连载内容。
案例 31：向量数据库与索引错误｜hnsw-graph-connectivity-island
场景
使用HNSW（Hierarchical Navigable Small World）索引的向量库中，一批文档由于embedding质量差（向量范数极小），在图构建时无法与主图建立足够数量的有效连接（M参数设置较小）。这些向量成为”孤岛”——存在于数据库中但无法通过搜索遍历到达。
错误表现
用户查询这些文档的主题时，即使查询与文档内容高度相关，检索结果也不包含这些文档。管理员在数据库中能看到记录存在，但搜索不到。
解决方案
- 在HNSW建图时进行连通性检查：对孤立连通分量（Connected Component）进行强制连接，或重建其embedding
- 定期检查向量范数分布，对范数异常（过大或过小）的向量进行归一化或重新编码
- 增加HNSW的M参数和efConstruction参数，提高图的连通性密度
原理
HNSW是基于图的近似最近邻算法，依赖图的连通性保证搜索可达性。如果向量在embedding空间中远离其他向量（如由于低质量embedding），或M参数过小，会产生搜索盲区。
案例 32：向量数据库与索引错误｜embedding-quantization-precision-loss
场景
为节省存储，将float32的embedding向量量化为int8（每维度从4字节降到1字节，节省75%空间）。在大部分情况下检索质量无明显下降，但两个原本相似度为0.71的向量（刚好超过阈值0.7）在量化后变为0.69，被过滤掉。
错误表现
某个特定查询-文档对在量化前后检索结果不一致，导致Agent在A环境（未量化）能回答，在B环境（量化）回答”不知道”，行为不可预测。
解决方案
- 量化前进行相似度分布分析：评估量化对相似度分布的影响，确保边界case的误判率可接受
- 采用自适应量化：对高维密集区域使用低精度，对稀疏区域使用高精度
- 量化后执行检索一致性测试：用大量查询对比量化前后的召回率，设定可接受的差异阈值
原理
量化（Quantization）通过降低精度换取存储和计算效率，但会引入量化误差（Quantization Error）。在相似度阈值边界附近的向量对最容易受到量化误差的影响。
案例 33：向量数据库与索引错误｜vector-dimensionality-mismatch-silent-failure
场景
系统升级时，embedding模型从768维更换为1024维，但向量数据库中的旧数据未重新索引。新查询生成1024维向量，数据库期望768维，由于客户端库的参数校验不严格，向量被静默截断或填充。
错误表现
所有查询返回空结果或随机结果，但系统没有报错。运维人员花费数小时才发现是维度不匹配问题。
解决方案
- 在向量数据库中存储维度元数据，插入/查询时进行严格维度校验，不匹配时抛出明确错误
- 模型升级时实施强制重新索引流程，并设置索引版本与模型版本的绑定校验
- 在应用层添加健康检查：定期用已知查询测试检索质量，质量异常时告警
原理
向量维度是embedding空间的”身份证”。维度不匹配意味着两个向量根本不在同一空间中，内积或余弦相似度的计算结果无意义。静默处理（截断/填充）掩盖了这一根本错误。
案例 34：向量数据库与索引错误｜cosine-similarity-magnitude-bias
场景
Agent使用余弦相似度衡量查询与文档的相关性。某文档embedding由于包含大量通用词汇，向量幅值很大（范数为10），另一个高质量专业文档范数为1。用户的专业查询与后者更相关，但余弦相似度只考虑方向不考虑幅值，两者得分相近。
错误表现
通用文档因篇幅长、词汇多被排在专业文档之前，Agent引用了通用性内容而非精准的技术细节。
解决方案
- 使用内积（Dot Product）或欧氏距离（Euclidean Distance）替代余弦相似度，让幅值影响相似度得分
- 对embedding进行L2归一化后再使用余弦相似度，消除幅值差异
- 在重排序阶段引入文档质量的独立评分（如信息密度、来源权威性），与相似度分结合
原理
余弦相似度的公式中，向量幅值被归一化消去。长文档的embedding通常有更大的幅值（因为更多token的向量叠加），但这不代表更高质量。在需要区分信息密度的场景中，余弦相似度存在局限。
案例 35：向量数据库与索引错误｜index-stale-deleted-documents-ghost
场景
用户从知识库中删除了一篇过时的政策文档，但向量索引的删除操作是异步的（通过消息队列消费）。在删除操作被索引消费前的5分钟内，用户进行了相关查询。
错误表现
Agent检索到了已删除的文档并作为依据回答，用户点击文档链接发现404，质疑Agent的可靠性。5分钟后同一查询不再返回该文档，行为不一致。
解决方案
- 实施”软删除”机制：删除时先标记数据库中的记录为”已删除”，索引异步清理期间检索结果先查主库过滤软删除标记
- 使用向量数据库的事务支持：确保向量索引的删除与主库删除在同一事务中提交
- 对删除操作设置”生效等待期”：删除后N秒内，相关查询返回”内容可能已过时”的提示
原理
异步索引更新是常见架构（为了性能），但会导致主库和索引的临时不一致（Eventual Consistency）。对删除操作而言，这种不一致表现为”幽灵数据”。
来源：Agent Search