Agents-Flex

Appearance

Store 故障排查与生产建议 ​

写入成功但查询不到 ​

按顺序检查：

  1. 写入和查询是否使用相同 Collection/Index；
  2. 查询向量是否生成，维度是否正确；
  3. Embedding 写入模型和查询模型是否一致；
  4. minScore 是否过高；
  5. 条件字段类型和值是否一致；
  6. 数据库索引是否已构建或加载；
  7. 最终查询是否被租户、分区或 metadata 条件过滤。

先移除 minScore 和 condition 做最小向量查询，再逐项加回限制，比直接调大 topK 更容易定位问题。

不同 Collection 数据看起来串了 ​

  • 确认每次 store/search/update/delete 都传入同一个 StoreOptions；
  • 不要运行时修改共享 Config 的默认集合；
  • 检查 Store 的集合缓存、锁和 schema 缓存是否以集合名为 key；
  • 检查数据库中的物理 Key 前缀、表名、索引名或 Collection ID；
  • 使用两个全新集合和互不相同的标记文档做隔离测试；
  • 排除应用缓存、RAG 上下文缓存和前端合并结果造成的假象。

向量维度不匹配 ​

维度由 Embedding 模型决定，并在集合 schema 创建后固定。更换模型时不能只替换 API Key 或 model name：

  1. 创建新集合或新索引；
  2. 用新模型重新生成全部文档向量；
  3. 校验召回质量；
  4. 原子切换业务集合；
  5. 延迟删除旧集合。

不要对向量截断或补零来绕过维度检查。

条件表达式报错 ​

text
Invalid condition expression at position N: ...

位置从 0 开始。检查字符串是否加引号、IN 是否有括号和值、BETWEEN 是否包含 AND、括号是否闭合。 解析成功但数据库报错时，检查供应商是否支持该运算符、字段 mapping 和 metadata 类型。

普通 Redis 无法创建索引 ​

RedisVectorStore 需要 RedisJSON 与 RediSearch。出现未知 FT.CREATE、FT.INFO 或 JSON 命令时，当前服务 不是 Redis Stack，或模块未加载。

Pgvector 初始化权限失败 ​

CREATE EXTENSION vector 通常需要较高权限。让 DBA 安装扩展，并确保应用用户拥有目标 schema 的建表、读写和 建索引权限。生产应用不应使用数据库超级用户。

Elasticsearch/OpenSearch TLS 错误 ​

确认 URL 协议、CA、证书主机名、认证方式和服务端安全插件。不要在生产代码中使用全信任证书管理器。

测试被跳过 ​

许多真实数据库测试只有在环境变量或 profile 开启时运行。检查 Maven 输出中的 Skipped，并确认 Docker 容器 健康、端口正确、测试连接的就是预期实例。

批量写入和重试 ​

  • 使用稳定 ID，使重试尽可能幂等；
  • 区分连接失败、限流、参数错误和部分批次失败；
  • 只对明确可重试的错误采用指数退避和随机抖动；
  • 为批次设置最大文档数和总字节数；
  • 记录失败 ID，不要因为部分失败默认为整批成功；
  • Pgvector 等事务实现与云服务批量 API 的原子性不同。

连接和生命周期 ​

Store 通常应作为应用级单例，避免每个请求新建客户端和连接池。实现 AutoCloseable 或提供 close() 的 Store 应在应用关闭时释放。SearchWrapper、StoreOptions 和 Document 是请求数据，不应作为并发共享的可变单例。

安全 ​

  1. 凭证从密钥系统注入，不硬编码、不写日志；
  2. Collection/Index 使用服务端租户映射，不接受任意用户输入；
  3. 共享集合模式下强制附加 tenant 条件；
  4. 对文档内容和 metadata 做大小、字段数和类型限制；
  5. 数据库只开放私网或受控网关；
  6. 使用最小权限账户；
  7. 日志记录操作、集合、耗时、数量和 request ID，不记录敏感正文；
  8. 对删除、重建索引和批量迁移建立审计与审批。

监控指标 ​

  • 写入、更新、删除、查询的次数、耗时和错误率；
  • Embedding 耗时、Token/字符数和失败率；
  • 查询 topK、结果数、空结果率和分值分布；
  • 批量大小、重试次数和部分失败数；
  • 集合创建、索引构建和 schema 校验失败；
  • 客户端连接池、超时、限流和服务端资源；
  • 按租户统计的容量与请求量。

上线检查表 ​

  • [ ] 固定数据库与客户端版本；
  • [ ] 用生产模型确认向量维度；
  • [ ] 真实数据库测试覆盖全部业务条件；
  • [ ] 两个新集合通过隔离测试；
  • [ ] 校准相似度阈值；
  • [ ] 验证备份、恢复和重建流程；
  • [ ] 配置超时、重试、连接池和资源限制；
  • [ ] 凭证、网络和租户边界通过安全检查；
  • [ ] 应用关闭时释放客户端；
  • [ ] 建立容量、错误率和召回质量监控。