Yuxu Ge
文章 · 2025-04-30

Java RAG 开发环境准备

1. Docker 安装与验证

验证 Docker 是否安装成功：

docker run hello-world

Docker 正常运行时，该命令从 Docker Hub 拉取测试镜像并输出：

Hello from Docker! This message shows that your installation appears to be working correctly.

2. 使用 Docker Compose 搭建 Elasticsearch 和 Qdrant

有了 Docker 环境后，使用 Docker Compose 同时启动 Elasticsearch 和 Qdrant 两个服务容器。在项目目录下创建 docker-compose.yml 文件：

version: '3.8'
services:
  elasticsearch:
    image: docker.elastic.co/elasticsearch/elasticsearch:8.9.0  # 指定Elasticsearch镜像版本
    container_name: elasticsearch
    environment:
      - discovery.type=single-node           # 单节点模式，无需集群配置
      - xpack.security.enabled=false         # 禁用安全认证，方便本地测试
      - bootstrap.memory_lock=false
      - ES_JAVA_OPTS=-Xms1g -Xmx1g           # 限制ES JVM内存
    ulimits:
      memlock:
        soft: -1
        hard: -1
    ports:
      - 9200:9200                            # 映射Elasticsearch端口
  qdrant:
    image: qdrant/qdrant:latest              # 使用最新版本的Qdrant镜像
    container_name: qdrant
    ports:
      - 6333:6333                            # REST API端口（HTTP）
      - 6334:6334                            # gRPC端口（用于Spring AI连接）

启动服务：

docker compose up -d

（或在较早版本使用 docker-compose up -d）

用 docker ps 查看容器状态，两项服务应均为 Up 状态。

验证 Elasticsearch：打开浏览器访问 http://localhost:9200，应返回集群的基本信息：

{"cluster_name":"docker-cluster",...}

由于禁用了安全性，无需认证即可访问。

验证 Qdrant：访问 http://localhost:6333 应显示欢迎页面。进一步验证健康状态：

curl http://localhost:6333/health

健康检查成功返回 Qdrant 的状态信息 JSON。至此向量数据库 Qdrant 和全文检索引擎 Elasticsearch 的环境已就绪。

3. 安装 Java JDK 和 Maven

安装 Java 17 或更高版本的 LTS 发行版（例如 Java 21）。使用 Homebrew：

brew install openjdk@17

将 JDK 的 bin 目录加入环境变量，例如将下面一行添加到 ~/.zshrc：

export PATH="/usr/local/opt/openjdk@17/bin:$PATH"

验证安装：

java -version

安装 Maven：

brew install maven

验证 Maven：

mvn -v

java 和 mvn 命令都应在终端 PATH 中可用。如果找不到命令，检查 shell 配置。

4. 创建 Spring Boot 项目与 Qdrant 支持

使用 IntelliJ IDEA 创建新的 Spring Boot 项目。选择 Create New Project → Spring Initializr，填入：

添加 Spring Web 依赖。项目生成后，编辑 pom.xml 添加 Spring AI Qdrant 依赖：

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-vector-store-qdrant</artifactId>
    <version>1.0.0-M7</version>  <!-- 使用当前最新的版本号 -->
</dependency>

打开 src/main/resources/application.yml 配置 Qdrant：

spring:
  ai:
    vectorstore:
      qdrant:
        host: localhost        # Qdrant 服务主机地址（默认localhost）
        port: 6334             # Qdrant gRPC端口 [oai_citation:4‡docs.spring.io](https://docs.spring.io/spring-ai/reference/api/vectordbs/qdrant.html#:~:text=)
        collection-name: demo_vectors   # 指定向量集合名称
        initialize-schema: true        # 自动初始化集合schema（如果尚未创建集合）

此配置告知 Spring AI：Qdrant 服务跑在本机 gRPC 默认端口 6334，使用名称为 demo_vectors 的集合存储向量，首次连接时自动创建集合。默认开发环境下 Qdrant 无需 API 秘钥认证。

可选：配置 Embedding 模型

要存储和搜索文本向量，需要配置 embedding 模型。添加 OpenAI 集成依赖：

<!-- 在 pom.xml 中添加 OpenAI 集成 -->
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-openai</artifactId>
    <version>1.0.0-M7</version>
</dependency>

然后更新 application.yml：

spring:
  ai:
    model:
      openai:
        api-key: sk-xxx...    # OpenAI API密钥
        embedding-model: text-embedding-ada-002  # 指定使用的嵌入模型名称

Spring AI 会自动创建 OpenAI embedding bean。如果没有 OpenAI API Key，可以跳过此步，改为实现一个简单的 embedding bean 用于测试，或直接调用 Qdrant 接口存储自定义向量。

5. 编写测试 Controller 调用 Qdrant 进行向量存储与检索

在 src/main/java 下创建包（例如 com.example.ragdemo.controller）并添加：

import org.springframework.web.bind.annotation.*;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.ai.embeddings.Document;
import org.springframework.ai.vectordb.VectorStore;
import org.springframework.ai.search.SearchRequest;
import java.util.List;
import java.util.Map;

@RestController
public class VectorTestController {
    @Autowired
    private VectorStore vectorStore;  // 自动注入 Qdrant 向量存储接口

    // 简单GET接口，用于插入向量并检索
    @GetMapping("/test-vector")
    public List<String> testVectorStore() {
        // 1. 构造待插入的文档列表（每个Document包含文本和可选的元数据）
        Document doc = new Document("Spring AI 在向量检索中的应用示例", 
                                    Map.of("source", "test"));
        List<Document> documents = List.of(doc);
        // 2. 将文档添加到 Qdrant 向量库（自动完成向量嵌入并存储）
        vectorStore.add(documents);  // 插入文档向量 [oai_citation:7‡docs.spring.io](https://docs.spring.io/spring-ai/reference/api/vectordbs/qdrant.html#:~:text=List,meta2)

        // 3. 使用相似度搜索检索与查询文本语义相近的文档
        SearchRequest request = SearchRequest.builder()
                                  .query("向量检索示例")  // 查询文本
                                  .topK(5)              // 返回前5个相似结果
                                  .build();
        List<Document> results = vectorStore.similaritySearch(request);  // 执行相似度检索 [oai_citation:8‡docs.spring.io](https://docs.spring.io/spring-ai/reference/api/vectordbs/qdrant.html#:~:text=%2F%2F%20Retrieve%20documents%20similar%20to,topK%285%29.build)

        // 4. 提取结果中文档的内容并返回
        List<String> resultContents = results.stream()
                                      .map(Document::getContent)
                                      .toList();
        return resultContents;
    }
}

此控制器通过 @Autowired 注入 VectorStore（Spring AI 根据配置自动构建 QdrantVectorStore 实例）。/test-vector 端点创建一个文档，通过 vectorStore.add() 将其存储到 Qdrant，然后调用 vectorStore.similaritySearch() 执行相似度检索。查询词"向量检索示例"与插入的文本在语义上接近，故应检索出该文档。

注意： 若未配置 embedding 模型，此步运行时会报错（因无法将文本转换为向量）。确保已配置 OpenAI 或其他 embedding 模型。或者直接使用 QdrantClient 接口存储自定义向量，虽然文本向量更接近实际 RAG 场景。

验证导入的类可用。若 Document、VectorStore 或 SearchRequest 无法导入，检查 Spring AI 依赖是否正确添加且 Maven 已下载。使用 Milestone 版本时，确保 Maven 的 repositories 包含 Spring Milestones 或 Snapshots 仓库，或使用 Spring AI 的 BOM 管理版本。

6. 启动应用并验证整条链路

启动 Spring Boot 应用。在 IntelliJ IDEA 中运行主类，或在项目根目录执行：

mvn spring-boot:run

应用启动时读取配置连接 Qdrant。查看控制台日志确认连接成功。应看到 Started RagDemoApplication in [time] seconds 且无异常。

打开浏览器访问 http://localhost:8080/test-vector。首次调用可能稍有延迟（embedding 生成）。成功返回包含存储文档内容的 JSON 数组：

["Spring AI 在向量检索中的应用示例"]

若检索结果包含插入的文本，表示向量管道完整工作。

故障排查

若接口未正常返回：

现在你已拥有一个工作中的 Java + Spring AI 项目，集成了 Qdrant。此基础支持进一步集成大语言模型调用、完善向量检索与文本检索的结合策略，实现完整的检索增强生成应用。

© 2026 Yuxu Ge ·