十、向量数据库

说明文中所有类名 / 方法名均在本地spring-ai 1.1.3的 jar 中核对过。中文文档1.0 时代示例里几处旧 API统一整理在最后的「踩坑清单」。1. 它是什么传统关系库精确匹配where id ?。向量库相似性搜索—— 给一个查询向量返回相似的向量KNN。向量库本身不生成向量只负责存储 检索。向量由EmbeddingModel生成float[]。在 RAG 里的位置灌库文档 → 切分 → EmbeddingModel 向量化 → VectorStore 存储 提问问题 → 向量化 → 相似度检索 topK → 检索结果作为上下文拼进提示词 → 大模型回答2. 核心 API1.1.3 实测签名// 只读检索函数式接口最小权限原则FunctionalInterfacepublicinterfaceVectorStoreRetriever{ListDocumentsimilaritySearch(SearchRequestrequest);defaultListDocumentsimilaritySearch(Stringquery){...}}// 读写publicinterfaceVectorStoreextendsDocumentWriter,VectorStoreRetriever{voidadd(ListDocumentdocuments);voiddelete(ListStringidList);voiddelete(Filter.ExpressionfilterExpression);defaultvoiddelete(StringfilterExpression){...}// 字符串 DSLdefaultTOptionalTgetNativeClient(){...}// 拿底层原生客户端}Document常用方法注意是getText()doc.getId();doc.getText();doc.getMetadata();doc.getScore();SearchRequest默认值topK 4、similarityThreshold 0.0即SIMILARITY_THRESHOLD_ACCEPT_ALL不过滤。3. 支持的 19 种实现Azure / Cassandra / Chroma / Elasticsearch / GemFire / MariaDB / Milvus / MongoDB Atlas / Neo4j / OpenSearch / Oracle / PgVector / Pinecone / Qdrant / Redis / SAP Hana / Typesense / Weaviate外加SimpleVectorStore内存实现教学用。4. 三种接入方式A. Starter 自动配置推荐dependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-starter-vector-store-milvus/artifactId/dependencyspring:ai:vectorstore:milvus:client:{host:localhost,port:19530}initialize-schema:true# ⚠ 1.1 起默认 false需要显式打开embedding-dimension:1536# 必须和 embedding 模型维度一致这样才会有VectorStorebean 可以Autowired。B. 手动配置不用自动配置依赖换成非 starter 的spring-ai-milvus-store然后BeanpublicVectorStorevectorStore(MilvusServiceClientclient,EmbeddingModelembeddingModel){returnMilvusVectorStore.builder(client,embeddingModel).collectionName(test_vector_store).indexType(IndexType.IVF_FLAT).metricType(MetricType.COSINE).batchingStrategy(newTokenCountBatchingStrategy()).initializeSchema(true).build();}C. SimpleVectorStore本模块在用不会被自动配置必须自己声明BeanpublicSimpleVectorStorevectorStore(EmbeddingModelembeddingModel){returnSimpleVectorStore.builder(embeddingModel).build();}内存存储重启即丢只适合演示 / 教学。5. 读写删最小示例// 写vectorStore.add(List.of(newDocument(Spring AI rocks,Map.of(country,BG))));// 读两种方式等价ListDocumentdocsretriever.similaritySearch(Spring);ListDocumentdocs2retriever.similaritySearch(SearchRequest.builder().query(Spring).topK(5).similarityThreshold(0.7).build());// 删按 ID / 按过滤表达式 / 按字符串表达式vectorStore.delete(List.of(doc.getId()));vectorStore.delete(b.eq(country,BG).build());vectorStore.delete(country BG);性能按 ID 删最快按过滤器删可能扫索引大批量删除要分批做。6. 元数据过滤只作用于 metadata类似 SQL where字符串 DSLcountry BG genre in [comedy,drama] year 2020编程式FilterExpressionBuilderbnewFilterExpressionBuilder();Filter.Expressionexpb.and(b.in(genre,drama,documentary),b.not(b.lt(year,2020))).build();运算符比较!组合AND/、OR/||其它IN、NIN、NOT、IS NULL/IS NOT NULL并非所有向量库都实现了 NULL 判断本项目提醒KnowledgeBase的元数据是source/category笔记示例里的type Spring、genre fairytale命中不了要么改语料要么改过滤表达式。7. 批处理策略大批量灌库必看接口org.springframework.ai.embedding.BatchingStrategy#batch(ListDocument)。默认实现TokenCountBatchingStrategy上限 8191 token、预留 10%即实际8191 * 0.9单文档超限直接抛异常。覆盖默认注册一个自己的 bean 即可自动配置会被替换。BeanpublicBatchingStrategycustomBatchingStrategy(){returnnewTokenCountBatchingStrategy(EncodingType.CL100K_BASE,8000,0.1);}若 embedding 模型支持autoTruncate如 Vertex AI要把批处理上限设成模型实际限制的 5~10 倍否则批策略先抛异常、模型根本没机会截断。但静默截断会丢掉长文档尾部信息 → 更推荐灌库前先切分。8. 读写分离写法推荐灌库服务依赖VectorStore检索服务只依赖VectorStoreRetrieverServiceclassDocumentRetriever{privatefinalVectorStoreRetrieverretriever;DocumentRetriever(VectorStoreRetrieverretriever){this.retrieverretriever;}ListDocumentfindSimilar(Stringquery){returnretriever.similaritySearch(query);}}好处最小权限、依赖更少、函数式接口可用 lambda / 方法引用造测试替身。9. ⚠ 1.1.3 踩坑清单文档 vs 实际文档 / 教程写法1.1.3 实际Document::getContentDocument::getText另有getFormattedContent()chatModel.generate(prompt)chatModel.call(String)schema 自动初始化initialize-schema默认false需显式打开直接Autowired VectorStore必须有具体 starter 或自己声明 beanSimpleVectorStore不自动配置Document.getScore()一定有值存在该 API但不匹配时为 null用前先判空本项目专属坑DeepSeek 没有 embedding 接口spring.ai.openai.embedding.*必须另配服务SiliconFlow / 通义兼容模式 / Ollama否则add()直接 404且入库与检索必须用同一个 embedding 模型否则维度不匹配。ListDocumentdocsnewJsonReader(newFileSystemResource(file),name,description).get();vectorStore.add(docs);