---
title: "OceanBase 数据库 Vector 与 Spring AI Alibaba 集成 - OceanBase 数据库 V4.3.5 | OceanBase 文档中心"
description: OceanBase 数据库 Vector 与 Spring AI Alibaba 集成 OceanBase 数据库从 V4.3.3 开始支持向量类型存储、向量索引、embedding 向量搜索的能力。可以将向量化后的数据存储在 OceanBase 数据库，供下一步的搜索使用。 Spring AI Alibaba 开源…
---
切换语言

- 中文站 - 简体中文
- International - English
- 日本站 - 日本語

文档反馈![](https://mdn.alipayobjects.com/huamei_22khvb/afts/img/A*P8CuR4UJ_FkAAAAAAAAAAAAADiGDAQ/original) OceanBase 数据库分布式版 - V 4.3.5 LTS

# OceanBase 数据库 Vector 与 Spring AI Alibaba 集成

更新时间：2026-04-09 14:12:04

[编辑](https://github.com/oceanbase/oceanbase-doc/edit/V4.3.5/zh-CN/680.ecological-integration/1100.AI/800.springai.md)  

OceanBase 数据库从 V4.3.3 开始支持向量类型存储、向量索引、embedding 向量搜索的能力。可以将向量化后的数据存储在 OceanBase 数据库，供下一步的搜索使用。

Spring AI Alibaba 开源项目基于 Spring AI 构建，是阿里云通义系列模型及服务在 Java AI 应用开发领域的最佳实践。它简化了 AI 应用的开发流程，并适应云原生的基础设施，可以帮助开发者快速构建 AI 应用。

本文将展示如何将 Spring AI Alibaba 与 OceanBase 数据库向量搜索能力集成，实现数据导入和相似性搜索功能。通过配置向量存储和搜索服务，开发者可以轻松构建基于 OceanBase 数据库的 AI 应用场景，支持文本相似度搜索、内容推荐等高级功能。

## 前提条件

- 您已完成部署 OceanBase 数据库并且创建了 MySQL 模式用户租户。创建用户租户的详细信息，参见 [创建租户](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000002013128)。

     - 确保您已经在租户中设置了 `ob_vector_memory_limit_percentage` 配置项，以启用向量搜索功能。V4.3.5 BP3 之前的版本推荐设置值为 `30`，从 V4.3.5 BP3 版本开始推荐保持默认值 `0`。如需更精确设置此配置项，请参考 [ob_vector_memory_limit_percentage](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000002015585) 计算此值。
 - 下载 [JDK 17+](https://www.oracle.com/java/technologies/downloads/#java17)。确保安装 Java 17 并配置环境变量。
 - 下载 [Maven](https://dlcdn.apache.org/maven/)。确保安装 Maven 3.6+，以构建项目和管理依赖。
 - 下载 [IntelliJ IDEA](https://www.jetbrains.com/idea/download/) 或 [Eclipse](https://www.eclipse.org/downloads/)，根据自己的操作系统选择合适的版本进行安装。

## 步骤一：获取数据库连接信息

联系 OceanBase 数据库部署人员或者管理员获取相应的数据库连接串，例如：

```sql
obclient -h$host -P$port -u$user_name -p$password -D$database_name

```

**参数说明：**

- `$host`：提供 OceanBase 数据库连接 IP。OceanBase 数据库代理（OceanBase Database Proxy，ODP）连接方式使用的是一个 ODP 地址；直连方式使用的是 OBServer 节点的 IP 地址。
 - `$port`：提供 OceanBase 数据库连接端口。ODP 连接的方式默认是 `2883`，在部署 ODP 时可自定义；直连方式默认是 `2881`，在部署 OceanBase 数据库时可自定义。
 - `$database_name`：需要访问的数据库名称。

  #### 注意

  连接租户的用户需要拥有该数据库的 `CREATE`、`INSERT`、`DROP` 和 `SELECT` 权限。更多有关用户权限的信息，请参见 [MySQL 模式下的权限分类](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000002016100)。
 - `$user_name`：提供租户的连接账户。ODP 连接的常用格式：`用户名@租户名#集群名` 或者 `集群名:租户名:用户名`；直连方式格式：`用户名@租户名`。
 - `$password`：提供账户密码。

更多连接串的信息，请参见 [通过 OBClient 连接 OceanBase 租户](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000002013251)。

## 步骤二：搭建 Maven 项目

Maven 是本文将用到的项目管理和构建工具。在此步骤创建一个 Maven 项目，并通过配置 `pom.xml` 文件添加项目依赖。

### 创建项目

1. 使用 Maven 命令创建项目。

   ```shell
   mvn archetype:generate -DgroupId=com.alibaba.cloud.ai.example -DartifactId=vector-oceanbase-example -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false

   ```
 2. 进入项目目录。

   ```shell
   cd vector-oceanbase-example

   ```

### 配置 `pom.xml` 文件

`pom.xml` 文件是 Maven 项目的核心配置文件，用于管理项目的依赖、插件、构建配置等信息。接下来，你需要修改 `pom.xml` 文件，添加 Spring AI Alibaba、OceanBase 向量存储以及其他必要的依赖。

打开 `pom.xml` 文件，并将以下内容替换原有内容。

```xml
    <project xmlns="http://maven.apache.org/POM/4.0.0"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
        <modelVersion>4.0.0</modelVersion>
        <parent>
            <groupId>com.alibaba.cloud.ai.example</groupId>
            <artifactId>spring-ai-alibaba-vector-databases-example</artifactId>
            <version>1.0.0</version>
        </parent>

        <artifactId>vector-oceanbase-example</artifactId>

        <properties>
            <maven.compiler.source>17</maven.compiler.source>
            <maven.compiler.target>17</maven.compiler.target>
            <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        </properties>

        <dependencies>
            <!-- 阿里云 AI Starter -->
            <dependency>
                <groupId>com.alibaba.cloud.ai</groupId>
                <artifactId>spring-ai-alibaba-starter</artifactId>
            </dependency>

            <!-- Spring Boot Web 支持 -->
            <dependency>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-starter-web</artifactId>
            </dependency>

            <!-- Spring AI 自动配置 -->
            <dependency>
                <groupId>org.springframework.ai</groupId>
                <artifactId>spring-ai-spring-boot-autoconfigure</artifactId>
            </dependency>

            <!-- Spring JDBC 支持 -->
            <dependency>
                <groupId>org.springframework</groupId>
                <artifactId>spring-jdbc</artifactId>
            </dependency>

            <!-- Transformers 模型支持 -->
            <dependency>
                <groupId>org.springframework.ai</groupId>
                <artifactId>spring-ai-transformers</artifactId>
            </dependency>

            <!-- OceanBase 向量数据库 Starter -->
            <dependency>
                <groupId>com.alibaba.cloud.ai</groupId>
                <artifactId>spring-ai-alibaba-starter-oceanbase-store</artifactId>
                <version>1.0.0-M6.2-SNAPSHOT</version>
            </dependency>

            <!-- OceanBase JDBC 驱动 -->
            <dependency>
                <groupId>com.oceanbase</groupId>
                <artifactId>oceanbase-client</artifactId>
                <version>2.4.14</version>
            </dependency>
        </dependencies>

        <!-- SNAPSHOT 仓库配置 -->
        <repositories>
            <repository>
                <id>sonatype-snapshots</id>
                <url>https://oss.sonatype.org/content/repositories/snapshots/</url>
                <releases>
                    <enabled>false</enabled>
                </releases>
                <snapshots>
                    <enabled>true</enabled>
                </snapshots>
            </repository>
        </repositories>
    </project>

```

## 步骤三：配置 OceanBase 数据库连接信息

此步骤配置 `application.yml` 文件，以添加 OceanBase 数据库连接信息。

在项目 `src/main/resources` 目录下创建 `application.yml` 文件，添加以下内容：

```yaml
server:
  port: 8080

spring:
  application:
    name: oceanbase-example
  ai:
    dashscope:
      api-key: ${DASHSCOPE_API_KEY}  # 替换为你的 DashScope API Key
    vectorstore:
      oceanbase:
        enabled: true
        url: jdbc:oceanbase://xxx:xxx/xxx  # OceanBase 连接 URL
        username: xxx                     # OceanBase 用户名
        password: xxx                     # OceanBase 密码
        tableName: vector_table           # 向量表名（自动创建）
        defaultTopK: 2                    # 默认返回相似结果数量
        defaultSimilarityThreshold: 0.8   # 相似度阈值（0~1，值越小越相似）

```

## 步骤四：创建主应用程序类和控制器

创建 Spring Boot 应用程序的启动类和控制器类，实现数据导入和相似性搜索功能。

### 创建应用程序启动类

在项目 `src/main/java/com/alibaba/cloud/ai/example/vector` 目录下创建 `OceanBaseApplication.java` 文件，添加以下内容：

```java
package com.alibaba.cloud.ai.example.vector;  // 包名需要与目录结构保持一致

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication  // 启用 Spring Boot 自动配置
public class OceanBaseApplication {
    public static void main(String[] args) {
        SpringApplication.run(OceanBaseApplication.class, args);  // 启动 Spring Boot 应用
    }
}

```

示例代码为项目的核心启动类，用于启动 Spring Boot 应用程序。

### 创建向量存储控制器

在项目 `src/main/java/com/alibaba/cloud/ai/example/vector` 目录下创建 `OceanBaseController.java` 文件，添加以下内容：

```java
package com.alibaba.cloud.ai.example.vector.controller;  // 包名需要与目录结构保持一致

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.ai.document.Document;
import org.springframework.ai.vectorstore.SearchRequest;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.HashMap;
import java.util.List;
import java.util.Map;

import com.alibaba.cloud.ai.vectorstore.oceanbase.OceanBaseVectorStore;

@RestController  // 标记为 REST 控制器
@RequestMapping("/oceanbase")  // 设置基础路径为 /oceanbase
public class OceanBaseController {

    private static final Logger logger = LoggerFactory.getLogger(OceanBaseController.class);  // 日志记录器

    @Autowired  // 自动注入 OceanBase 向量存储服务
    private OceanBaseVectorStore oceanBaseVectorStore;

    // 导入数据的接口
    @GetMapping("/import")
    public void importData() {
        logger.info("Start importing data");

        // 创建示例数据
        HashMap<String, Object> map = new HashMap<>();
        map.put("id", "12345");
        map.put("year", "2025");
        map.put("name", "yingzi");

        // 创建包含三个文档的列表
        List<Document> documents = List.of(
            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("year", 2024)),
            new Document("Spring AI rocks!! Spring AI rocks!! Spring AI rocks!! Spring AI rocks!! Spring AI rocks!!", map)
        );

        // 将文档添加到向量存储中
        oceanBaseVectorStore.add(documents);
    }

    // 搜索相似文档的接口
    @GetMapping("/search")
    public List<Document> search() {
        logger.info("Start searching data");

        // 执行相似性搜索，查询包含 "Spring" 的文档，返回最相似的前 2 个结果
        return oceanBaseVectorStore.similaritySearch(SearchRequest.builder()
                                                     .query("Spring")
                                                     .topK(2)
                                                     .build());
    }
}

```

## 步骤五：启动与测试 Maven 项目

### 使用 IDE 启动项目

本文以 IntelliJ IDEA 为例，介绍如何使用 IDE 启动项目。

具体步骤如下：

1. 打开项目：`File` -> `Open` -> 选择 `pom.xml`。
 2. 选中 `作为一个项目打开`。
 3. 找到主类 `OceanBaseApplication.java`。
 4. 右键点击 `Run 'OceanBaseApplication.main()'`。

### 测试项目

1. 访问以下 URL 导入测试数据：

   ```shell
   http://localhost:8080/oceanbase/import

   ```
 2. 访问以下 URL 进行向量搜索：

   ```shell
   http://localhost:8080/oceanbase/search

   ```

   预期返回结果：

   ```json
   [
       {
           "id": "03fe9aad-13cc-4d25-807b-ca1bc314f571",
           "text": "Spring AI rocks!! Spring AI rocks!! Spring AI rocks!! Spring AI rocks!! Spring AI rocks!!",
           "metadata": {
               "name": "yingzi",
               "id": "12345",
               "year": "2025",
               "distance": "7.274442499114312"
           }
       },
       {
           "id": "75864954-0a23-4fa1-8e18-b78fd870d474",
           "text": "Spring AI rocks!! Spring AI rocks!! Spring AI rocks!! Spring AI rocks!! Spring AI rocks!!",
           "metadata": {
               "name": "yingzi",
               "id": "12345",
               "year": "2025",
               "distance": "7.274442499114312"
           }
       }
   ]

   ```

## 常见问题

### OceanBase 数据库连接失败

- 原因：URL、用户名或密码错误。
 - 解决方法：检查 `application.yml` 中的 OceanBase 配置，确保数据库服务已启动。

### 依赖冲突

- 原因：多个 Spring Boot 版本冲突。
 - 解决方法：使用 `mvn dependency:tree` 查看依赖树，排除冲突版本。

### SNAPSHOT 依赖无法下载

- 原因：未配置 SNAPSHOT 仓库。
 - 解决方法：确保 `pom.xml` 中已添加 `sonatype-snapshots` 仓库。

 上一篇 下一篇 ![有帮助](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*y6ocSqN8cqsAAAAAAAAAAAAAARQnAQ)![无帮助](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*BG9IQJyLHF8AAAAAAAAAAAAAARQnAQ)![反馈](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*eTWdQKCRKHwAAAAAAAAAAAAAARQnAQ)[AI](https://www.oceanbase.com/obi) 咨询热线