大模型之Spring AI实战系列（十一）：Spring Boot + OpenAI 集成本地向量数据库Chroma
系列篇章💥
| No. | 文章 |
|---|---|
| 1 | 大模型之Spring AI实战系列（一）：基础认知篇 - 开启智能应用开发之旅 |
| 2 | 大模型之Spring AI实战系列（二）：Spring Boot + OpenAI 打造聊天应用全攻略 |
| 3 | 大模型之Spring AI实战系列（三）：Spring Boot + OpenAI 实现聊天应用上下文记忆功能 |
| 4 | 大模型之Spring AI实战系列（四）：Spring Boot + OpenAI 使用OpenAI Embedding实现文本向量化 |
| 5 | 大模型之Spring AI实战系列（五）：Spring Boot + OpenAI 构建带角色设定的智能对话系统 |
| 6 | 大模型之Spring AI实战系列（六）：Spring Boot + OpenAI 利用PromptTemplate构建动态提示词系统 |
| 7 | 大模型之Spring AI实战系列（七）：Spring Boot + OpenAI 构建结构化输出的AI响应系统 |
| 8 | 大模型之Spring AI实战系列（八）：Spring Boot + OpenAI 使用Whisper实现语音转文本功能 |
| 9 | 大模型之Spring AI实战系列（九）：Spring Boot + OpenAI 使用TTS实现文本转语音功能 |
| 10 | 大模型之Spring AI实战系列（十）：Spring Boot + OpenAI 使用 DALL·E实现文本生成图像功能 |
| 11 | 大模型之Spring AI实战系列（十一）：Spring Boot + OpenAI 集成本地向量数据库Chroma |
目录
- 系列篇章💥
- 前言
- 一、开发环境准备
- （一）Java 版本要求
- （二）Maven 构建工具
- （三）OpenAI API 密钥
- （三）本地部署 Chroma 数据库
- 二、POM依赖引入
- （一）Spring AI与OpenAI集成依赖包
- （二）集成向量数据库chroma依赖包
- （三）SpringAI相关依赖包版本管理
- 三、配置文件详解
- 四、核心代码详解
- （一）Application启动类
- （二）向量数据库配置类
- 1.`RestClient.Builder`：构建 HTTP 请求客户端
- 2.`ChromaApi`：封装对 Chroma 服务的访问接口
- 3.`ChromaVectorStore`：集成到 Spring AI 的向量数据库适配器
- （三）向量检索控制器
- 1.`add()` 方法：添加文档至向量数据库
- 2.`similaritySearch()` 方法：执行相似性搜索
- 3.`Document` 类介绍
- 五、Chroma 向量数据库详解
- （一）什么是向量数据库？
- （二）Chroma 简介
- （三）Chroma 核心概念
- 六、Spring AI 中的 VectorStore 抽象层
- 七、Chroma 本地部署全流程详解
- （一）安装 Chroma
- （二）启动 Chroma 服务
- （三）创建 Collection（集合）
- （四）Spring AI 配置与接入
- 八、Chroma 与 Spring AI 的整合实践
- （一）向量数据库的基本应用场景
- 1.文档向量化存储
- 2.语义相似性检索
- 3.多模态检索（未来拓展方向）
- （二）示例：文档入库 + 相似性查询流程演示
- 步骤 1：添加文档
- 步骤 2：执行语义搜索
- 九、部署与测试
- （一）部署准备
- （二）启动 Chroma 服务（本地）
- （三）启动 Spring Boot 应用
- （四）测试接口功能
- 1.请求方式
- 2.请求参数说明
- 3.预期返回结果
- 总结
前言
在前面的文章中，我们已经学习了如何使用 Spring AI 构建基础聊天服务、流式对话、上下文记忆、角色设定、动态提示词模板、结构化输出、语音识别与合成、图像生成等能力。本文将聚焦于向量数据库（VectorStore） 的集成与使用。
我们将基于 spring-ai-openai-vectorStore 示例项目，并结合本地部署的 Chroma 向量数据库，详细介绍如何通过 Spring AI 集成 Chroma 实现文档的存储与相似性检索，为后续 RAG（Retrieval-Augmented Generation）系统打下坚实的基础。
一、开发环境准备
（一）Java 版本要求
本项目采用Java 17进行编译和运行，请务必确保你的开发环境已成功安装JDK 17。你可以在命令行中输入以下命令进行检查：
java -version
输出应类似如下内容：
openjdk version "17.0.8" 2023-07-18 OpenJDK Runtime Environment (build 17.0.8+7) OpenJDK 64-Bit Server VM (build 17.0.8+7, mixed mode, sharing)
（二）Maven 构建工具
确保你已安装 Maven 并配置好环境变量：
mvn -v
输出应类似如下内容：
Apache Maven 3.8.8 (4c87b05d9aedce574290d1acc98575ed5eb6cd39) Maven home: D:\Program Files (x86)\apache-maven-3.8.8 Java version: 17.0.12, vendor: Oracle Corporation, runtime: D:\Program Files\jdk-17.0.12 Default locale: zh_CN, platform encoding: GBK OS name: "windows 10", version: "10.0", arch: "amd64", family: "windows"
（三）OpenAI API 密钥
你需要注册 OpenAI 官网 获取 API Key（国内可以直接使用中转地址），并设置为环境变量：
export OPENAI_API_KEY="your_openai_api_key" export OPENAI_API_URL="https://api.openai.com/v1"
注意：出于安全考虑，不建议将密钥硬编码在代码中，推荐使用环境变量或配置中心进行管理。
（三）本地部署 Chroma 数据库
你可以通过如下命令安装并启动 Chroma：
pip install chromadb
启动服务：
chroma run --path "D:/Program Files/chromadb" --host 0.0.0.0 --port 8000
创建集合：
curl -v -X POST http://localhost:8000/api/v1/collections -H "Content-Type: application/json" -d "{\"name\": \"TestCollection\"}"二、POM依赖引入
（一）Spring AI与OpenAI集成依赖包
org.springframework.ai spring-ai-starter-model-openai此依赖包用于实现Spring AI与OpenAI的集成，为后续与OpenAI API进行交互提供了必要的支持。
（二）集成向量数据库chroma依赖包
org.springframework.ai spring-ai-chroma-store
此依赖包用于实现Spring AI与Chroma的集成，为后续与Chroma进行交互提供了必要的支持。
（三）SpringAI相关依赖包版本管理
版本管理
org.springframework.ai spring-ai-bom 1.0.0-SNAPSHOT pom import部分通过引入spring-ai-bom，实现了对SpringAI相关依赖包版本的统一管理。这样，在项目中使用Spring AI相关依赖时，无需在每个依赖声明中单独指定版本号，只需遵循spring-ai-bom中定义的版本即可，极大地简化了依赖管理工作，同时确保了项目中依赖版本的一致性和稳定性。
三、配置文件详解
在配置文件 application.yml 中，对openai相关参数进行配置：
server: port: 8893 spring: ai: openai: base-url: ${OPENAI_API_URL} api-key: ${OPENAI_API_KEY} chat: options: model: gpt-3.5-turbo temperature: 0.7 embedding: model: text-embedding-ada-002- 默认使用的是 OpenAI 的 text-embedding-ada-002 模型；
- 也可以替换为其他支持的 Embedding 模型（如 HuggingFace 的 SBERT 模型）；
- 如果希望使用企业级私有模型，需自行替换 Embedding Model 的实现。
四、核心代码详解
（一）Application启动类
这是 Spring Boot 的启动类，非常简洁：
@SpringBootApplication public class SpringAiApplication { public static void main(String[] args) { SpringApplication.run(SpringAiApplication.class, args); } }Spring Boot会自动扫描并加载所有的Controller、Service等Bean，为项目的启动和运行奠定基础。它通过@SpringBootApplication注解开启了Spring Boot的自动配置功能，使得项目能够快速搭建起一个完整的Spring应用环境。
（二）向量数据库配置类
该类用于配置 Chroma 向量数据库连接与初始化。
@Configuration public class ChromaConfig { @Bean public RestClient.Builder builder() { return RestClient.builder().requestFactory(new SimpleClientHttpRequestFactory()); } @Bean public ChromaApi chromaApi(RestClient.Builder restClientBuilder) { String chromaUrl = "http://localhost:8000"; ChromaApi chromaApi = new ChromaApi(chromaUrl, restClientBuilder); return chromaApi; } @Bean public VectorStore chromaVectorStore(EmbeddingModel embeddingModel, ChromaApi chromaApi) { return ChromaVectorStore.builder(chromaApi, embeddingModel) .collectionName("TestCollection") .initializeSchema(true) .build(); } }1.RestClient.Builder：构建 HTTP 请求客户端
- SimpleClientHttpRequestFactory 是 Spring 提供的一个简单的 HTTP 客户端工厂。
- 用于构建访问 Chroma REST API 的请求对象。
2.ChromaApi：封装对 Chroma 服务的访问接口
- 通过构造方法传入 Chroma 服务地址 http://localhost:8000；
- 封装对集合、文档的增删改查操作；
- 可以自定义超时、重试策略等。
3.ChromaVectorStore：集成到 Spring AI 的向量数据库适配器
- 提供与 Spring AI 的统一接口 VectorStore；
- 支持添加文档、删除文档、查询相似文档等功能；
- 会自动调用 OpenAI 的 Embedding 模型对文本进行向量化处理；
- 支持指定集合名称（如 TestCollection）、是否初始化 Schema 等参数。
（三）向量检索控制器
该类使用 VectorStore 接口来实现文档的添加与相似性检索。
@RestController @RequestMapping("/vectorStore") public class VectorStoreController { @Autowired VectorStore vectorStore; @GetMapping("/vectorQuery") public List vectorQuery() { List documents = List.of( new Document("Spring AI rocks!! ...", Map.of("meta1", "meta1")), new Document("The World is Big...", null), new Document("You walk forward facing the past and you turn back toward the future.", Map.of("meta2", "meta2"))); vectorStore.add(documents); List results = vectorStore.similaritySearch(SearchRequest.builder() .query("Spring") .topK(5) .build()); return results; } }1.add() 方法：添加文档至向量数据库
vectorStore.add(documents);
- 接收一个 List 对象作为输入；
- 自动调用 OpenAI 的 Embedding API 生成向量；
- 存储到 Chroma 的指定集合中；
- 支持元数据字段（metadata），便于后续筛选或过滤。
2.similaritySearch() 方法：执行相似性搜索
@GetMapping("/vectorQuery") public List vectorQuery() { ... List results = vectorStore.similaritySearch(...); return results; }- 使用 SearchRequest 构造查询请求；
- 指定 query("Spring") 表示要查找与“Spring”语义最接近的文档；
- 设置 topK(5) 表示返回最相关的前5个结果；
- 最终返回一个 List 对象。
3.Document 类介绍
org.springframework.ai.document.Document 是 Spring AI 提供的标准文档结构类，具有以下属性：
字段 描述 content 文本内容，是被 Embedding 转换的对象 metadata 元数据字段，支持 Map 结构 id 可选字段，用于唯一标识文档 五、Chroma 向量数据库详解
（一）什么是向量数据库？
向量数据库是一种专门用于存储和查询向量数据（即 Embedding）的数据库系统。由于大语言模型（LLM）擅长处理文本之间的语义关系，而向量数据库则专注于高效地进行近似最近邻（ANN）搜索，两者结合可以实现强大的语义检索能力。
（二）Chroma 简介
Chroma 是一个轻量级、易部署、适合本地使用的开源向量数据库，它具备以下特点：
特点 描述 ✅ 开源免费 社区活跃，易于扩展和定制 ✅ 易部署 可一键启动，无需复杂依赖 ✅ 支持REST API 方便与各类语言集成 ✅ 支持多集合管理 不同业务模块可划分独立集合 ✅ 支持持久化存储 支持本地磁盘保存数据 Chroma 非常适合在开发阶段或中小型知识库场景下使用。
（三）Chroma 核心概念
概念 说明 Collection 类似传统数据库的“表”，用于组织多个文档 ID 每个文档的唯一标识符 Metadata 文档的元数据信息，支持按字段筛选 Embedding 文本的数值表示形式，用于向量计算 Distance 相似度计算的方式（默认使用余弦距离） 六、Spring AI 中的 VectorStore 抽象层
Spring AI 对多种向量数据库进行了抽象和封装，提供了统一的接口 VectorStore，使得用户无需关心底层实现，即可完成文档的存取与检索。
VectorStore 接口主要方法
方法 功能描述 add(List) 添加文档到向量数据库 delete(List documentIds) 删除指定ID的文档 retrieve(SearchRequest request) 执行向量检索 similaritySearch(String query, int topK) 执行文本相似度搜索（封装了向量转换） 注：以上方法均基于 Embedding 模型自动完成文本 → 向量的转换。
七、Chroma 本地部署全流程详解
（一）安装 Chroma
pip install chromadb
验证是否安装成功：
pip show chromadb
（二）启动 Chroma 服务
chroma run --path "D:/Program Files/chromadb" --host 0.0.0.0 --port 8000
- --path：指定本地存储路径，用于持久化数据；
- --host：绑定地址，默认只允许本地访问，设为 0.0.0.0 后支持外部访问；
- --port：指定监听端口，默认为 8000。
（三）创建 Collection（集合）
curl -v -X POST http://localhost:8000/api/v1/collections \ -H "Content-Type: application/json" \ -d "{\"name\": \"TestCollection\"}"- 创建名为 TestCollection 的集合；
- 集合一旦创建，后续所有的向量数据都将在该集合下进行存储。
（四）Spring AI 配置与接入
在 [ChromaConfig.java]中配置 ChromaVectorStore：
@Bean public VectorStore chromaVectorStore(EmbeddingModel embeddingModel, ChromaApi chromaApi) { return ChromaVectorStore.builder(chromaApi, embeddingModel) .collectionName("TestCollection") .initializeSchema(true) .build(); }- ChromaVectorStore 是 Spring AI 提供的封装接口；
- collectionName 指定要操作的集合；
- initializeSchema(true) 表示如果集合不存在，则自动创建。
八、Chroma 与 Spring AI 的整合实践
（一）向量数据库的基本应用场景
1.文档向量化存储
- 将任意文本内容（FAQ、技术文档、文章、日志等）转换为向量后入库；
- 便于后续基于语义的检索和匹配。
2.语义相似性检索
- 输入一段自然语言，从向量数据库中找出最相近的文档；
- 例如：用户输入“Spring Boot 如何配置数据库连接？”，系统可返回历史问答中的相关答案。
3.多模态检索（未来拓展方向）
- 可配合图像、音频 Embedding，构建跨模态检索系统；
- 例如：上传一张图片，检索出与其内容语义最接近的文本描述。
（二）示例：文档入库 + 相似性查询流程演示
步骤 1：添加文档
List documents = List.of( new Document("Spring AI rocks!! Spring AI rocks!! Spring AI rocks!!", Map.of("meta1", "meta1")), new Document("The World is Big and Salvation Lurks Around the Corner"), new Document("You walk forward facing the past and you turn back toward the future.", Map.of("meta2", "meta2")) ); vectorStore.add(documents);- vectorStore.add() 会自动调用 Embedding 模型生成向量；
- 将文本内容连同元数据一起写入 Chroma 集合中。
步骤 2：执行语义搜索
List results = vectorStore.similaritySearch( SearchRequest.builder().query("Spring").topK(5).build() );- 输入关键词 "Spring"；
- 返回 Top-K 条最相似的文档；
- 检索结果可用于前端展示、进一步分析或作为 Prompt 输入。
九、部署与测试
在完成了本地开发环境的搭建和 Chroma 向量数据库的集成后，下一步就是将项目部署并进行功能验证。
（一）部署准备
在部署前，请确保以下条件已满足：
条件 描述 Java 环境 JDK 17 或以上版本 Maven 构建工具 安装并配置好 mvn 命令 OpenAI API 密钥 已获取并配置为系统环境变量 Chroma 数据库 已成功安装并启动，集合 TestCollection 已创建 （二）启动 Chroma 服务（本地）
如果你尚未启动 Chroma，请先执行如下命令：
chroma run --path "D:/Program Files/chromadb" --host 0.0.0.0 --port 8000
如果你使用的是 Linux 或 macOS，请注意路径格式的差异。
该命令会启动一个本地运行的 Chroma 服务，监听在 http://localhost:8000，用于后续 Spring Boot 应用访问。
（三）启动 Spring Boot 应用
可以直接基于IntelliJ IDEA启动并运行Spring Boot应用程序，也可以进入项目根目录，执行 mvn clean package 进行打包，之后采用 java -jar xxx.jar 命令进行部署运行。运行成功后，应用将在 http://localhost:8893启动。
（四）测试接口功能
Spring Boot 应用提供了一个 REST 接口 /vectorStore/vectorQuery，用于演示文档入库 + 相似性检索功能。
1.请求方式
- 方法：GET
- URL：http://localhost:8893/vectorStore/vectorQuery
2.请求参数说明
该接口无需额外参数，内部硬编码了几个测试文档。
3.预期返回结果
调用接口后，程序会完成以下操作：
-
添加如下文档至 Chroma：
new Document("Spring AI rocks!! ...", Map.of("meta1", "meta1")), new Document("The World is Big and Salvation Lurks Around the Corner"), new Document("You walk forward facing the past...", Map.of("meta2", "meta2")), new Document("Spring is nature’s way of saying...", Map.of("meta3", "meta3")) -
使用查询词 "Spring" 执行相似性搜索，返回最相关的文档列表。
示例响应内容如下（JSON 格式）：
[ { "content": "Spring AI rocks!! Spring AI rocks!! Spring AI rocks!!", "metadata": { "meta1": "meta1" } }, { "content": "Spring is nature’s way of saying, “Let’s party!”...", "metadata": { "meta3": "meta3" } } ]注：返回结果可能因模型 Embedding 的微小变化略有不同，但总体趋势应一致。
总结
通过本文的详细讲解，我们掌握了如何在 Spring AI 中集成 Chroma 向量数据库，实现文档的向量化存储与语义检索。我们了解了 Chroma 的基本概念、本地部署方式、集合管理以及与 Spring AI 的集成过程。为后续构建基于向量数据库的知识检索系统打下了坚实基础。
在下一篇文章中，我们将正式进入 RAG（Retrieval-Augmented Generation）系统构建，结合向量数据库与 LLM 的能力，打造真正意义上的智能问答系统，敬请期待！
若您对本文介绍的技术内容感兴趣，希望进一步探索和实践，欢迎关注我，通过私信的方式与我联系，获取完整的项目代码，开启您的 Spring AI 开发之旅。
🎯🔖更多专栏系列文章：AI大模型提示工程完全指南、AI大模型探索之路（零基础入门）、AI大模型预训练微调进阶、AI大模型开源精选实践、AI大模型RAG应用探索实践🔥🔥🔥 其他专栏可以查看博客主页📑
😎 作者介绍：资深程序老猿，从业10年+、互联网系统架构师，目前专注于AIGC的探索（CSDN博客之星|AIGC领域优质创作者）
📖专属社群：欢迎关注【小兵的AI视界】公众号或扫描下方👇二维码，回复‘入群’ 即刻上车，获取邀请链接。
💘领取三大专属福利：1️⃣免费赠送AI+编程📚500本，2️⃣AI技术教程副业资料1套，3️⃣DeepSeek资料教程1套🔥（限前500人）
如果文章内容对您有所触动，别忘了点赞、⭐关注，收藏！加入我们，一起携手同行AI的探索之旅，开启智能时代的大门！
-
