Typesense

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

Typesense (英語) は、直感的な開発者エクスペリエンスを提供しながら、50 ミリ秒未満の即時検索に最適化されているオープンソースの型ミス耐性検索エンジンです。通常の検索データと一緒に高次元ベクトルを保存およびクエリできるベクトル検索機能を提供します。

前提条件

  • 実行中の Typesense インスタンス。次のオプションが利用可能です。

  • 必要に応じて、EmbeddingModel が TypesenseVectorStore によって保存される埋め込みを生成するための API キー。

自動構成

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

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-typesense-spring-boot-starter</artifactId>
</dependency>

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

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

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

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

ベクトルストアの実装では必要なスキーマを初期化できますが、application.properties ファイルで …​initialize-schema=true を設定してオプトインする必要があります。

さらに、構成された EmbeddingModel Bean が必要になります。詳細については、EmbeddingModel セクションを参照してください。

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

@Autowired VectorStore vectorStore;

// ...

List<Document> documents = List.of(
    new Document("Spring AI rocks!! Spring AI rocks!! Spring AI rocks!! Spring AI rocks!! Spring AI rocks!!", Map.of("meta1", "meta1")),
    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("meta2", "meta2")));

// Add the documents to Typesense
vectorStore.add(documents);

// Retrieve documents similar to a query
List<Document> results = vectorStore.similaritySearch(SearchRequest.builder().query("Spring").topK(5).build());

プロパティの構成

Typesense に接続して TypesenseVectorStore を使用するには、インスタンスのアクセス詳細を提供する必要があります。Spring Boot の application.yml を介して簡単な構成を提供できます。

spring:
  ai:
    vectorstore:
      typesense:
        initialize-schema: true
        collection-name: vector_store
        embedding-dimension: 1536
        client:
          protocol: http
          host: localhost
          port: 8108
          api-key: xyz

spring.ai.vectorstore.typesense.* で始まるプロパティは、TypesenseVectorStore を構成するために使用されます。

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

spring.ai.vectorstore.typesense.initialize-schema

必要なスキーマを初期化するかどうか

false

spring.ai.vectorstore.typesense.collection-name

ベクトルを保存するコレクションの名前

vector_store

spring.ai.vectorstore.typesense.embedding-dimension

ベクトルの次元数

1536

spring.ai.vectorstore.typesense.client.protocol

HTTP プロトコル

http

spring.ai.vectorstore.typesense.client.host

ホスト名

localhost

spring.ai.vectorstore.typesense.client.port

ポート

8108

spring.ai.vectorstore.typesense.client.api-key

API キー

xyz

手動構成

Spring Boot 自動構成を使用する代わりに、Typesense ベクトルストアを手動で構成できます。そのためには、プロジェクトに spring-ai-typesense-store を追加する必要があります。

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

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

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

Typesense Client Bean を作成します。

@Bean
public Client typesenseClient() {
    List<Node> nodes = new ArrayList<>();
    nodes.add(new Node("http", "localhost", "8108"));
    Configuration configuration = new Configuration(nodes, Duration.ofSeconds(5), "xyz");
    return new Client(configuration);
}

次に、ビルダーパターンを使用して TypesenseVectorStore Bean を作成します。

@Bean
public VectorStore vectorStore(Client client, EmbeddingModel embeddingModel) {
    return TypesenseVectorStore.builder(client, embeddingModel)
        .collectionName("custom_vectors")     // Optional: defaults to "vector_store"
        .embeddingDimension(1536)            // Optional: defaults to 1536
        .initializeSchema(true)              // Optional: defaults to false
        .batchingStrategy(new TokenCountBatchingStrategy()) // Optional: defaults to TokenCountBatchingStrategy
        .build();
}

// This can be any EmbeddingModel implementation
@Bean
public EmbeddingModel embeddingModel() {
    return new OpenAiEmbeddingModel(new OpenAiApi(System.getenv("OPENAI_API_KEY")));
}

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

Typesense ストアでも汎用ポータブルメタデータフィルターを活用できます。

たとえば、次のいずれかのテキスト式言語を使用できます。

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());
これらの (ポータブル) フィルター式は自動的に Typesense 検索フィルター (英語) に変換されます。

たとえば、次のポータブルフィルター式:

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

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

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

ドキュメントが期待どおりの順序で取得されない場合、または検索結果が期待どおりでない場合は、使用している埋め込みモデルを確認してください。

埋め込みモデルは検索結果に大きな影響を与える可能性があります (つまり、データがスペイン語の場合は、スペイン語または多言語の埋め込みモデルを使用するようにしてください)。

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

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

TypesenseVectorStore vectorStore = context.getBean(TypesenseVectorStore.class);
Optional<Client> nativeClient = vectorStore.getNativeClient();

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

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