Oracle Database 23ai - AI Vector Search

Oracle Database 23ai (23.4+) 的 AI Vector Search 功能可作为 Spring AI VectorStore 使用，帮助您存储文档嵌入并执行相似性搜索。当然，所有其他功能也可用。

The AI Vector Search capabilities of the Oracle Database 23ai (23.4+) are available as a Spring AI VectorStore to help you to store document embeddings and perform similarity searches. Of course, all other features are also available.

Run Oracle Database 23ai locally 附录展示了如何使用轻量级 Docker 容器启动数据库。

The _run_oracle_database_23ai_locally appendix shows how to start a database with a lightweight Docker container.

Auto-Configuration

Spring AI 自动配置、启动器模块的工件名称发生了重大变化。请参阅 upgrade notes 以获取更多信息。

There has been a significant change in the Spring AI auto-configuration, starter modules' artifact names. Please refer to the upgrade notes for more information.

首先，将 Oracle Vector Store 启动器依赖项添加到您的项目中：

Start by adding the Oracle Vector Store boot starter dependency to your project:

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

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

or to your Gradle build.gradle build file.

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

如果需要此向量存储为您初始化模式，则需要在相应的构造函数中为 initializeSchema 布尔参数传递 true，或者在 application.properties 文件中设置 …​initialize-schema=true 。

If you need this vector store to initialize the schema for you then you’ll need to pass true for the initializeSchema boolean parameter in the appropriate constructor or by setting …​initialize-schema=true in the application.properties file.

这是一个重大更改！在早期版本的Spring AI中，此架构初始化是默认发生的。

this is a breaking change! In earlier versions of Spring AI, this schema initialization happened by default.

向量存储还需要一个 EmbeddingModel 实例来计算文档的嵌入。您可以选择 EmbeddingModel Implementations 中可用的一个。

The Vector Store, also requires an EmbeddingModel instance to calculate embeddings for the documents. You can pick one of the available EmbeddingModel Implementations.

例如，要使用 OpenAI EmbeddingModel ，请将以下依赖项添加到您的项目中：

For example to use the OpenAI EmbeddingModel add the following dependency to your project:

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

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

or to your Gradle build.gradle build file.

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

请参阅 Dependency Management 部分，将 Spring AI BOM 添加到您的构建文件中。请参阅 Artifact Repositories 部分，将 Maven Central 和/或快照存储库添加到您的构建文件中。

Refer to the Dependency Management section to add the Spring AI BOM to your build file. Refer to the Artifact Repositories section to add Maven Central and/or Snapshot Repositories to your build file.

要连接和配置 OracleVectorStore ，您需要提供数据库的访问详细信息。可以通过 Spring Boot 的 application.yml 提供简单的配置。

To connect to and configure the OracleVectorStore, you need to provide access details for your database. A simple configuration can either be provided via Spring Boot’s 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

查看 configuration parameters 列表，了解默认值和配置选项。

Check the list of oracle-properties to learn about the default values and configuration options.

现在您可以在应用程序中自动装配 OracleVectorStore 并使用它：

Now you can Auto-wire the OracleVectorStore in your application and use it:

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

Configuration properties

您可以在 Spring Boot 配置中使用以下属性来自定义 OracleVectorStore 。

You can use the following properties in your Spring Boot configuration to customize the OracleVectorStore.

Property Description Default value

spring.ai.vectorstore.oracle.index-type

Nearest neighbor search index type. Options are NONE - exact nearest neighbor search, IVF - Inverted Flat File index. It has faster build times and uses less memory than HNSW, but has lower query performance (in terms of speed-recall tradeoff). HNSW - creates a multilayer graph. It has slower build times and uses more memory than IVF, but has better query performance (in terms of speed-recall tradeoff).

NONE

spring.ai.vectorstore.oracle.distance-type

Search distance type among COSINE (default), DOT, EUCLIDEAN, EUCLIDEAN_SQUARED, and MANHATTAN.

NOTE: If vectors are normalized, you can use DOT or COSINE for best performance.

COSINE

spring.ai.vectorstore.oracle.forced-normalization

Allows enabling vector normalization (if true) before insertion and for similarity search.

CAUTION: Setting this to true is a requirement to allow for search request similarity threshold.

NOTE: If vectors are normalized, you can use DOT or COSINE for best performance.

false

spring.ai.vectorstore.oracle.dimensions

Embeddings dimension. If not specified explicitly the OracleVectorStore will allow the maximum: 65535. Dimensions are set to the embedding column on table creation. If you change the dimensions your would have to re-create the table as well.

65535

spring.ai.vectorstore.oracle.remove-existing-vector-store-table

Drops the existing table on start up.

false

spring.ai.vectorstore.oracle.initialize-schema

Whether to initialize the required schema.

false

spring.ai.vectorstore.oracle.search-accuracy

Denote the requested accuracy target in the presence of index. Disabled by default. You need to provide an integer in the range [1,100] to override the default index accuracy (95). Using lower accuracy provides approximate similarity search trading off speed versus accuracy.

-1 (DEFAULT_SEARCH_ACCURACY)

Metadata filtering

您可以将通用的、可移植的 metadata filters 与 OracleVectorStore 结合使用。

You can leverage the generic, portable metadata filters with the OracleVectorStore.

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

For example, you can use either the text expression language:

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 以编程方式：

or programmatically using the 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());

这些过滤表达式将转换为等效的 OracleVectorStore 过滤器。

These filter expressions are converted into the equivalent OracleVectorStore filters.

Manual Configuration

您可以通过手动配置 OracleVectorStore 来替代使用 Spring Boot 自动配置。为此，您需要在项目中添加 Oracle JDBC 驱动和 JdbcTemplate 自动配置依赖项：

Instead of using the Spring Boot auto-configuration, you can manually configure the OracleVectorStore. For this you need to add the Oracle JDBC driver and JdbcTemplate auto-configuration dependencies to your project:

<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>

  1. 参见 Dependency Management 部分，将 Spring AI BOM 添加到你的构建文件中。

Refer to the Dependency Management section to add the Spring AI BOM to your build file.

要配置应用程序中的 OracleVectorStore ，您可以使用以下设置：

To configure the OracleVectorStore in your application, you can use the following setup:

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

Run Oracle Database 23ai locally

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

然后，您可以使用以下方式连接到数据库：

You can then connect to the database using:

sql mlops/mlops@localhost/freepdb1

Accessing the Native Client

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

The Oracle Vector Store implementation provides access to the underlying native Oracle client (OracleConnection) through the getNativeClient() method:

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
}

原生客户端为您提供对 Oracle 特定功能和操作的访问，这些功能和操作可能不会通过 VectorStore 接口公开。

The native client gives you access to Oracle-specific features and operations that might not be exposed through the VectorStore interface.