Weaviate

本节引导你设置 Weaviate VectorStore 以存储文档嵌入并执行相似度搜索。

Weaviate 是一个开源向量数据库，让你能够存储数据对象以及来自你喜爱之 ML 模型的向量嵌入，并无缝扩展到数十亿数据对象。它提供工具让你存储文档的嵌入、内容和元数据，并在这些嵌入上进行搜索，包括元数据过滤。

前置条件

一个正在运行的 Weaviate 实例。有以下可选方案：
- Weaviate 云服务（需要创建账户和 API 密钥）
- Docker 容器
如有需要，为 EmbeddingModel 配置一个 API 密钥，以生成 WeaviateVectorStore 所存储的嵌入。

依赖

NOTE

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

把 Weaviate 向量库依赖添加到你的项目：

xml

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

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

groovy

dependencies {
    implementation 'org.springframework.ai:spring-ai-weaviate-store'
}

TIP

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

配置

要连接到 Weaviate 并使用 WeaviateVectorStore，你需要提供实例的访问详情。配置可以通过 Spring Boot 的 application.properties 提供：

properties

spring.ai.vectorstore.weaviate.host=<host_of_your_weaviate_instance>
spring.ai.vectorstore.weaviate.scheme=<http_or_https>
spring.ai.vectorstore.weaviate.api-key=<your_api_key>
# API key if needed, e.g. OpenAI
spring.ai.openai.api-key=<api-key>

如果你更喜欢为 API 密钥等敏感信息使用环境变量，你有多种选择：

选项一：使用 Spring 表达式语言（SpEL）

你可以使用自定义的环境变量名并在应用配置中引用它们：

yaml

# In application.yml
spring:
  ai:
    vectorstore:
      weaviate:
        host: ${WEAVIATE_HOST}
        scheme: ${WEAVIATE_SCHEME}
        api-key: ${WEAVIATE_API_KEY}
    openai:
      api-key: ${OPENAI_API_KEY}

bash

# In your environment or .env file
export WEAVIATE_HOST=<host_of_your_weaviate_instance>
export WEAVIATE_SCHEME=<http_or_https>
export WEAVIATE_API_KEY=<your_api_key>
export OPENAI_API_KEY=<api-key>

选项二：以编程方式访问环境变量

或者，你也可以在 Java 代码中访问环境变量：

java

String weaviateApiKey = System.getenv("WEAVIATE_API_KEY");
String openAiApiKey = System.getenv("OPENAI_API_KEY");

NOTE

如果你选择创建一个 shell 脚本来管理环境变量，务必在启动应用之前通过 "source" 该文件来运行它，即 source <your_script_name>.sh。

自动配置

Spring AI 为 Weaviate 向量库提供 Spring Boot 自动配置。要启用它，请将以下依赖添加到你的项目的 Maven pom.xml 文件：

xml

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

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

groovy

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

TIP

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

请查看该向量库的配置参数列表，了解默认值和配置选项。

TIP

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

此外，你还需要一个已配置的 EmbeddingModel bean。更多信息参见 EmbeddingModel 一节。

以下是所需 bean 的一个示例：

java

@Bean
public EmbeddingModel embeddingModel() {
    // Retrieve API key from a secure source or environment variable
    String apiKey = System.getenv("OPENAI_API_KEY");

    // Can be any other EmbeddingModel implementation
    return new OpenAiEmbeddingModel(OpenAiEmbeddingOptions.builder().apiKey(apiKey).build());
}

现在你可以在应用中把 WeaviateVectorStore 作为向量库自动装配。

手动配置

与其使用 Spring Boot 自动配置，不如使用构建器模式手动配置 WeaviateVectorStore：

java

@Bean
public WeaviateClient weaviateClient() {
    return new WeaviateClient(new Config("http", "localhost:8080"));
}

@Bean
public VectorStore vectorStore(WeaviateClient weaviateClient, EmbeddingModel embeddingModel) {
    return WeaviateVectorStore.builder(weaviateClient, embeddingModel)
        .options(options)                              // Optional: use custom options
        .consistencyLevel(ConsistentLevel.QUORUM)      // Optional: defaults to ConsistentLevel.ONE
        .filterMetadataFields(List.of(                 // Optional: fields that can be used in filters
            MetadataField.text("country"),
            MetadataField.number("year")))
        .build();
}

元数据过滤

你也可以在 Weaviate 向量库上利用通用、可移植的元数据过滤器。

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

java

vectorStore.similaritySearch(
    SearchRequest.builder()
        .query("The World")
        .topK(TOP_K)
        .similarityThreshold(SIMILARITY_THRESHOLD)
        .filterExpression("country in ['UK', 'NL'] && year >= 2020").build());

或以编程方式使用 Filter.Expression DSL：

java

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

NOTE

这些（可移植的）过滤表达式会被自动转换为 Weaviate 专有的 where 过滤器。

例如，这个可移植的过滤表达式：

sql

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

会被转换为 Weaviate 专有的 GraphQL 过滤格式：

graphql

operator: And
operands:
    [{
        operator: Or
        operands:
            [{
                path: ["meta_country"]
                operator: Equal
                valueText: "UK"
            },
            {
                path: ["meta_country"]
                operator: Equal
                valueText: "NL"
            }]
    },
    {
        path: ["meta_year"]
        operator: GreaterThanEqual
        valueNumber: 2020
    }]

在 Docker 中运行 Weaviate

要快速上手一个本地的 Weaviate 实例，你可以在 Docker 中运行它：

bash

docker run -it --rm --name weaviate \
    -e AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED=true \
    -e PERSISTENCE_DATA_PATH=/var/lib/weaviate \
    -e QUERY_DEFAULTS_LIMIT=25 \
    -e DEFAULT_VECTORIZER_MODULE=none \
    -e CLUSTER_HOSTNAME=node1 \
    -p 8080:8080 \
    semitechnologies/weaviate:1.31.22

这会启动一个可通过 http://localhost:8080 访问的 Weaviate 实例。

WeaviateVectorStore 属性

你可以在 Spring Boot 配置中使用以下属性来定制 Weaviate 向量库。

属性
描述
默认值
`spring.ai.vectorstore.weaviate.host`
Weaviate 服务器的主机
localhost:8080
`spring.ai.vectorstore.weaviate.scheme`
连接方案
http
`spring.ai.vectorstore.weaviate.api-key`
用于认证的 API 密钥
`spring.ai.vectorstore.weaviate.object-class`
用于存储文档的类名。
SpringAiWeaviate
`spring.ai.vectorstore.weaviate.content-field-name`
内容的字段名
content
`spring.ai.vectorstore.weaviate.meta-field-prefix`
元数据的字段前缀
meta_
`spring.ai.vectorstore.weaviate.consistency-level`
一致性与速度之间期望的权衡
ConsistentLevel.ONE
`spring.ai.vectorstore.weaviate.filter-field`
配置可在过滤器中使用的元数据字段。格式：spring.ai.vectorstore.weaviate.filter-field.`<field-name>`=`<field-type>`

TIP

对象类名应以大写字母开头，字段名应以小写字母开头。

参见 data-object-concepts

访问原生客户端

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

java

WeaviateVectorStore vectorStore = context.getBean(WeaviateVectorStore.class);
Optional<WeaviateClient> nativeClient = vectorStore.getNativeClient();

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

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

Chat Client API

顾问（Advisor）API

结构化输出

模型

聊天模型 API

嵌入模型 API

Amazon Bedrock

VertexAI

图像模型 API

音频模型

转录 API

文本转语音（TTS）API

审核模型

工具调用

Model Context Protocol (MCP)

MCP 服务端 Boot Starter

MCP 注解

检索增强生成

向量数据库

Weaviate

前置条件

依赖

配置

选项一：使用 Spring 表达式语言（SpEL）

选项二：以编程方式访问环境变量

自动配置

手动配置

元数据过滤

在 Docker 中运行 Weaviate

WeaviateVectorStore 属性

访问原生客户端

友情链接