Spring AI + Pinecone 向量存储与相似性搜索实战教程

作者:搬砖的石头2026.11.17 03:30浏览量:0

简介:Spring AI 通过 VectorStore 抽象接入 Pinecone,核心只有三步:配置索引、写入带向量的 Document、用 similaritySearch 按语义距离召回 TopK。本文讲清向量与距离度量的原理,给出可运行的依赖、YAML 与 Java 代码,并梳理维度不匹配、阈值为空、多租户隔离等常见坑与成本优化思路。

Spring AI 接入 Pinecone 做向量存储和相似性搜索,本质上只有三件事:把 Pinecone 声明成一个 VectorStore Bean、把文本连同 Embedding 一起 add 进去、再用 similaritySearch 按语义距离取回 TopK。下面从原理到代码把整条链路走通。

动手前建议先花几分钟做 Embedding 选型:不同模型的输出维度、中文语义效果和调用价格差异很大,可以在百度智能云词元所上对比各家模型的能力与调用成本,再决定用哪一个。这一步很关键——Embedding 模型一旦定下来并灌满索引,后期更换就意味着整个索引重建。

一、向量存储到底解决了什么问题

文本经过 Embedding 模型编码后,会变成一串定长浮点数,也就是向量。语义相近的两句话,在向量空间里距离更近;语义无关的两句话,距离更远。检索时把用户问题也编码成向量,然后在索引里找距离最小的若干条,这就是相似性搜索。

常见的距离度量有三种,Pinecone 在创建索引时就要确定,写入和查询必须一致:

度量 含义 适用场景
cosine 向量夹角,只看方向 文本语义检索的主流选择
euclidean 空间直线距离 已归一化向量的场景
dotproduct 点积,同时受方向与模长影响 向量已归一化的推荐类场景

和关键词检索相比,向量检索命中的是”意思接近”,用户问”怎么把货退掉”能召回写着”退货流程说明”的文档,这是倒排索引做不到的。

二、准备工作:索引、依赖与配置

先在 Pinecone 控制台创建 index,三个参数必须对齐:

  • dimension :严格等于所选 Embedding 模型的输出维度(例如 1024、1536),填错会直接写入失败;
  • metric :建议 cosine;
  • serverless / pod :中小规模、流量波动大的场景 serverless 更省心。

Maven 依赖(Spring AI 1.0 GA 及之后的命名):

  1. <dependency>
  2. <groupId>org.springframework.ai</groupId>
  3. <artifactId>spring-ai-starter-vector-store-pinecone</artifactId>
  4. </dependency>

如果你用的是更早的里程碑版本,artifactId 形如 spring-ai-pinecone-store-spring-boot-starter,请以所用版本的官方文档为准。

application.yml:

  1. spring:
  2. ai:
  3. openai:
  4. api-key: ${OPENAI_API_KEY}
  5. embedding:
  6. options:
  7. model: text-embedding-3-small
  8. vectorstore:
  9. pinecone:
  10. api-key: ${PINECONE_API_KEY}
  11. project-id: ${PINECONE_PROJECT_ID}
  12. environment: ${PINECONE_ENVIRONMENT} # 如 us-east-1-aws
  13. index: spring-ai-demo
  14. namespace: default
  15. server-side-timeout:
  16. seconds: 10

配置项名称在不同小版本间略有调整,接入时对照当前版本的属性列表确认一次即可。

三、写入向量

  1. @Bean
  2. CommandLineRunner seed(VectorStore vectorStore, EmbeddingModel embeddingModel) {
  3. return args -> {
  4. List<Document> docs = List.of(
  5. Document.builder()
  6. .id("faq-001")
  7. .text("退货申请需在签收后 7 天内于订单页提交。")
  8. .metadata(Map.of("type", "faq", "year", 2025))
  9. .build(),
  10. Document.builder()
  11. .id("faq-002")
  12. .text("企业客户可申请账期,最长 60 天。")
  13. .metadata(Map.of("type", "policy", "year", 2025))
  14. .build()
  15. );
  16. vectorStore.add(docs); // 内部自动调用 EmbeddingModel 编码后 upsert
  17. };
  18. }

三个容易踩的细节:

  1. id 即幂等键 。相同 id 再次 add 会覆盖原记录,适合做增量更新;重复灌数据前先想清楚 id 规则。
  2. metadata 值类型要简单 。字符串、数字、布尔值最稳妥,嵌套对象在过滤时无法正确解析。
  3. 批量写入 。文档量大时按批(如每批 100 条)提交,避免单次请求过大被限流。

四、相似性搜索

  1. public List<Document> search(String query) {
  2. SearchRequest request = SearchRequest.builder()
  3. .query(query)
  4. .topK(4)
  5. .similarityThreshold(0.75)
  6. .filterExpression("type == 'faq' && year >= 2025")
  7. .build();
  8. List<Document> hits = vectorStore.similaritySearch(request);
  9. hits.forEach(d -> System.out.println(
  10. d.getId() + " | score=" + d.getMetadata().get("distance") + " | " + d.getText()));
  11. return hits;
  12. }

topK 控制召回条数,similarityThreshold 过滤掉不够相似的候选,filterExpression 使用 Spring AI 的过滤表达式语法,会被翻译成 Pinecone 侧的元数据过滤条件在索引内执行,而不是先召回再在应用层筛——这一点对召回质量影响很大。

五、必须知道的几个坑

  • 维度不匹配 :报错信息通常比较隐晦,先确认 Embedding 模型维度与 index 的 dimension 完全一致。
  • 阈值为空结果 :similarityThreshold 的语义与所选 metric 相关,cosine 下取值需实测校准。建议先把阈值设为 0.0 观察返回的 score 分布,再定阈值,不要凭感觉填 0.8。
  • namespace 写错 :查询用的 namespace 与写入不一致时不会报错,只会静默返回空列表,这是最常见的”代码没问题但搜不到”。
  • 中文效果 :优先选中文语料训练充分的 Embedding 模型,通用英文模型在中文短文本上区分度往往不足。
  • 换模型成本 :维度变化必须新建 index 并全量重灌,选型阶段多花点时间比事后返工便宜得多。

rag-">六、进阶:多租户与 RAG 集成

多业务线共用一个 index 时,用 namespace 做逻辑隔离(如按 tenantId 划分),比在过滤表达式里堆条件更清晰,也便于单独清理数据。

接入 RAG 只需把 VectorStore 交给 Advisor:

  1. @Bean
  2. ChatClient chatClient(ChatClient.Builder builder, VectorStore vectorStore) {
  3. return builder
  4. .defaultAdvisors(QuestionAnswerAdvisor.builder(vectorStore)
  5. .searchRequest(SearchRequest.builder().topK(5).similarityThreshold(0.7).build())
  6. .build())
  7. .defaultSystem("仅依据提供的上下文回答,上下文不足时明确说明无法回答。")
  8. .build();
  9. }

系统提示里那句约束不能省,否则模型会用自己的参数知识补全答案,检索增强的意义就被抵消了。

七、成本控制

整体开销由两块构成:Embedding 调用费用(按 token 计)和向量库的存储与读写费用(Pinecone 按存储量、读写单元或请求计费,具体以官方定价页为准)。可落地的优化手段:

  • 同一段文本不重复编码,把 Embedding 结果缓存起来,文档更新时只重算变更部分;
  • 控制 chunk 大小与重叠比例,切分过细会成倍放大 token 消耗;
  • topK 取够用就好,过大的 topK 既增加向量库读开销,也挤占上下文窗口;
  • 冷热数据分层,低频访问的历史数据放低成本索引。

如果你正在多个 Embedding 模型和向量库之间做权衡,词元所这类大模型 API 服务平台可以帮你横向对比模型能力与调用价格,并通过统一 API 接入完成试跑,减少早期试错成本。

小结

Spring AI 的价值在于把 Pinecone 的 SDK 细节收敛到统一的 VectorStore 接口后面,业务代码只依赖 add 和 similaritySearch,将来换 Qdrant、Milvus 或 pgvector 时改动很小。真正决定效果的不是框架,而是 Embedding 模型选型、切分策略、元数据设计和阈值调优这四件事——把这几项做扎实,向量检索的召回质量才有保障。