尧图网页设计 
37 · 常见错误与排查清单一句话遇到问题先对照本清单——维度不匹配、索引没生效、召回率低是三大高频坑。本章是全教程的收官速查手册把前面各章的坑集中成一份排错地图。一、写入 / 类型相关❌expected N dimensions, not M原因插入向量维度和列定义vector(N)不一致。排查-- 确认列维度SELECTcolumn_name,udt_nameFROMinformation_schema.columnsWHEREtable_nameitems;-- 确认要插入向量的维度是否等于 N解决让向量维度与列一致换模型后维度变了要改表并重灌数据第 24 章。❌type vector does not exist原因当前数据库没启用扩展。解决CREATE EXTENSION IF NOT EXISTS vector;注意扩展按库启用第 07 章。❌ 插入报格式错误原因向量写成了(1,2,3)或{1,2,3}。解决必须是方括号字符串[1,2,3]第 09 章。二、索引没生效查询还是慢 先确认是否走了索引EXPLAINANALYZESELECTidFROMitemsORDERBYembedding[...]LIMIT10;看到Seq Scan 没走索引Index Scan using ... hnsw 走了。❌ 常见原因与解决现象原因解决用-但索引是余弦距离运算符与索引操作符类不匹配统一余弦索引配第 15 章数据量太小优化器认为全表扫更快正常现象大数据下会走索引没建索引忘了建CREATE INDEX ... USING hnsw ...查询没有 ORDER BY 距离 LIMIT不是 KNN 模式改成ORDER BY 距离 LIMIT k第 16 章加了函数/表达式与索引表达式不一致让查询表达式和索引定义完全一致三、召回率低搜不准 / 结果少❌ 结果比 LIMIT 少 / 漏掉相关文档最可能带WHERE过滤导致召回塌陷第 21 章。解决按优先级升级 pgvector 0.8 开迭代扫描第 22 章SEThnsw.iterative_scanrelaxed_order;过滤值固定 →部分索引。多租户 →分区表。兜底调大ef_search。❌ 整体召回偏低原因解决ef_search/probes太小调大第 20、18 章IVFFlat 桶过时REINDEX第 33 章分块太大/太小优化 chunk第 25 章距离度量选错文本用余弦第 12 章入库和查询用了不同模型统一模型重灌第 24 章 怎么确认召回低用暴力搜索当真值对比第 23、30 章量化 RecallK别靠感觉。四、性能问题现象排查解决查询慢EXPLAIN ANALYZE看是否走索引建索引 / 调参内存不够、频繁读盘查缓存命中率第 36 章halfvec / 加内存 / pgvectorscale写入慢是否边插边维护索引先导后建第 32 章越跑越慢死元组/索引膨胀VACUUM / REINDEX第 33 章建索引很久未加大维护内存/并行调maintenance_work_mem、并行第 32 章五、建索引报错❌memory required is NN MB, maintenance_work_mem is MM MB原因维护内存不足。解决SETmaintenance_work_mem4GB;❌ IVFFlat 建索引后召回很差原因空表或数据太少时建的 IVFFlat聚类没意义。解决先灌足够数据再建第 17 章或改用 HNSW。六、快速自检清单上线前逐项确认[ ] CREATE EXTENSION vector 已在目标库执行 [ ] 列维度 embedding 模型维度 [ ] 入库和查询用的是同一个 embedding 模型 [ ] 距离运算符 与 索引操作符类 一致 [ ] 查询是 ORDER BY 距离 LIMIT k 的 KNN 模式 [ ] EXPLAIN 确认走了向量索引 [ ] 带过滤查询已处理召回塌陷迭代扫描/部分索引/分区 [ ] 用评测集量化了 RecallK [ ] ef_search/probes 已按评测调优 [ ] 索引能放进内存缓存命中率高 [ ] 已配置 VACUUM / 定期维护 [ ] 已做备份 / 高可用七、一句话总结三大高频坑维度不匹配查列定义与模型、索引没生效EXPLAIN 看 Seq Scan 运算符匹配、召回低过滤塌陷 调 ef_search 评测量化上线前过一遍自检清单。恭喜全部 37 章学完你已经从不懂向量成长为能独立设计、优化、运维生产级 pgvector 向量检索系统的开发者概念(01-05) → 环境基础(06-11) → 查询进阶(12-15) → 索引性能(16-23) → 真实应用(24-29) → 生产运维(30-37)➡️ 想把这些能力用 Java 框架工程化、快速做出 RAG 应用转姊妹篇docs/spring-ai-vector-learning/00-学习计划总览.md 37 · 常见错误与排查清单
37 · 常见错误与排查清单一句话遇到问题先对照本清单——维度不匹配、索引没生效、召回率低是三大高频坑。本章是全教程的收官速查手册把前面各章的坑集中成一份排错地图。一、写入 / 类型相关❌expected N dimensions, not M原因插入向量维度和列定义vector(N)不一致。排查-- 确认列维度SELECTcolumn_name,udt_nameFROMinformation_schema.columnsWHEREtable_nameitems;-- 确认要插入向量的维度是否等于 N解决让向量维度与列一致换模型后维度变了要改表并重灌数据第 24 章。❌type vector does not exist原因当前数据库没启用扩展。解决CREATE EXTENSION IF NOT EXISTS vector;注意扩展按库启用第 07 章。❌ 插入报格式错误原因向量写成了(1,2,3)或{1,2,3}。解决必须是方括号字符串[1,2,3]第 09 章。二、索引没生效查询还是慢 先确认是否走了索引EXPLAINANALYZESELECTidFROMitemsORDERBYembedding[...]LIMIT10;看到Seq Scan 没走索引Index Scan using ... hnsw 走了。❌ 常见原因与解决现象原因解决用-但索引是余弦距离运算符与索引操作符类不匹配统一余弦索引配第 15 章数据量太小优化器认为全表扫更快正常现象大数据下会走索引没建索引忘了建CREATE INDEX ... USING hnsw ...查询没有 ORDER BY 距离 LIMIT不是 KNN 模式改成ORDER BY 距离 LIMIT k第 16 章加了函数/表达式与索引表达式不一致让查询表达式和索引定义完全一致三、召回率低搜不准 / 结果少❌ 结果比 LIMIT 少 / 漏掉相关文档最可能带WHERE过滤导致召回塌陷第 21 章。解决按优先级升级 pgvector 0.8 开迭代扫描第 22 章SEThnsw.iterative_scanrelaxed_order;过滤值固定 →部分索引。多租户 →分区表。兜底调大ef_search。❌ 整体召回偏低原因解决ef_search/probes太小调大第 20、18 章IVFFlat 桶过时REINDEX第 33 章分块太大/太小优化 chunk第 25 章距离度量选错文本用余弦第 12 章入库和查询用了不同模型统一模型重灌第 24 章 怎么确认召回低用暴力搜索当真值对比第 23、30 章量化 RecallK别靠感觉。四、性能问题现象排查解决查询慢EXPLAIN ANALYZE看是否走索引建索引 / 调参内存不够、频繁读盘查缓存命中率第 36 章halfvec / 加内存 / pgvectorscale写入慢是否边插边维护索引先导后建第 32 章越跑越慢死元组/索引膨胀VACUUM / REINDEX第 33 章建索引很久未加大维护内存/并行调maintenance_work_mem、并行第 32 章五、建索引报错❌memory required is NN MB, maintenance_work_mem is MM MB原因维护内存不足。解决SETmaintenance_work_mem4GB;❌ IVFFlat 建索引后召回很差原因空表或数据太少时建的 IVFFlat聚类没意义。解决先灌足够数据再建第 17 章或改用 HNSW。六、快速自检清单上线前逐项确认[ ] CREATE EXTENSION vector 已在目标库执行 [ ] 列维度 embedding 模型维度 [ ] 入库和查询用的是同一个 embedding 模型 [ ] 距离运算符 与 索引操作符类 一致 [ ] 查询是 ORDER BY 距离 LIMIT k 的 KNN 模式 [ ] EXPLAIN 确认走了向量索引 [ ] 带过滤查询已处理召回塌陷迭代扫描/部分索引/分区 [ ] 用评测集量化了 RecallK [ ] ef_search/probes 已按评测调优 [ ] 索引能放进内存缓存命中率高 [ ] 已配置 VACUUM / 定期维护 [ ] 已做备份 / 高可用七、一句话总结三大高频坑维度不匹配查列定义与模型、索引没生效EXPLAIN 看 Seq Scan 运算符匹配、召回低过滤塌陷 调 ef_search 评测量化上线前过一遍自检清单。恭喜全部 37 章学完你已经从不懂向量成长为能独立设计、优化、运维生产级 pgvector 向量检索系统的开发者概念(01-05) → 环境基础(06-11) → 查询进阶(12-15) → 索引性能(16-23) → 真实应用(24-29) → 生产运维(30-37)➡️ 想把这些能力用 Java 框架工程化、快速做出 RAG 应用转姊妹篇docs/spring-ai-vector-learning/00-学习计划总览.md