​
Typesense 向量数据库

Spring AI 支持将 Typesense 作为向量数据库。

​
添加依赖

要使用 Typesense 向量存储，您需要将 spring-ai-typesense-store-spring-boot-starter 依赖项添加到项目的 pom.xml 文件中。 该启动器包含了 spring-ai-core 和 Typesense Java 客户端库。 
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-typesense-store-spring-boot-starter</artifactId>
</dependency>
您还需要一个 EmbeddingClient 实现来为您的文档生成向量嵌入。例如，您可以添加 spring-ai-openai-spring-boot-starter 以使用 OpenAI 的嵌入模型： 
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-openai-spring-boot-starter</artifactId>
</dependency>

​
配置属性

在您的 application.properties 或 application.yml 文件中配置 Typesense 和嵌入客户端属性。

​
Typesense 属性

属性描述默认值
spring.ai.vectorstore.typesense.collection-name用于存储文档的 Typesense 集合名称。spring_ai_collection
spring.ai.vectorstore.typesense.embedding-dimension嵌入向量的维度。必须与 EmbeddingClient 生成的维度匹配。1536 (OpenAI text-embedding-ada-002)
spring.ai.vectorstore.typesense.hostTypesense 服务器的主机名或 IP 地址。localhost
spring.ai.vectorstore.typesense.portTypesense 服务器的端口。8108
spring.ai.vectorstore.typesense.protocol用于连接到 Typesense 服务器的协议 (例如 http 或 https)http
spring.ai.vectorstore.typesense.api-key用于向 Typesense 服务器进行身份验证的 API 密钥。
示例 application.properties: 
# Typesense 配置
spring.ai.vectorstore.typesense.collection-name=my_documents
spring.ai.vectorstore.typesense.embedding-dimension=1536
spring.ai.vectorstore.typesense.host=localhost
spring.ai.vectorstore.typesense.port=8108
spring.ai.vectorstore.typesense.protocol=http
spring.ai.vectorstore.typesense.api-key=YOUR_TYPESENSE_API_KEY

# 嵌入客户端配置 (例如 OpenAI)
spring.ai.openai.api-key=YOUR_OPENAI_API_KEY
spring.ai.openai.embedding.options.model=text-embedding-ada-002
确保 spring.ai.vectorstore.typesense.embedding-dimension 与您正在使用的 EmbeddingClient 输出的嵌入维度相匹配。

​
使用 VectorStore

将 VectorStore bean 注入到您的组件中以与之交互： 
import org.springframework.ai.vectorstore.VectorStore;
import org.springframework.ai.document.Document;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

import java.util.List;

@Service
public class MyVectorStoreService {

    private final VectorStore vectorStore; // 将自动配置 TypesenseVectorStore

    @Autowired
    public MyVectorStoreService(VectorStore vectorStore) {
        this.vectorStore = vectorStore;
    }

    public void addDocuments(List<Document> documents) {
        vectorStore.add(documents);
    }

    public List<Document> findSimilarDocuments(String query, int k) {
        return vectorStore.similaritySearch(query, k);
    }
}

​
创建 TypesenseVectorStore Bean (可选)

Spring Boot 会自动配置 TypesenseVectorStore bean。但是，如果您需要自定义配置，可以定义自己的 bean： 
import org.springframework.ai.embedding.EmbeddingClient;
import org.springframework.ai.vectorstore.TypesenseVectorStore;
import org.springframework.ai.vectorstore.TypesenseVectorStore.TypesenseVectorStoreConfig;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.typesense.api.Client;
import org.typesense.api.ConfigurationNode;

import java.util.List;

@Configuration
public class MyTypesenseConfig {

    @Bean
    public Client typesenseClient() {
        // 从属性或直接创建 TypesenseClient
        List<ConfigurationNode> nodes = List.of(
            new ConfigurationNode("localhost", "8108", "http")
        );
        // 如果需要 API 密钥:
        // org.typesense.api.Configuration configuration = new org.typesense.api.Configuration(nodes, java.time.Duration.ofSeconds(10), "YOUR_TYPESENSE_API_KEY");
        org.typesense.api.Configuration configuration = new org.typesense.api.Configuration(nodes, java.time.Duration.ofSeconds(10), "YOUR_TYPESENSE_API_KEY");
        return new Client(configuration);
    }

    @Bean
    public TypesenseVectorStore typesenseVectorStore(Client typesenseClient, EmbeddingClient embeddingClient) {
        TypesenseVectorStoreConfig config = TypesenseVectorStoreConfig.builder()
            .withCollectionName("my_custom_collection")
            .withEmbeddingDimension(1536)
            .build();
        return new TypesenseVectorStore(typesenseClient, embeddingClient, config);
    }
}

​
元数据过滤

Typesense 向量存储支持使用 Typesense 的 filter_by 查询参数 和 Spring AI 的 相似性搜索过滤器表达式 进行元数据过滤。 过滤器表达式会转换为 Typesense 的 filter_by 字符串格式。 示例： 
import org.springframework.ai.vectorstore.SearchRequest;
import org.springframework.ai.vectorstore.filter.Filter;
import org.springframework.ai.vectorstore.filter.FilterExpressionBuilder;

// ...

FilterExpressionBuilder b = new FilterExpressionBuilder();

// genre:='drama' && year:>2020
Filter filter = new Filter(b.eq("genre", "drama").and(b.gt("year", 2020)).build());

SearchRequest request = SearchRequest.query("A dramatic film released after 2020") // 示例查询通常保留英文
    .withTopK(5)
    .withFilter(filter);

List<Document> results = vectorStore.similaritySearch(request);
确保用于过滤的元数据字段存在于您的 Typesense 集合 schema 中，并根据 Typesense 的要求进行适当定义 (例如，将它们定义为 facet: true 以进行高效过滤)。 Typesense 对 filter_by 语法有特定的要求。Spring AI 的 FilterExpressionConverter 尽力将其转换为兼容的格式，但复杂的嵌套表达式可能无法完全支持或需要仔细构建。

​
删除数据

TypesenseVectorStore 支持通过文档 ID 删除数据。 
boolean deleted = vectorStore.delete(List.of("documentId1", "documentId2"));

​
总结

将 Spring AI 与 Typesense 集成，提供了一种快速且易于使用的向量搜索解决方案，利用了 Typesense 的内存性能和对开发人员友好的特性。

文档有误？请协助编辑

发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！