OceanBaseデータベースとSpring AI Alibabaの連携|V4.3.5|OceanBaseデータベース|OceanBaseデータベースドキュメント|分散データベース

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

Spring AI Alibabaは、Spring AIを基盤に構築されたオープンソースプロジェクトで、Alibaba CloudのTongyiシリーズのモデルやサービスをJavaによる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に合ったバージョンをインストールします。

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

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>
            <!-- Alibaba Cloud 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 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   # 類似度のしきい値

ステップ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;
    
    // データをインポートするAPIエンドポイント
    @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);
    }
    
    // 類似ドキュメントを検索するAPIエンドポイント
    @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 Alibabaの連携