Spring Boot SeekDB 向量数据库集成示例

这是一个完整的 Spring Boot 项目，演示如何使用 JDBC 对接 SeekDB 向量数据库，实现向量数据的增删改查、向量语义搜索和混合搜索功能。

📋 项目概述

本项目展示了以下核心功能：

1. 向量 CRUD 操作 - 使用 LangChain4j + OpenAI Embedding 自动生成向量
2. 向量语义搜索 - 基于向量相似度的语义检索（支持近似和精确搜索）
3. 混合搜索 - 结合关键词匹配和向量语义的混合检索（支持 RRF 排序）

🛠️ 技术栈

• Spring Boot 3.5.10 - 主框架
• JDBC Template - 数据库操作
• MySQL Driver - SeekDB 兼容 MySQL 协议
• LangChain4j 0.36.2 - AI 集成框架
• OpenAI API - Embedding 向量生成（text-embedding-ada-002，1536维）
• Lombok - 简化代码
• JUnit 5 - 单元测试

📁 项目结构

src/main/java/com/example/springboot/seekdb/
├── config/              # 配置类
│   └── AppConfiguration.java
├── entity/              # 实体类
│   └── Document.java
├── dto/                 # 数据传输对象
│   ├── SearchResult.java
│   └── HybridSearchResult.java
├── repository/          # 数据访问层
│   └── DocumentRepository.java
└── service/             # 业务逻辑层
    ├── VectorCrudService.java       # CRUD 服务
    ├── VectorSearchService.java     # 向量搜索服务
    └── HybridSearchService.java     # 混合搜索服务

src/test/java/com/example/springboot/seekdb/service/
├── VectorCrudServiceTest.java       # CRUD 测试
├── VectorSearchServiceTest.java     # 向量搜索测试
└── HybridSearchServiceTest.java     # 混合搜索测试

🚀 快速开始

前置要求

1. JDK 17+
2. Maven 3.6+
3. SeekDB 数据库 - 确保已安装并运行
4. OpenAI API Key - 用于生成 Embedding 向量

步骤 1: 配置数据库连接

编辑 src/main/resources/application.yml：

spring:
  datasource:
    # TODO: 替换为你的 SeekDB 连接信息
    url: jdbc:mysql://your-seekdb-host:3306/your_database?useSSL=false&serverTimezone=UTC
    username: your_username
    password: your_password

步骤 2: 配置 OpenAI API Key

两种方式：

方式 1: 环境变量（推荐）

export OPENAI_API_KEY=sk-your-api-key-here

方式 2: 直接配置 编辑 application.yml：

langchain4j:
  open-ai:
    embedding-model:
      api-key: sk-your-api-key-here

步骤 3: 初始化数据库表

在 SeekDB 中执行 src/main/resources/schema.sql 创建表结构：

-- 创建文档表
CREATE TABLE documents (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    title VARCHAR(500) NOT NULL,
    content TEXT NOT NULL,
    vector VECTOR(1536) NOT NULL,  -- OpenAI text-embedding-ada-002
    metadata JSON,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);

-- 创建向量索引
CREATE VECTOR INDEX idx_vector_hnsw ON documents(vector)
WITH (distance=l2, type=hnsw);

步骤 4: 运行测试

# 运行所有测试
mvn test

# 运行特定测试
mvn test -Dtest=VectorCrudServiceTest
mvn test -Dtest=VectorSearchServiceTest
mvn test -Dtest=HybridSearchServiceTest

📚 功能说明

1️⃣ 向量 CRUD 操作

VectorCrudService 提供以下功能：

// 创建文档（自动生成向量）
Long id = vectorCrudService.createDocument(
    "Introduction to AI",
    "Artificial Intelligence is transforming the world...",
    "{\"category\": \"technology\"}"
);

// 查询文档
Optional<Document> doc = vectorCrudService.getDocumentById(id);

// 更新文档（重新生成向量）
vectorCrudService.updateDocument(id, newTitle, newContent, newMetadata);

// 删除文档
vectorCrudService.deleteDocument(id);

核心特性：

• ✅ 自动调用 OpenAI Embedding API 生成向量
• ✅ 支持 JSON 格式元数据存储
• ✅ 完整的增删改查操作
• ✅ 向量维度：1536（text-embedding-ada-002）

2️⃣ 向量语义搜索

VectorSearchService 提供三种搜索方式：

// 方式1: 近似搜索（使用向量索引，速度快）
List<SearchResult> results = vectorSearchService.semanticSearchApproximate(
    "What is machine learning?",
    5  // Top 5
);

// 方式2: 精确搜索（全表扫描，结果精确）
List<SearchResult> results = vectorSearchService.semanticSearchExact(
    "What is machine learning?",
    5
);

// 方式3: 文本搜索（SeekDB 自动处理向量转换）
List<SearchResult> results = vectorSearchService.semanticSearchWithText(
    "What is machine learning?",
    5
);

核心特性：

• ✅ 使用 semantic_vector_distance 函数
• ✅ 支持 L2 距离计算
• ✅ APPROXIMATE 关键字利用 HNSW 索引加速
• ✅ 返回距离得分和排名

3️⃣ 混合搜索

HybridSearchService 结合关键词和语义：

// 基础混合搜索
List<HybridSearchResult> results = hybridSearchService.hybridSearch(
    "Apple iPhone camera",
    5,
    false  // 不使用 RRF
);

// 使用 RRF 排序的混合搜索
List<HybridSearchResult> results = hybridSearchService.hybridSearch(
    "Apple iPhone camera",
    5,
    true  // 使用 RRF
);

// 多字段混合搜索
List<HybridSearchResult> results = hybridSearchService.hybridSearchMultiField(
    "MacBook",                           // 标题查询
    "laptop for developers",             // 内容查询
    3
);

核心特性：

• ✅ 使用 DBMS_HYBRID_SEARCH.SEARCH() 函数
• ✅ 关键词匹配 + 向量语义双重检索
• ✅ 支持 RRF（Reciprocal Rank Fusion）排序
• ✅ 返回综合得分、关键词得分、语义得分

🧪 测试用例

VectorCrudServiceTest

• ✅ 创建文档并生成向量
• ✅ 查询单个文档
• ✅ 查询所有文档
• ✅ 更新文档并重新生成向量
• ✅ 删除文档
• ✅ 统计文档数量
• ✅ 完整的 CRUD 工作流程

VectorSearchServiceTest

• ✅ 近似语义搜索
• ✅ 精确语义搜索
• ✅ 文本语义搜索
• ✅ 比较近似和精确搜索结果
• ✅ 测试不同 TopK 值
• ✅ 语义相似度验证
• ✅ 完整的搜索工作流程

HybridSearchServiceTest

• ✅ 基础混合搜索
• ✅ 使用 RRF 排序
• ✅ 多字段混合搜索
• ✅ 比较有无 RRF 的结果
• ✅ 测试关键词权重
• ✅ 测试语义权重
• ✅ 复杂混合查询场景
• ✅ 完整的混合搜索工作流程

📖 SeekDB 官方文档参考

• 向量数据存储
• 向量语义搜索
• 混合搜索

🔍 常见问题

Q1: 如何切换 Embedding 模型？

修改 application.yml：

langchain4j:
  open-ai:
    embedding-model:
      model-name: text-embedding-3-small  # 更快、更便宜
      # model-name: text-embedding-3-large  # 3072维，更高质量

注意： 切换模型后需要同步修改数据库表的向量维度！

Q2: 如何使用其他 Embedding 提供商？

LangChain4j 支持多种提供商：

<!-- Azure OpenAI -->
<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-azure-open-ai</artifactId>
</dependency>

<!-- Ollama (本地部署) -->
<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-ollama</artifactId>
</dependency>