Weaviate

このセクションでは、ドキュメントの埋め込みを保存し、類似性検索を実行するために Weaviate VectorStore を設定する手順について説明します。

Weaviate (英語) は、お気に入りの ML モデルからのデータオブジェクトとベクトル埋め込みを保存し、数十億のデータオブジェクトにシームレスに拡張できるオープンソースのベクトルデータベースです。ドキュメントの埋め込み、コンテンツ、メタデータを保存し、メタデータのフィルタリングを含むそれらの埋め込みを検索するためのツールを提供します。

前提条件

依存関係

Spring AI 自動構成、スターターモジュールのアーティファクト名に大きな変更がありました。詳細については、アップグレードノートを参照してください。

プロジェクトに Weaviate ベクトルストア依存関係を追加します。

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-weaviate-store</artifactId>
</dependency>

または、Gradle build.gradle ビルドファイルに保存します。

dependencies {
    implementation 'org.springframework.ai:spring-ai-weaviate-store'
}
Spring AI BOM をビルドファイルに追加するには、"依存関係管理" セクションを参照してください。

構成

Weaviate に接続して WeaviateVectorStore を使用するには、インスタンスのアクセス詳細を指定する必要があります。設定は Spring Boot の application.properties から行えます。

spring.ai.vectorstore.weaviate.host=<host_of_your_weaviate_instance>
spring.ai.vectorstore.weaviate.scheme=<http_or_https>
spring.ai.vectorstore.weaviate.api-key=<your_api_key>
# API key if needed, e.g. OpenAI
spring.ai.openai.api-key=<api-key>

API キーなどの機密情報に環境変数を使用する場合は、複数のオプションがあります。

オプション 1: Spring 式言語の使用 (SpEL)

カスタム環境変数名を使用して、アプリケーション構成で参照することができます。

# In application.yml
spring:
  ai:
    vectorstore:
      weaviate:
        host: ${WEAVIATE_HOST}
        scheme: ${WEAVIATE_SCHEME}
        api-key: ${WEAVIATE_API_KEY}
    openai:
      api-key: ${OPENAI_API_KEY}
# In your environment or .env file
export WEAVIATE_HOST=<host_of_your_weaviate_instance>
export WEAVIATE_SCHEME=<http_or_https>
export WEAVIATE_API_KEY=<your_api_key>
export OPENAI_API_KEY=<api-key>

オプション 2: プログラムによる環境変数へのアクセス

あるいは、Java コードで環境変数にアクセスすることもできます。

String weaviateApiKey = System.getenv("WEAVIATE_API_KEY");
String openAiApiKey = System.getenv("OPENAI_API_KEY");
環境変数を管理するためにシェルスクリプトを作成する場合は、ファイル (例: source <your_script_name>.sh) を「ソース」してアプリケーションを起動する前に必ず実行してください。

自動構成

Spring AI は、Weaviate ベクトルストア用の Spring Boot 自動構成を提供します。これを有効にするには、プロジェクトの Maven pom.xml ファイルに次の依存関係を追加します。

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-vector-store-weaviate</artifactId>
</dependency>

または、Gradle build.gradle ビルドファイルに保存します。

dependencies {
    implementation 'org.springframework.ai:spring-ai-starter-vector-store-weaviate'
}
Spring AI BOM をビルドファイルに追加するには、"依存関係管理" セクションを参照してください。

デフォルト値と構成オプションについては、ベクトルストアの構成パラメーターのリストを参照してください。

アーティファクトリポジトリセクションを参照して、ビルドファイルに Maven Central リポジトリやスナップショットリポジトリを追加します。

さらに、設定済みの EmbeddingModel Bean が必要です。詳細については、"EmbeddingModel" セクションを参照してください。

必要な Bean の例を次に示します。

@Bean
public EmbeddingModel embeddingModel() {
    // Retrieve API key from a secure source or environment variable
    String apiKey = System.getenv("OPENAI_API_KEY");

    // Can be any other EmbeddingModel implementation
    return new OpenAiEmbeddingModel(OpenAiApi.builder().apiKey(apiKey).build());
}

これで、WeaviateVectorStore をアプリケーション内のベクトルストアとして自動接続できるようになりました。

手動構成

Spring Boot 自動構成を使用する代わりに、ビルダーパターンを使用して WeaviateVectorStore を手動で構成できます。

@Bean
public WeaviateClient weaviateClient() {
    return new WeaviateClient(new Config("http", "localhost:8080"));
}

@Bean
public VectorStore vectorStore(WeaviateClient weaviateClient, EmbeddingModel embeddingModel) {
    return WeaviateVectorStore.builder(weaviateClient, embeddingModel)
        .objectClass("CustomClass")                    // Optional: defaults to "SpringAiWeaviate"
        .consistencyLevel(ConsistentLevel.QUORUM)      // Optional: defaults to ConsistentLevel.ONE
        .filterMetadataFields(List.of(                 // Optional: fields that can be used in filters
            MetadataField.text("country"),
            MetadataField.number("year")))
        .build();
}

メタデータのフィルタリング

Weaviate ストアでは、汎用的でポータブルなメタデータフィルターも活用できます。

例: 次のいずれかのテキスト式言語を使用できます。

vectorStore.similaritySearch(
    SearchRequest.builder()
        .query("The World")
        .topK(TOP_K)
        .similarityThreshold(SIMILARITY_THRESHOLD)
        .filterExpression("country in ['UK', 'NL'] && year >= 2020").build());

または、Filter.Expression DSL を使用してプログラム的に次のようにします。

FilterExpressionBuilder b = new FilterExpressionBuilder();

vectorStore.similaritySearch(SearchRequest.builder()
    .query("The World")
    .topK(TOP_K)
    .similarityThreshold(SIMILARITY_THRESHOLD)
    .filterExpression(b.and(
        b.in("country", "UK", "NL"),
        b.gte("year", 2020)).build()).build());
これらの (ポータブル) フィルター式は、フィルターが使用される (英語) 独自の Weaviate に自動的に変換されます。

例: この移植可能なフィルター式:

country in ['UK', 'NL'] && year >= 2020

独自の Weaviate GraphQL フィルター形式に変換されます。

operator: And
operands:
    [{
        operator: Or
        operands:
            [{
                path: ["meta_country"]
                operator: Equal
                valueText: "UK"
            },
            {
                path: ["meta_country"]
                operator: Equal
                valueText: "NL"
            }]
    },
    {
        path: ["meta_year"]
        operator: GreaterThanEqual
        valueNumber: 2020
    }]

Docker で Weaviate を実行する

ローカル Weaviate インスタンスをすぐに使い始めるには、Docker で実行します。

docker run -it --rm --name weaviate \
    -e AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED=true \
    -e PERSISTENCE_DATA_PATH=/var/lib/weaviate \
    -e QUERY_DEFAULTS_LIMIT=25 \
    -e DEFAULT_VECTORIZER_MODULE=none \
    -e CLUSTER_HOSTNAME=node1 \
    -p 8080:8080 \
    semitechnologies/weaviate:1.22.4

これにより、localhost:8080 でアクセス可能な Weaviate インスタンスが起動します。

WeaviateVectorStore プロパティ

Spring Boot 構成で次のプロパティを使用して、Weaviate ベクトルストアをカスタマイズできます。

プロパティ 説明 デフォルト値

spring.ai.vectorstore.weaviate.host

Weaviate サーバーのホスト

localhost:8080

spring.ai.vectorstore.weaviate.scheme

接続スキーマ

http

spring.ai.vectorstore.weaviate.api-key

認証用の API キー

spring.ai.vectorstore.weaviate.object-class

ドキュメントを保存するためのクラス名

SpringAiWeaviate

spring.ai.vectorstore.weaviate.consistency-level

一貫性と速度の間の望ましいトレードオフ

ConsistentLevel.ONE

spring.ai.vectorstore.weaviate.filter-field

フィルターで使用できるメタデータフィールドを構成します。形式: spring.ai.vectorstore.weaviate.filter-field.<field-name>=<field-type>

ネイティブクライアントへのアクセス

Weaviate ベクトルストアの実装は、getNativeClient() メソッドを通じて、基盤となるネイティブ Weaviate クライアント (WeaviateClient) へのアクセスを提供します。

WeaviateVectorStore vectorStore = context.getBean(WeaviateVectorStore.class);
Optional<WeaviateClient> nativeClient = vectorStore.getNativeClient();

if (nativeClient.isPresent()) {
    WeaviateClient client = nativeClient.get();
    // Use the native client for Weaviate-specific operations
}

ネイティブクライアントを使用すると、VectorStore インターフェースでは公開されない可能性のある Weaviate 固有の機能や操作にアクセスできます。