简介: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,三个参数必须对齐:
cosine;Maven 依赖(Spring AI 1.0 GA 及之后的命名):
<dependency><groupId>org.springframework.ai</groupId><artifactId>spring-ai-starter-vector-store-pinecone</artifactId></dependency>
如果你用的是更早的里程碑版本,artifactId 形如 spring-ai-pinecone-store-spring-boot-starter,请以所用版本的官方文档为准。
application.yml:
spring:ai:openai:api-key: ${OPENAI_API_KEY}embedding:options:model: text-embedding-3-smallvectorstore:pinecone:api-key: ${PINECONE_API_KEY}project-id: ${PINECONE_PROJECT_ID}environment: ${PINECONE_ENVIRONMENT} # 如 us-east-1-awsindex: spring-ai-demonamespace: defaultserver-side-timeout:seconds: 10
配置项名称在不同小版本间略有调整,接入时对照当前版本的属性列表确认一次即可。
@BeanCommandLineRunner seed(VectorStore vectorStore, EmbeddingModel embeddingModel) {return args -> {List<Document> docs = List.of(Document.builder().id("faq-001").text("退货申请需在签收后 7 天内于订单页提交。").metadata(Map.of("type", "faq", "year", 2025)).build(),Document.builder().id("faq-002").text("企业客户可申请账期,最长 60 天。").metadata(Map.of("type", "policy", "year", 2025)).build());vectorStore.add(docs); // 内部自动调用 EmbeddingModel 编码后 upsert};}
三个容易踩的细节:
add 会覆盖原记录,适合做增量更新;重复灌数据前先想清楚 id 规则。
public List<Document> search(String query) {SearchRequest request = SearchRequest.builder().query(query).topK(4).similarityThreshold(0.75).filterExpression("type == 'faq' && year >= 2025").build();List<Document> hits = vectorStore.similaritySearch(request);hits.forEach(d -> System.out.println(d.getId() + " | score=" + d.getMetadata().get("distance") + " | " + d.getText()));return hits;}
topK 控制召回条数,similarityThreshold 过滤掉不够相似的候选,filterExpression 使用 Spring AI 的过滤表达式语法,会被翻译成 Pinecone 侧的元数据过滤条件在索引内执行,而不是先召回再在应用层筛——这一点对召回质量影响很大。
similarityThreshold 的语义与所选 metric 相关,cosine 下取值需实测校准。建议先把阈值设为 0.0 观察返回的 score 分布,再定阈值,不要凭感觉填 0.8。多业务线共用一个 index 时,用 namespace 做逻辑隔离(如按 tenantId 划分),比在过滤表达式里堆条件更清晰,也便于单独清理数据。
接入 RAG 只需把 VectorStore 交给 Advisor:
@BeanChatClient chatClient(ChatClient.Builder builder, VectorStore vectorStore) {return builder.defaultAdvisors(QuestionAnswerAdvisor.builder(vectorStore).searchRequest(SearchRequest.builder().topK(5).similarityThreshold(0.7).build()).build()).defaultSystem("仅依据提供的上下文回答,上下文不足时明确说明无法回答。").build();}
系统提示里那句约束不能省,否则模型会用自己的参数知识补全答案,检索增强的意义就被抵消了。
整体开销由两块构成:Embedding 调用费用(按 token 计)和向量库的存储与读写费用(Pinecone 按存储量、读写单元或请求计费,具体以官方定价页为准)。可落地的优化手段:
topK 取够用就好,过大的 topK 既增加向量库读开销,也挤占上下文窗口;如果你正在多个 Embedding 模型和向量库之间做权衡,词元所这类大模型 API 服务平台可以帮你横向对比模型能力与调用价格,并通过统一 API 接入完成试跑,减少早期试错成本。
Spring AI 的价值在于把 Pinecone 的 SDK 细节收敛到统一的 VectorStore 接口后面,业务代码只依赖 add 和 similaritySearch,将来换 Qdrant、Milvus 或 pgvector 时改动很小。真正决定效果的不是框架,而是 Embedding 模型选型、切分策略、元数据设计和阈值调优这四件事——把这几项做扎实,向量检索的召回质量才有保障。