Weaviate 技术详解与 Spring AI 集成实践

本文系统介绍 Weaviate 向量数据库的原理、发展、Spring AI 集成方案，并通过多种 Mermaid 图表优化结构理解，帮助开发者快速建立系统性认知。

---

一、概述

Weaviate 是一个开源的向量数据库，专为存储、检索大规模机器学习模型生成的向量嵌入（embeddings）而设计。它支持丰富的内容与元数据管理，并能高效执行相似度检索与复杂过滤操作。

---

二、名词解释

名词	解释
向量数据库	专门用于存储和检索高维向量（如文本、图像的嵌入表示）的数据库。
Embedding	将文本/图片等内容转化为固定长度的数值向量，用于语义检索等任务。
Metadata	附属在内容上的描述性信息，如国家、年份等，可用于过滤和查询。
VectorStore	Spring AI 接口，用于统一管理各种向量数据库的交互逻辑。
WeaviateClient	Java SDK 客户端，封装 Weaviate 原生 API 交互能力。

---

三、项目背景与发展历史

1. 发展历程

• 2019年：Weaviate 项目由 Semi Technologies 发起，定位为语义搜索数据库。
• 2021年：逐步扩展为支持多种主流嵌入模型（OpenAI, Cohere等）。
• 2023年：与 Spring AI 等主流 AI 框架集成，成为向量检索基础设施的主力军。
• 2024年：支持数十亿级别向量数据，成为大模型场景下的首选基础组件。

2. 权威参考资料

• 官方文档：Weaviate Documentation
• Semi Technologies Blog：Why Weaviate?
• Spring AI 文档：Spring AI Reference

---

四、技术架构与系统流程

1. 系统架构流程图（Mermaid - flowchart）

flowchart TB
    subgraph 用户应用
        A[内容/文档上传]
        B[元数据设置]
        C[向量生成(EmbeddingModel)]
    end

    subgraph Spring AI
        D[WeaviateVectorStore]
        E[自动配置/手动配置]
        F[相似度检索]
        G[元数据过滤]
    end

    subgraph Weaviate 服务
        H[存储内容/向量]
        I[检索/过滤]
        J[原生API操作]
    end

    A --> C
    B --> D
    C --> D
    D -->|配置| E
    D -->|存储| H
    D -->|检索| F
    F --> G
    G --> I
    E --> D
    D --> J

说明： 用户内容经过 EmbeddingModel 生成向量，经 Spring AI 的 VectorStore 存入 Weaviate，并支持检索与过滤。

---

2. 状态转换图（Mermaid - stateDiagram-v2）

说明： 展示了从系统初始化到内容上传、处理、检索的完整状态流转过程。

---

3. 时序交互图（Mermaid - sequenceDiagram）

说明： 明确各组件之间的交互时序，便于理解 Spring AI 与 Weaviate 的协作流程。

---

五、Spring AI 集成实践

1. 依赖引入

Maven：

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

Gradle：

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

2. 配置方式

application.properties 示例

spring.ai.vectorstore.weaviate.host=localhost:8080
spring.ai.vectorstore.weaviate.scheme=http
spring.ai.vectorstore.weaviate.api-key=
spring.ai.openai.api-key=<your_openai_api_key>

application.yml + 环境变量

spring:
  ai:
    vectorstore:
      weaviate:
        host: ${WEAVIATE_HOST}
        scheme: ${WEAVIATE_SCHEME}
        api-key: ${WEAVIATE_API_KEY}
    openai:
      api-key: ${OPENAI_API_KEY}

环境变量设置：

export WEAVIATE_HOST=localhost:8080
export WEAVIATE_SCHEME=http
export WEAVIATE_API_KEY=
export OPENAI_API_KEY=<your_openai_api_key>

3. Bean 配置示例（自动装配）

@Bean
public EmbeddingModel embeddingModel() {
    String apiKey = System.getenv("OPENAI_API_KEY");
    return new OpenAiEmbeddingModel(OpenAiApi.builder().apiKey(apiKey).build());
}

@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)
        .consistencyLevel(ConsistentLevel.QUORUM)
        .filterMetadataFields(List.of(
            MetadataField.text("country"),
            MetadataField.number("year")))
        .build();
}

4. 元数据过滤示例

表达式过滤：

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

DSL过滤：

FilterExpressionBuilder b = new FilterExpressionBuilder();
vectorStore.similaritySearch(SearchRequest.builder()
    .query("The World")
    .topK(5)
    .similarityThreshold(0.8)
    .filterExpression(b.and(
        b.in("country", "UK", "NL"),
        b.gte("year", 2020)).build()).build());

---

六、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 服务。

---

七、核心配置参数速记口

配置项	说明	默认值
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	一致性等级	ONE

---

八、系统性认知总结

• Weaviate 是什么？ —— 专为大规模语义检索设计的开源向量数据库。
• 为什么用 Weaviate？ —— 支持高性能向量检索、灵活元数据过滤、易于扩展和集成。
• Spring AI 集成优势？ —— 简化配置、自动装配、统一检索接口，极大提升开发效率。
• 如何快速落地？ —— 通过 Docker 启动本地服务，Spring AI 引入依赖与配置，轻松实现向量检索与元数据过滤。
• 常见场景？ —— 智能问答、知识库检索、推荐系统、内容去重等 AI 应用场景。

---

九、参考文献

1. Weaviate 官方文档
2. Spring AI Reference
3. Semi Technologies Blog
4. Weaviate Github

---

以上内容及图表，帮助你从原理、架构到落地实践全面掌握 Weaviate 与 Spring AI 向量数据库解决方案。