Skip to content

Commit a3007d6

Browse files
siyuan-sysiyuan-sy
authored
支持使用 MariaDB 作为向量库 (#23)
* 提交mariadb代码
1 parent f9ed8be commit a3007d6

File tree

8 files changed

+431
-0
lines changed

8 files changed

+431
-0
lines changed

‎spring-ai-vector/pom.xml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@
1313
<modules>
1414
<module>spring-ai-vector-milvus</module>
1515
<module>spring-ai-vector-redis</module>
16+
<module>spring-ai-vector-mariadb</module>
1617
</modules>
1718

1819
<dependencies>

‎spring-ai-vector/spring-ai-vector-mariadb/README.md

Lines changed: 226 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,226 @@
1+
# `spring-ai-vector-mariadb` 文档
2+
3+
## 1. 概述
4+
5+
本模块 `spring-ai-vector-mariadb` 提供了一个基于 **MariaDB** 的向量存储实现，支持将高维向量数据存入 MariaDB 数据库，并能够执行相似性搜索（如余弦相似度）。适用于需要结合关系型数据库和 AI 向量能力的场景。
6+
7+
该项目集成了 [Spring AI](https://docs.spring.io/spring-ai/reference/html/) 和 [MariaDB](https://mariadb.org/)，为开发者提供了一个快速上手的向量存储解决方案。
8+
9+
---
10+
11+
## 2. 功能特性
12+
13+
- 使用 MariaDB 存储文档及其向量表示
14+
- 支持通过 Spring Boot 自动配置向量数据库连接
15+
- 提供简单的 CRUD 操作（增删查）
16+
- 支持基于余弦相似度的向量检索
17+
- 集成 OpenAI 兼容的嵌入模型接口（如阿里云 DashScope）
18+
19+
---
20+
21+
## 3. 技术栈
22+
23+
| 技术 | 版本/说明 |
24+
|------|---------------------------------------------|
25+
| Java | JDK 21+ |
26+
| Spring Boot | 最新稳定版本 |
27+
| Spring AI | 集成 `spring-ai-starter-vector-store-mariadb` |
28+
| MariaDB | 使用 JDBC 客户端 `mariadb-java-client:3.5.2` |
29+
| 嵌入模型 | 支持 OpenAI 接口兼容模型，如阿里云 DashScope |
30+
31+
---
32+
33+
## 4. 项目结构
34+
35+
```
36+
spring-ai-vector-mariadb/
37+
├── src/
38+
│ ├── main/
39+
│ │ ├── java/
40+
│ │ │ └── com.glmapper.ai.vector/
41+
│ │ │ ├── MariadbVectorApplication.java # 应用启动类
42+
│ │ │ └── storage/
43+
│ │ │ └── VectorStoreStorage.java # 向量存储业务逻辑封装
44+
│ │ └── resources/
45+
│ │ └── application.yml # 主配置文件
46+
│ └── test/
47+
│ ├── java/
48+
│ │ └── storage/
49+
│ │ └── VectorStoreStorageTest.java # 单元测试类
50+
│ └── resources/
51+
│ └── application-test.yml # 测试环境配置文件
52+
├── README.md # 项目说明文档（当前文件）
53+
└── pom.xml # Maven 构建配置
54+
```
55+
56+
57+
---
58+
59+
## 5. 环境依赖与准备
60+
61+
### 5.1 MariaDB 数据库部署
62+
63+
推荐使用 Docker 快速部署 MariaDB 实例：
64+
65+
```bash
66+
docker run -d \
67+
--name mariadb \
68+
-e MYSQL_ROOT_PASSWORD=root \
69+
-p 3306:3306 \
70+
mariadb:latest
71+
```
72+
73+
74+
① 初始化数据库并创建用于向量存储的表结构（可由 Spring Boot 自动完成）。
75+
76+
② 一个 `EmbeddingModel` 实例，用于计算文档嵌入。有多个[选项](https://docs.spring.io/spring-ai/reference/api/embeddings.html#available-implementations)可供选择
77+
78+
③ 一个 API 密钥，给 EmbeddingModel 用于生成向量数据
79+
> 注意：确保在 `application.yml` 中配置正确的数据库连接地址、用户名和密码。
80+
81+
---
82+
83+
## 6. 配置说明
84+
85+
### 6.1 核心配置 (`application.yml`)
86+
87+
```yaml
88+
server:
89+
port: 8080
90+
91+
spring:
92+
datasource:
93+
url: ${BASE_HOST} # 如 jdbc:mariadb://localhost:3308/vector_test
94+
username: ${BASE_NAME}
95+
password: ${BASE_PWD}
96+
driver-class-name: org.mariadb.jdbc.Driver
97+
98+
ai:
99+
vectorstore:
100+
mariadb:
101+
initialize-schema: true # 是否自动初始化表结构
102+
distance-type: COSINE # 距离计算类型
103+
dimensions: 1536 # 向量维度
104+
openai:
105+
api-key: ${API_KEY} # 嵌入模型 API Key
106+
embedding:
107+
base-url: https://dashscope.aliyuncs.com/compatible-mode/v1
108+
embeddings-path: /embeddings
109+
options:
110+
model: text-embedding-v4 # 使用的嵌入模型
111+
```
112+
113+
114+
### 6.2 测试环境配置 (`application-test.yml`)
115+
116+
```yaml
117+
spring:
118+
datasource:
119+
url: jdbc:mariadb://localhost:3308/vector_test
120+
username: root
121+
password: root
122+
ai:
123+
vectorstore:
124+
mariadb:
125+
initialize-schema: false # 不再初始化 schema
126+
```
127+
128+
129+
---
130+
131+
## 7. 核心类说明
132+
133+
### 7.1 `MariadbVectorApplication.java`
134+
135+
主应用启动类，使用 `@SpringBootApplication` 注解启用 Spring Boot 自动配置。
136+
137+
### 7.2 `VectorStoreStorage.java`
138+
139+
封装了对向量存储的操作，包括：
140+
141+
- `store(List<Document>)`: 将文档及向量存入数据库
142+
- `search(String)`: 执行相似性搜索，返回匹配结果
143+
- `delete(Set<String>)`: 删除指定 ID 的向量记录
144+
145+
依赖注入 `VectorStore` 实现具体的向量操作逻辑。
146+
147+
---
148+
149+
## 8. 单元测试
150+
151+
### 8.1 `VectorStoreStorageTest.java`
152+
153+
单元测试验证向量存储与搜索功能是否正常。测试步骤如下：
154+
155+
1. 插入预定义文档
156+
2. 执行相似性搜索
157+
3. 验证结果非空
158+
4. 清理数据（每个测试后删除插入的数据）
159+
160+
运行命令：
161+
162+
```bash
163+
mvn test
164+
```
165+
166+
167+
---
168+
169+
## 9. 使用指南
170+
171+
### 9.1 启动应用
172+
173+
确保已正确配置数据库连接信息和 API 密钥后，直接运行：
174+
175+
```bash
176+
mvn spring-boot:run
177+
```
178+
179+
180+
或在 IDE（如 IntelliJ IDEA）中运行 `MariadbVectorApplication` 类。
181+
182+
### 9.2 示例调用
183+
184+
你可以通过 REST API 或自定义服务调用 [VectorStoreStorage](spring-ai-vector/spring-ai-vector-mariadb/src/main/java/com/glmapper/ai/vector/storage/VectorStoreStorage.java) 方法进行文档存储与查询。
185+
186+
---
187+
188+
## 10. 依赖管理
189+
190+
### 10.1 Maven 依赖 ([pom.xml](spring-ai-vector/spring-ai-vector-mariadb/pom.xml))
191+
192+
```xml
193+
<dependency>
194+
<groupId>org.springframework.ai</groupId>
195+
<artifactId>spring-ai-starter-vector-store-mariadb</artifactId>
196+
</dependency>
197+
198+
<dependency>
199+
<groupId>org.mariadb.jdbc</groupId>
200+
<artifactId>mariadb-java-client</artifactId>
201+
<version>3.5.2</version>
202+
</dependency>
203+
```
204+
205+
206+
---
207+
208+
## 11. 注意事项
209+
210+
- 确保 MariaDB 已正确安装并启动。
211+
- 如果遇到 SQL 异常，请检查 `initialize-schema` 设置以及数据库权限。
212+
- 向量维度需与使用的 Embedding 模型一致（默认为 1536）。
213+
- 在生产环境中应关闭 `initialize-schema`，避免误删数据。
214+
215+
---
216+
217+
## 12. 参考资料
218+
219+
- [Spring AI 文档](https://docs.spring.io/spring-ai/reference/html/)
220+
- [MariaDB 官方文档](https://mariadb.org/documentation/)
221+
- [DashScope 开发者文档](https://help.aliyun.com/zh/dashscope/developer-reference/introduction)
222+
- [Docker Hub - MariaDB](https://hub.docker.com/_/mariadb)
223+
224+
---
225+
226+
如有问题或建议，请联系维护人员。

‎spring-ai-vector/spring-ai-vector-mariadb/pom.xml

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<project xmlns="http://maven.apache.org/POM/4.0.0"
3+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
4+
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
5+
<modelVersion>4.0.0</modelVersion>
6+
<parent>
7+
<groupId>com.glmapper</groupId>
8+
<artifactId>spring-ai-vector</artifactId>
9+
<version>0.0.1</version>
10+
</parent>
11+
12+
<artifactId>spring-ai-vector-mariadb</artifactId>
13+
<packaging>jar</packaging>
14+
15+
<properties>
16+
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
17+
</properties>
18+
19+
<dependencies>
20+
21+
<dependency>
22+
<groupId>org.springframework.ai</groupId>
23+
<artifactId>spring-ai-starter-vector-store-mariadb</artifactId>
24+
<exclusions>
25+
<exclusion>
26+
<groupId>org.mariadb.jdbc</groupId>
27+
<artifactId>mariadb-java-client</artifactId>
28+
</exclusion>
29+
</exclusions>
30+
</dependency>
31+
<!-- 3.3版本缺少enquoteIdentifier方法, springAI 自动调用失败,引入最新版本client -->
32+
<dependency>
33+
<groupId>org.mariadb.jdbc</groupId>
34+
<artifactId>mariadb-java-client</artifactId>
35+
<version>3.5.2</version>
36+
</dependency>
37+
</dependencies>
38+
</project>

‎spring-ai-vector/spring-ai-vector-mariadb/src/main/java/com/glmapper/ai/vector/MariadbVectorApplication.java

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
package com.glmapper.ai.vector;
2+
3+
import org.springframework.boot.SpringApplication;
4+
import org.springframework.boot.autoconfigure.SpringBootApplication;
5+
6+
/**
7+
* @author siyuan
8+
* @since 2025/6/14
9+
*/
10+
@SpringBootApplication
11+
public class MariadbVectorApplication {
12+
public static void main(String[] args) {
13+
SpringApplication.run(MariadbVectorApplication.class, args);
14+
}
15+
}

‎spring-ai-vector/spring-ai-vector-mariadb/src/main/java/com/glmapper/ai/vector/storage/VectorStoreStorage.java

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
package com.glmapper.ai.vector.storage;
2+
3+
import lombok.RequiredArgsConstructor;
4+
import org.springframework.ai.document.Document;
5+
import org.springframework.ai.vectorstore.SearchRequest;
6+
import org.springframework.ai.vectorstore.VectorStore;
7+
import org.springframework.stereotype.Component;
8+
9+
import java.util.ArrayList;
10+
import java.util.List;
11+
import java.util.Set;
12+
13+
/**
14+
* @author siyuan
15+
* @since 2025/6/14
16+
*/
17+
@Component
18+
@RequiredArgsConstructor
19+
public class VectorStoreStorage {
20+
21+
private final VectorStore vectorStore;
22+
23+
24+
public void delete(Set<String> ids) {
25+
vectorStore.delete(new ArrayList<>(ids));
26+
}
27+
28+
public void store(List<Document> documents) {
29+
if (documents == null || documents.isEmpty()) {
30+
return;
31+
}
32+
vectorStore.add(documents);
33+
}
34+
35+
public List<Document> search(String query) {
36+
return vectorStore.similaritySearch(SearchRequest.builder().query(query).topK(5).build());
37+
}
38+
}

‎spring-ai-vector/spring-ai-vector-mariadb/src/main/resources/application.yml

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
server:
2+
port: 8080
3+
4+
spring:
5+
application:
6+
name: mariadb-vector-store
7+
datasource:
8+
url: ${BASE_HOST}
9+
username: ${BASE_NAME}
10+
password: ${BASE_PWD}
11+
driver-class-name: org.mariadb.jdbc.Driver
12+
ai:
13+
vectorstore:
14+
mariadb:
15+
# 启用模式初始化
16+
initialize-schema: true
17+
# 设置距离计算类型为余弦相似度
18+
distance-type: COSINE
19+
# 定义向量维度为1536
20+
dimensions: 1536
21+
openai:
22+
api-key: ${API_KEY}
23+
embedding:
24+
base-url: https://dashscope.aliyuncs.com/compatible-mode/v1
25+
embeddings-path: /embeddings
26+
options:
27+
model: text-embedding-v4

0 commit comments

Comments
 (0)