​
SAP HANA Cloud 向量数据库

Spring AI 支持将 SAP HANA Cloud 作为向量数据库，利用其向量引擎进行相似性搜索。

​
添加依赖

要使用 SAP HANA Cloud 向量存储，您需要将 spring-ai-sap-hana-store-spring-boot-starter 依赖项添加到项目的 pom.xml 文件中。 该启动器包含了 spring-ai-core 和 SAP HANA JDBC 驱动程序。

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-sap-hana-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 文件中配置 SAP HANA Cloud 和嵌入客户端属性。

​
SAP HANA Cloud 属性

属性描述默认值
spring.ai.vectorstore.hana.hostSAP HANA Cloud 实例的主机名或 IP 地址。
spring.ai.vectorstore.hana.portSAP HANA Cloud 实例的端口。
spring.ai.vectorstore.hana.username用于连接到 SAP HANA Cloud 的用户名。
spring.ai.vectorstore.hana.password用于连接到 SAP HANA Cloud 的密码。
spring.ai.vectorstore.hana.table-name用于存储向量和元数据的表名。SPRING_AI_VECTOR_STORE
spring.ai.vectorstore.hana.embedding-dimension嵌入向量的维度。必须与 EmbeddingClient 生成的维度匹配。1536 (OpenAI text-embedding-ada-002)
spring.ai.vectorstore.hana.distance-type用于相似性搜索的距离类型 (L2DISTANCE, COSINE_SIMILARITY, EUCLIDEAN_DISTANCE)。L2DISTANCE
spring.ai.vectorstore.hana.schema-nameSAP HANA Cloud 中的 schema 名称。(用户默认 schema)
spring.ai.vectorstore.hana.ssl.enabled是否为 JDBC 连接启用 SSL。false
spring.ai.vectorstore.hana.ssl.trust-store-locationSSL 信任库文件的路径 (如果 ssl.enabled 为 true)。
spring.ai.vectorstore.hana.ssl.trust-store-passwordSSL 信任库的密码 (如果 ssl.enabled 为 true)。

示例 application.properties:

# SAP HANA Cloud 配置
spring.ai.vectorstore.hana.host=your-hana-host
spring.ai.vectorstore.hana.port=your-hana-port
spring.ai.vectorstore.hana.username=your-username
spring.ai.vectorstore.hana.password=your-password
spring.ai.vectorstore.hana.table-name=MY_VECTOR_TABLE
spring.ai.vectorstore.hana.embedding-dimension=1536
spring.ai.vectorstore.hana.distance-type=COSINE_SIMILARITY
# spring.ai.vectorstore.hana.schema-name=MY_SCHEMA # 可选
# spring.ai.vectorstore.hana.ssl.enabled=true # 如果需要 SSL
# spring.ai.vectorstore.hana.ssl.trust-store-location=path/to/truststore.jks
# spring.ai.vectorstore.hana.ssl.trust-store-password=truststore_password

# 嵌入客户端配置 (例如 OpenAI)
spring.ai.openai.api-key=YOUR_OPENAI_API_KEY
spring.ai.openai.embedding.options.model=text-embedding-ada-002

确保 spring.ai.vectorstore.hana.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; // 将自动配置 HanaVectorStore

    @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);
    }
}

​
创建 HanaVectorStore Bean (可选)

Spring Boot 会自动配置 HanaVectorStore bean。但是，如果您需要自定义配置，可以定义自己的 bean：

import com.zaxxer.hikari.HikariDataSource;
import org.springframework.ai.embedding.EmbeddingClient;
import org.springframework.ai.vectorstore.HanaVectorStore;
import org.springframework.ai.vectorstore.HanaVectorStore.HanaVectorStoreConfig;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.jdbc.core.JdbcTemplate;

import javax.sql.DataSource;

@Configuration
public class MyHanaConfig {

    @Bean
    public DataSource hanaDataSource() {
        HikariDataSource dataSource = new HikariDataSource();
        dataSource.setJdbcUrl("jdbc:sap://your-hana-host:your-hana-port");
        dataSource.setUsername("your-username
        dataSource.setPassword("your-password");
        // dataSource.setSchema("MY_SCHEMA"); // 可选
        // SSL 属性 (如果需要)
        // dataSource.getDataSourceProperties().setProperty("encrypt", "true");
        // dataSource.getDataSourceProperties().setProperty("trustStore", "path/to/truststore.jks");
        // dataSource.getDataSourceProperties().setProperty("trustStorePassword", "truststore_password");
        return dataSource;
    }

    @Bean
    public JdbcTemplate jdbcTemplate(DataSource hanaDataSource) {
        return new JdbcTemplate(hanaDataSource);
    }

    @Bean
    public HanaVectorStore hanaVectorStore(JdbcTemplate jdbcTemplate, EmbeddingClient embeddingClient) {
        HanaVectorStoreConfig config = HanaVectorStoreConfig.builder()
            .tableName("MY_CUSTOM_TABLE")
            .embeddingDimension(1536)
            .distanceType(HanaVectorStoreConfig.DistanceType.COSINE_SIMILARITY)
            // .schemaName("MY_SCHEMA") // 可选
            .build();
        return new HanaVectorStore(jdbcTemplate, embeddingClient, config);
    }
}

​
元数据过滤

SAP HANA Cloud 向量存储支持使用 SQL WHERE 子句和 Spring AI 的 相似性搜索过滤器表达式 进行元数据过滤。

过滤器表达式会转换为 SQL WHERE 子句中的条件。

示例：

import org.springframework.ai.vectorstore.SearchRequest;
import org.springframework.ai.vectorstore.filter.Filter;
import org.springframework.ai.vectorstore.filter.FilterExpressionBuilder;

// ...

FilterExpressionBuilder b = new FilterExpressionBuilder();

// "metadata"->>'genre' = 'drama' AND "metadata"->>'year' > 2020
// 注意：在 SAP HANA 中，JSON 字段访问通常使用 JSON 函数或路径表达式。
// 此处的示例假定元数据存储为 JSON，并且数据库配置为支持此类查询。
// 精确的 SQL 语法可能因您的 HANA 版本和表结构而异。
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);

元数据存储在表中的 metadata JSON 列中。 过滤器表达式中使用的键 (例如，genre, year) 应该是您在文档元数据中使用的键。 确保您的 SAP HANA Cloud 实例配置为允许对 JSON 列进行高效查询。根据需要，可能需要为元数据字段创建索引。

​
删除数据

HanaVectorStore 支持通过文档 ID 删除数据。

boolean deleted = vectorStore.delete(List.of("documentId1", "documentId2"));

​
总结

将 Spring AI 与 SAP HANA Cloud 集成，使您能够利用 HANA 的内存计算能力和企业级特性进行向量存储和相似性搜索，从而增强您的 AI 应用程序。

文档有误？请协助编辑

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