大模型之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

---

---

前言

在前面的文章中，我们已经学习了如何使用 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集成依赖包

 <dependency>
     <groupId>org.springframework.ai</groupId>
     <artifactId>spring-ai-starter-model-openai</artifactId>
 </dependency>

此依赖包用于实现Spring AI与OpenAI的集成，为后续与OpenAI API进行交互提供了必要的支持。

（二）集成向量数据库chroma依赖包

<dependency>
  <groupId>org.springframework.ai</groupId>
  <artifactId>spring-ai-chroma-store</artifactId>
</dependency>

此依赖包用于实现Spring AI与Chroma的集成，为后续与Chroma进行交互提供了必要的支持。

（三）SpringAI相关依赖包版本管理

版本管理

 <dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-bom</artifactId>
            <version>1.0.0-SNAPSHOT</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

部分通过引入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<Document> vectorQuery() {
        List<Document> 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<Document> results = vectorStore.similaritySearch(SearchRequest.builder()
                .query("Spring")
                .topK(5)
                .build());

        return results;
    }
}

1.add() 方法：添加文档至向量数据库

vectorStore.add(documents);

• 接收一个 List<Document> 对象作为输入；
• 自动调用 OpenAI 的 Embedding API 生成向量；
• 存储到 Chroma 的指定集合中；
• 支持元数据字段（metadata），便于后续筛选或过滤。

2.similaritySearch() 方法：执行相似性搜索

@GetMapping("/vectorQuery")
public List<Document> vectorQuery() {
    ...
    List<Document> results = vectorStore.similaritySearch(...);
    return results;
}

• 使用 SearchRequest 构造查询请求；
• 指定 query("Spring") 表示要查找与“Spring”语义最接近的文档；
• 设置 topK(5) 表示返回最相关的前5个结果；
• 最终返回一个 List<Document> 对象。

3.Document 类介绍

org.springframework.ai.document.Document 是 Spring AI 提供的标准文档结构类，具有以下属性：

字段	描述
content	文本内容，是被 Embedding 转换的对象
metadata	元数据字段，支持 Map<String, Object> 结构
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<Document>)	添加文档到向量数据库
delete(List<String> 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<Document> 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<Document> 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.预期返回结果

调用接口后，程序会完成以下操作：

1. 添加如下文档至 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"))
   

2. 使用查询词 "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的探索之旅，开启智能时代的大门！