基于Spring AI与PgVector的智能文档搜索系统实践

1. 项目背景与核心价值去年在开发内部知识管理系统时我们遇到了传统关键词搜索的瓶颈——工程师们无法精准找到几个月前写的技术方案因为搜索依赖的是记忆中的关键词而非实际需求语义。这正是我们决定构建这个AI驱动文档搜索系统的初衷。这个系统本质上是一个基于语义理解的智能知识库它解决了三个核心痛点语义鸿沟传统搜索需要用户准确记忆文档中的关键词而我们的系统能理解如何优化Spring Boot应用的启动速度这样的自然语言查询多模态检索支持同时使用关键词、语义向量和业务规则进行混合搜索知识沉淀通过RAG模式系统不仅能找到文档还能基于文档内容生成结构化答案技术选型上我们采用Spring Boot 3.4.4 Spring AI的组合主要考虑团队已有的Java技术栈积累Spring AI对多种大模型服务的统一抽象能力PostgreSQLPgVector在保证事务一致性的同时提供向量搜索功能关键决策放弃纯向量数据库方案而选择PgVector是因为生产环境中需要保证文档元数据和向量数据的事务一致性这是许多专业向量数据库无法提供的。2. 系统架构深度解析2.1 整体架构设计系统采用经典的三层架构但针对AI特性做了增强设计[用户界面层] │ ▼ [API网关层] → [认证鉴权] │ ▼ [业务逻辑层] —— [Spring AI] —— [通义千问API] │ │ ▼ ▼ [数据访问层] ← [PgVector扩展] │ ▼ [PostgreSQL 16.1]这种设计的特殊之处在于双通道数据处理文本内容同时走传统关系型存储和向量化管道可插拔AI服务通过Spring AI抽象层可以随时切换底层大模型提供商混合索引策略对高频查询字段建立B-tree索引对向量字段使用IVFFlat索引2.2 核心模块交互流程以文档上传为例看各模块如何协同工作文件接收SearchController接收MultipartFile进行基础校验文本提取DocumentEmbeddingService调用Tika库解析文档内容分块处理按Markdown的##标题分割文档每块不超过512个token向量化通过Spring AI调用通义千问的text-embedding-v2模型持久化使用PgVector的vector类型存储嵌入向量// 典型的分块向量化代码示例 public ListChunk processDocument(MultipartFile file) { String content textExtractor.extract(file); ListString chunks markdownSplitter.split(content); return chunks.stream().map(chunk - { float[] embedding embeddingClient.embed(chunk); return new Chunk(chunk, embedding); }).toList(); }3. 关键技术创新点3.1 混合搜索算法我们的混合搜索不是简单的权重相加而是动态调整策略查询分析阶段通过规则模型判断查询类型技术术语密集 → 提高关键词权重描述性语句 → 提高向量相似度权重包含具体参数 → 触发精确匹配过滤器并行检索阶段-- 关键词搜索SQL SELECT * FROM documents WHERE content LIKE %spring% AND content LIKE %boot% -- 向量搜索SQL SELECT * FROM documents ORDER BY embedding [0.1,0.3,...] LIMIT 10结果融合阶段采用加权倒数融合算法WRF避免单一策略主导3.2 语义增强实现查询重写不只是简单的同义词替换而是包含技术术语标准化springboot → Spring Bootmybatis → MyBatis意图识别增强怎么用 → 追加示例、demo等扩展词报错 → 追加异常、错误代码等上下文感知重写// 原始查询事务不生效 // 重写后Spring事务失效原因 Transactional不生效4. 性能优化实战4.1 PgVector调优经验索引策略CREATE INDEX ON documents USING ivfflat (embedding vector_l2_ops) WITH (lists 100); -- 建议值为总记录数/1000查询优化对TOP K查询添加LIMIT子句对大规模数据使用分区表定期执行ANALYZE documents连接池配置spring.datasource.hikari: maximum-pool-size: 20 connection-timeout: 30000 leak-detection-threshold: 600004.2 缓存设计我们实现了三级缓存体系本地缓存Caffeine缓存高频查询的向量结果分布式缓存Redis缓存文档内容浏览器缓存ETag协商缓存踩坑记录直接缓存向量数组导致内存暴涨改为缓存Base64编码后的字符串节省了40%内存。5. 生产环境部署方案5.1 基础设施要求组件规格要求说明PostgreSQL16GB内存100GB SSD需要pgvector扩展应用服务器4核8GBJDK17Redis2GB内存用作查询缓存阿里云DashScopeQPS≥50需要申请API-KEY5.2 高可用设计数据库层配置PgBouncer连接池主从复制应用层Kubernetes部署Horizontal Pod Autoscaler容灾方案向量搜索降级为关键词搜索大模型超时后返回原始文档片段6. 典型问题排查指南6.1 向量搜索精度问题现象相关文档排名靠后排查步骤检查嵌入模型是否匹配必须使用相同模型生成和查询验证向量维度是否一致通义千问v2是1536维测试余弦相似度计算SELECT 1 - (embedding [0.1,0.2,...]) AS cosine_similarity FROM documents WHERE id 1236.2 性能下降分析现象查询响应时间从200ms升至2s检查清单PostgreSQL的pg_stat_statements查看慢查询检查IVFFlat索引是否需要重建REINDEX INDEX ivfflat_index_name;确认连接池没有耗尽7. 扩展与演进方向当前系统已经支持了基础的RAG流程但我们在实际使用中发现几个可以增强的点多模态扩展除了Markdown正在对接PPT/PDF解析模块增量索引避免每次全量重建向量索引查询分析看板可视化搜索效果优化过程插件机制允许业务方自定义处理管道一个有趣的实践是我们最近尝试用系统自身的搜索记录作为训练数据通过微调让模型更好地理解内部技术术语这在解决公司内部特定缩写的搜索问题上效果显著。