Weaviate
本部分将引导您完成 Weaviate VectorStore
设置,以存储文档嵌入
并执行相似性搜索
。
Weaviate 是什么?
Weaviate 是一个开源的向量数据库,它允许您存储来自您喜爱的机器学习模型的数据对象和向量嵌入,并能够无缝扩展至数十亿个数据对象。 它提供了存储文档嵌入、内容及元数据的工具,以及通过这些嵌入进行搜索的功能,包括元数据过滤。
先决条件
- 一个正在运行的 Weaviate 实例。以下是可用的选项:
- Weaviate 云服务 (需创建账户并获取 API 密钥)
- Docker 容器
- 如需要,可为 EmbeddingModel 获取 API 密钥,以生成由 WeaviateVectorStore 存储的嵌入向量。
依赖项
将 Weaviate 向量存储依赖项添加到您的项目中:
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-weaviate-store</artifactId>
</dependency>
或者,在你的 Gradle 构建文件 build.gradle
中添加:
dependencies {
implementation 'org.springframework.ai:spring-ai-weaviate-store'
}
配置
要连接到 Weaviate 并使用 WeaviateVectorStore,您需要提供实例的访问详细信息。配置可以通过 Spring Boot 的 application.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 密钥等敏感信息,您有多种选择:
选项 1:使用 Spring 表达式语言(SpEL)
您可以使用自定义的环境变量名称,并在应用程序配置中引用它们:
# In application.yml
spring:
ai:
vectorstore:
weaviate:
host: ${WEAVIATE_HOST}
scheme: ${WEAVIATE_SCHEME}
api-key: ${WEAVIATE_API_KEY}
openai:
api-key: ${OPENAI_API_KEY}
# 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 代码中访问环境变量:
String weaviateApiKey = System.getenv("WEAVIATE_API_KEY");
String openAiApiKey = System.getenv("OPENAI_API_KEY");
自动配置
Spring AI 为 Weaviate 向量存储提供了 Spring Boot 自动配置功能。要启用此功能,请将以下依赖项添加到项目的 Maven pom.xml 文件中:
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-vector-store-weaviate</artifactId>
</dependency>
或者,在你的 Gradle 构建文件 build.gradle
中添加:
dependencies {
implementation 'org.springframework.ai:spring-ai-starter-vector-store-weaviate'
}
此外,您还需要配置一个 EmbeddingModel
bean。详情请参阅 EmbeddingModel 部分。
以下是所需 Bean 的示例:
@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(OpenAiApi.builder().apiKey(apiKey).build());
}
现在,您可以在应用程序中自动装配 WeaviateVectorStore 作为向量存储使用。
手动配置
除了使用 Spring Boot 的自动配置外,您还可以通过构建器模式手动配置 WeaviateVectorStore:
@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)
.objectClass("CustomClass") // Optional: defaults to "SpringAiWeaviate"
.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 存储中的通用、便携式 元数据过滤器 。
例如,您可以使用文本表达式语言:
vectorStore.similaritySearch(
SearchRequest.builder()
.query("The World")
.topK(TOP_K)
.similarityThreshold(SIMILARITY_THRESHOLD)
.filterExpression("country in ['UK', 'NL'] && year >= 2020").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("country", "UK", "NL"),
b.gte("year", 2020)).build()).build());
例如,这个便携式过滤表达式:
country in ['UK', 'NL'] && year >= 2020
被转换为专有的 Weaviate 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 中运行它:
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.22.4
这将启动一个可通过 localhost:8080 访问的 Weaviate 实例。
WeaviateVectorStore 属性
您可以在 Spring Boot 配置中使用以下属性来定制 Weaviate 向量存储。
属性 (Property) | 描述 (Description) | 默认值 (Default value) |
---|---|---|
spring.ai.vectorstore.weaviate.host |
Weaviate 服务器的主机地址 | localhost:8080 |
spring.ai.vectorstore.weaviate.scheme |
连接协议 (http/https) | http |
spring.ai.vectorstore.weaviate.api-key |
用于身份验证的 API 密钥 | - |
spring.ai.vectorstore.weaviate.object-class |
用于存储文档的类名 | SpringAiWeaviate |
spring.ai.vectorstore.weaviate.consistency-level |
一致性需求与速度之间的理想权衡 | ConsistentLevel.ONE |
spring.ai.vectorstore.weaviate.filter-field |
配置可用于筛选的元数据字段。格式:spring.ai.vectorstore.weaviate.filter-field.<字段名称>=<字段类型> |
- |
访问原生客户端
Weaviate 向量存储实现通过 getNativeClient () 方法提供了对底层原生 Weaviate 客户端(WeaviateClient)的访问:
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
}
原生客户端为您提供了访问 Weaviate 特有功能和操作的途径,这些可能未通过 VectorStore 接口公开。
最后编辑:Jeebiz 更新时间:2025-09-28 09:15