Memory Search索引模型不匹配故障

Memory Search 索引模型不匹配故障------技术复盘

问题现象

执行 memory_search 查询时返回错误：

index was built for model fts-only, expected text-embedding-3-small

所有语义搜索全部失败，历史记忆检索不可用。

排查过程

1. 确认影响范围： 尝试不同 query 均报同一错误 → 整个索引层面问题
2. 分析错误信息：
   • fts-only: 纯全文搜索，不依赖 embedding 模型
   • text-embedding-3-small: OpenAI 语义向量模型（1536 维）
3. 推断根因： 之前索引用 fts-only 模式构建，现在配置期望 text-embedding-3-small，可能是 Gateway 升级/配置变更导致默认模型切换

根因

Embedding 模型配置变更导致存量索引与新期望模型不匹配。

语义搜索需要重建索引以匹配当前模型，类似数据库 schema migration。

解决方案

# 重建 memory 索引以匹配当前 embedding 模型
openclaw memory index --force

复盘总结

维度	要点
核心认知	Embedding 模型是索引的"编译器"------切换模型后旧索引无法被新模型读取
配置原则	变更配置要同步迁移数据，应该设计"检测→告警→自动/手动重建"闭环
降级策略	语义搜索不可用时应 fallback 到 fts-only 全文搜索，而非直接报错
通用性	此问题在 RAG 系统、向量数据库、搜索引擎中普遍存在，踩过一次永世不忘

#技术复盘 #MemorySearch #Embedding #索引故障 #RAG