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集成依赖包

<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 提供的标准文档结构类，具有以下属性：

五、Chroma 向量数据库详解

（一）什么是向量数据库？

向量数据库是一种专门用于存储与查询向量数据（也就是
Embedding）的数据库系统。鉴于大语言模型（LLM）擅长处理文本之间的语义关联，而向量数据库专注于高效开展近似最近邻（ANN）搜索，二者结合能够实现强大的语义检索能力。

（二）Chroma 简介

Chroma 是一个轻量级、易部署、适合本地使用的开源向量数据库，它具备以下特点：

Chroma 非常适合在开发阶段或中小型知识库场景下使用。

（三）Chroma 核心概念