Spring AI|V4.4.2|OceanBaseデータベース|OceanBaseデータベースドキュメント|分散データベース

OceanBaseデータベースは、バージョンV4.3.3からベクトル型データの格納、ベクトルインデックス、そしてembeddingベクトル検索機能をサポートしています。これにより、ベクトル化したデータをOceanBaseデータベースに保存し、次の検索処理で利用できるようになりました。

Spring AI Alibabaは、Spring AIを基盤として構築されたオープンソースプロジェクトであり、Alibaba CloudのTongyiシリーズモデルおよびサービスをJava AIアプリケーション開発で活用するためのベストプラクティスです。このプロジェクトはAIアプリケーションの開発プロセスを簡素化し、クラウドネイティブなインフラに適応させることで、開発者が迅速にAIアプリケーションを構築できるよう支援します。

本記事では、Spring AI AlibabaとOceanBaseデータベースのベクトル検索機能を連携させ、データのインポートと類似性検索機能を実現する方法を紹介します。ベクトルストレージと検索サービスを設定することで、開発者はOceanBaseデータベースを基盤としたAIアプリケーションシナリオを容易に構築でき、テキスト類似度検索やコンテンツ推薦などの高度な機能をサポートできます。

前提条件

OceanBaseデータベースのデプロイが完了し、MySQLモードのユーザーテナントが作成されていること。テナント作成の詳細については、テナントの作成を参照してください。
- ベクトル検索機能を有効にするために、テナントで ob_vector_memory_limit_percentage 構成パラメータを設定していること。推奨値は 30 です。より正確にこの構成パラメータを設定する必要がある場合は、ob_vector_memory_limit_percentage を参照してこの値を計算してください。
JDK 17+をダウンロードします。Java 17をインストールし、環境変数を設定していることを確認してください。
Mavenをダウンロードします。プロジェクトのビルドと依存関係の管理のため、Maven 3.6+ をインストールしていることを確認してください。
IntelliJ IDEAまたはEclipseをダウンロードし、お使いのOSに合ったバージョンを選択してインストールします。

ステップ１：データベース接続情報を取得する

OceanBaseデータベースのデプロイ担当者または管理者から、該当するデータベース接続文字列を取得します。例：

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モードの権限分類を参照してください。
$user_name：テナントの接続アカウント。ODP接続の一般的な形式：ユーザー名@テナント名#クラスタ名またはクラスタ名:テナント名:ユーザー名。直接接続方式の形式：ユーザー名@テナント名。
$password：アカウントのパスワード。

接続文字列の詳細については、OBClientを使用したOceanBaseテナントへの接続を参照してください。

ステップ2：Mavenプロジェクトの構築

Mavenは、本記事で使用するプロジェクト管理およびビルドツールです。このステップでは、Mavenプロジェクトを作成し、pom.xml ファイルを設定してプロジェクトの依存関係を追加します。

プロジェクトの作成

Mavenコマンドを使用してプロジェクトを作成します。

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

プロジェクトのディレクトリに移動します。
```
cd vector-oceanbase-example
```

`pom.xml`ファイルの設定

pom.xmlファイルはMavenプロジェクトの中心的な設定ファイルであり、プロジェクトの依存関係、プラグイン、ビルド設定などの情報を管理します。次に、pom.xmlファイルを修正し、Spring AI Alibaba、OceanBaseベクトルストレージ、およびその他の必要な依存関係を追加する必要があります。

pom.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>

ステップ3：OceanBaseデータベース接続情報を設定する

このステップでは、application.yml ファイルを設定し、OceanBaseデータベースの接続情報を追加します。

プロジェクトの src/main/resources ディレクトリに application.yml ファイルを作成し、以下の内容を追加します：

server:
  port: 8080

spring:
  application:
    name: oceanbase-example
  ai:
    dashscope:
      api-key: ${DASHSCOPE_API_KEY}  # あなたのDashScope APIキーに置き換えてください
    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、値が小さいほど類似）

ステップ4：メインアプリケーションクラスとコントローラーを作成する

Spring Bootアプリケーションの起動クラスとコントローラークラスを作成し、データインポートおよび類似性検索機能を実装します。

アプリケーション起動クラスの作成

プロジェクトの src/main/java/com/alibaba/cloud/ai/example/vector ディレクトリに OceanBaseApplication.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ファイルを作成し、以下の内容を追加します：

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");

        // 3つのドキュメントを含むリストを作成
        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());
    }
}

ステップ5：Mavenプロジェクトの起動とテスト

IDEを使用したプロジェクトの起動

本記事では、IntelliJ IDEAを例に、IDEを使用してプロジェクトを起動する方法を説明します。

具体的な手順は以下のとおりです：

プロジェクトを開く：File -> Open -> pom.xmlを選択します。
プロジェクトとして開くを選択します。
メインクラスOceanBaseApplication.javaを見つけます。
右クリックしてRun 'OceanBaseApplication.main()'を選択します。

プロジェクトのテスト

以下のURLにアクセスして、テストデータをインポートします：
```
http://localhost:8080/oceanbase/import
```

以下のURLにアクセスして、ベクトル検索を実行します：

http://localhost:8080/oceanbase/search

期待される戻り値：

[
    {
        "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 リポジトリが追加されていることを確認します。

OceanBase

顧客事例

Spring AI