本地向量库Chroma实战：入库检索与四步验收

Spring 生态做 RAG 有个天然优势：向量库接入被 Spring AI 抽象成了 VectorStore 接口，换存储实现不动业务代码。本文走一遍 Spring Boot + OpenAI + 本地 Chroma 的完整集成，从部署到接口验收。

环境基线：JDK 17 与 Chroma 部署

项目要求 Java 17，命令行 java -version 确认。Chroma 是本地向量库的轻量选择，一条命令起服务：

pip install chromadb
chroma run --path ./chroma_data --port 8000

--path 指定持久化目录，容器或进程重启数据不丢。端口 8000 后面配置要对上。

依赖与配置

POM 里引入两块：spring-ai-openai 相关依赖、Chroma 的 vector store 适配包，版本统一交给 spring-ai-bom 管理。application.yml 里配齐三样：OpenAI 密钥、Chroma 服务地址、collection 名称。密钥同样走环境变量注入，不落配置文件。

配置类拆解

向量库接入的配置类由三部分组成：

@Bean
public VectorStore vectorStore(EmbeddingModel embeddingModel) {
    ChromaApi chromaApi = new ChromaApi("http://localhost:8000", RestClient.builder());
    return new ChromaVectorStore(embeddingModel, chromaApi, "docs_collection");
}

RestClient.Builder 构建 HTTP 客户端，ChromaApi 封装对 Chroma 服务的访问，ChromaVectorStore 把 Chroma 适配进 Spring AI 的 VectorStore 抽象。业务代码只见 VectorStore 接口，日后换 PGVector、Milvus，配置类改一行。

入库与检索的两个核心方法

控制器层就两个动作。add 负责文档入库——Document 类承载文本和元数据，入库时自动向量化：

vectorStore.add(List.of(new Document(content, Map.of("source", "employee Handbook"))));

similaritySearch 负责语义检索，SearchRequest 指定查询文本和返回条数：

List<Document> results = vectorStore.similaritySearch(
        SearchRequest.builder().query("年假怎么请").topK(5).build());

验收清单

集成完别急着上线，四步验收：

入库验证：add 后直接调 similaritySearch 用原文关键词查，能命中自己才算写进去了；
语义验证：换同义说法（"休假流程"查"年假怎么请"）确认语义检索生效，不是关键词匹配；
元数据验证：返回的 Document 带 source 等元数据，引用来源才有据可查；
异常验证：Chroma 服务停掉后再调接口，应用要有明确的失败提示而不是无限挂起。

与 RAG 全链路的关系

向量库只是 RAG 的存储层。入库侧要解决分块（表格整块入库加摘要行）、元数据挂载；查询侧要过相似度阈值——低于阈值宁可答"没有相关内容"，也别让模型硬编。检索决定上限、生成决定表达，Chroma 这层做扎实，后面换更强模型才有意义。