Oracle Database 23ai - AI 向量搜索

Oracle Database 23ai（23.4+）的 AI Vector Search 能力作为 Spring AI VectorStore 提供，帮助你存储文档嵌入并执行相似度搜索。当然，其所有其他特性也都可用。

TIP

“在本地运行 Oracle Database 23ai” 附录展示了如何用轻量级的 Docker 容器启动一个数据库。

自动配置

NOTE

Spring AI 的自动配置、starter 模块的制品名称发生了重大变更。 更多信息请参阅 升级说明。

先把你项目的 Oracle Vector Store boot starter 依赖添加好：

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

或添加到你的 Gradle build.gradle 构建文件。

dependencies {
    implementation 'org.springframework.ai:spring-ai-starter-vector-store-oracle'
}

如果你需要该向量库为你初始化模式，则要在相应的构造器中为 initializeSchema 布尔参数传入 true，或在 application.properties 文件中设置 ...initialize-schema=true。

NOTE

这是一处破坏性变更！在较早的 Spring AI 版本中，此模式初始化默认进行。

该向量库还需要一个 EmbeddingModel 实例来计算文档的嵌入。 你可以从可用的 EmbeddingModel 实现 中选择一个。

例如，要使用 OpenAI EmbeddingModel，把你的项目添加以下依赖：

<dependency>
	<groupId>org.springframework.ai</groupId>
	<artifactId>spring-ai-starter-model-openai</artifactId>
</dependency>

或添加到你的 Gradle build.gradle 构建文件。

dependencies {
    implementation 'org.springframework.ai:spring-ai-starter-model-openai'
}

TIP

参见 依赖管理 一节，把 Spring AI BOM 添加到你的构建文件。

参见 制品仓库 一节，把 Maven Central 和/或 Snapshot 仓库添加到你的构建文件。

要连接并配置 OracleVectorStore，你需要提供数据库的访问详情。 一个简单的配置可以通过 Spring Boot 的 application.yml 提供

spring:
  datasource:
    url: jdbc:oracle:thin:@//localhost:1521/freepdb1
    username: mlops
    password: mlops
  ai:
	vectorstore:
	  oracle:
		index-type: IVF
		distance-type: COSINE
		dimensions: 1536

TIP

请查看 configuration parameters 以了解默认值与配置项。

现在你可以在应用中把 OracleVectorStore 自动装配并使用它：

@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 Oracle Vector Store
vectorStore.add(documents);

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

配置属性

你可以在 Spring Boot 配置中使用以下属性来定制 OracleVectorStore。

配置项	说明	默认值
spring.ai.vectorstore.oracle.index-type	最近邻检索的索引类型。 可选：NONE（精确最近邻检索）、IVF（倒排平面文件索引）。 构建更快、内存占用比 HNSW 更低，但查询性能（速度-召回权衡）较差。 HNSW（构建多层图）。 构建比 IVF 慢、内存占用更高，但查询性能（速度-召回权衡）更好。	NONE
spring.ai.vectorstore.oracle.distance-type	检索距离类型，可选 COSINE（默认）、DOT、EUCLIDEAN、EUCLIDEAN_SQUARED 与 MANHATTAN。 注意：若向量已归一化，用 DOT 或 COSINE 性能最佳。| COSINE	spring.ai.vectorstore.oracle.forced-normalization
为真时，在写入与相似度检索前启用向量归一化。 注意：必须设为真才能使用 search request similarity threshold. 注意：若向量已归一化，用 DOT 或 COSINE 性能最佳。 | false	spring.ai.vectorstore.oracle.dimensions	嵌入维度。未显式指定时 OracleVectorStore 允许的最大值为 65535。 维度在建表时写入嵌入列；改动维度就必须重建表。
65535	spring.ai.vectorstore.oracle.remove-existing-vector-store-table	启动时删除已有表。
false	spring.ai.vectorstore.oracle.initialize-schema	是否初始化所需的 schema。
false	spring.ai.vectorstore.oracle.search-accuracy	指定建有索引时的精度目标。默认关闭。 需提供 1–100 的整数以覆盖默认索引精度（95）。 精度调低即为近似相似度检索，用速度换精度。
-1 (DEFAULT_SEARCH_ACCURACY)

元数据过滤

你可以在 OracleVectorStore 上利用通用、可移植的元数据过滤器。

例如，你可以使用文本表达式语言：

vectorStore.similaritySearch(
    SearchRequest.builder()
    .query("The World")
    .topK(TOP_K)
    .similarityThreshold(SIMILARITY_THRESHOLD)
    .filterExpression("author in ['john', 'jill'] && article_type == 'blog'").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("author","john", "jill"),
        b.eq("article_type", "blog")).build()).build());

NOTE

这些过滤表达式会被转换为等价的 OracleVectorStore 过滤器。

手动配置

与其使用 Spring Boot 自动配置，不如手动配置 OracleVectorStore。 为此你需要把 Oracle JDBC 驱动和 JdbcTemplate 自动配置依赖添加到你的项目：

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

<dependency>
	<groupId>com.oracle.database.jdbc</groupId>
	<artifactId>ojdbc11</artifactId>
	<scope>runtime</scope>
</dependency>

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

TIP

参见 依赖管理 一节，把 Spring AI BOM 添加到你的构建文件。

要在你的应用中配置 OracleVectorStore，可以使用以下设置：

@Bean
public VectorStore vectorStore(JdbcTemplate jdbcTemplate, EmbeddingModel embeddingModel) {
    return OracleVectorStore.builder(jdbcTemplate, embeddingModel)
        .tableName("my_vectors")
        .indexType(OracleVectorStoreIndexType.IVF)
        .distanceType(OracleVectorStoreDistanceType.COSINE)
        .dimensions(1536)
        .searchAccuracy(95)
        .initializeSchema(true)
        .build();
}

在本地运行 Oracle Database 23ai

docker run --rm --name oracle23ai -p 1521:1521 -e APP_USER=mlops -e APP_USER_PASSWORD=mlops -e ORACLE_PASSWORD=mlops gvenzl/oracle-free:23-slim

然后你可以使用以下命令连接到该数据库：

sql mlops/mlops@localhost/freepdb1

访问原生客户端

Oracle 向量库实现通过 getNativeClient() 方法提供对底层原生 Oracle 客户端（OracleConnection）的访问：

OracleVectorStore vectorStore = context.getBean(OracleVectorStore.class);
Optional<OracleConnection> nativeClient = vectorStore.getNativeClient();

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

原生客户端让你得以访问那些可能未通过 VectorStore 接口暴露的 Oracle 特定功能与操作。