# https://github.com/weaviate/weaviate 项目说明书

生成时间：2026-05-31 03:23:55 UTC

## 目录

- [项目概述](#page-overview)
- [核心概念](#page-core-concepts)
- [系统架构](#page-architecture)
- [API层实现](#page-api-layer)
- [LSMKV存储引擎](#page-lsmkv-storage)
- [向量索引实现](#page-vector-indexes)
- [集群与复制机制](#page-cluster-replication)
- [多租户支持](#page-multi-tenancy)
- [混合搜索实现](#page-hybrid-search)
- [模块系统](#page-modules)

<a id='page-overview'></a>

## 项目概述

### 相关页面

相关主题：[系统架构](#page-architecture), [核心概念](#page-core-concepts)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/weaviate/weaviate/blob/main/README.md)
- [cmd/weaviate-server/main.go](https://github.com/weaviate/weaviate/blob/main/cmd/weaviate-server/main.go)
- [adapters/handlers/rest/server.go](https://github.com/weaviate/weaviate/blob/main/adapters/handlers/rest/server.go)
- [adapters/handlers/grpc/server.go](https://github.com/weaviate/weaviate/blob/main/adapters/handlers/grpc/server.go)
- [modules/text2vec-contextionary/client/contextionary.go](https://github.com/weaviate/weaviate/blob/main/modules/text2vec-contextionary/client/contextionary.go)
- [tools/telemetry-dashboard/README.md](https://github.com/weaviate/weaviate/blob/main/tools/telemetry-dashboard/README.md)
- [usecases/config/runtime/manager_test.go](https://github.com/weaviate/weaviate/blob/main/usecases/config/runtime/manager_test.go)
- [cluster/proto/api/message.pb.go](https://github.com/weaviate/weaviate/blob/main/cluster/proto/api/message.pb.go)
</details>

# 项目概述

## 1. 项目简介

Weaviate 是一个开源的云原生向量数据库（Vector Database），它同时存储对象（objects）和向量（vectors），能够在规模上实现语义搜索。资料来源：[README.md](https://github.com/weaviate/weaviate/blob/main/README.md)

Weaviate 将向量相似性搜索与关键词过滤、检索增强生成（RAG）和重排序（reranking）整合在单一查询接口中。常见的应用场景包括 RAG 系统、语义搜索与图像搜索、推荐引擎、聊天机器人和内容分类。

### 1.1 核心定位

Weaviate 的核心定位具有以下几个关键特征：

- **双重存储能力**：同时支持结构化对象和向量嵌入的存储
- **语义搜索**：基于向量相似性实现语义理解，而非仅依赖关键词匹配
- **云原生架构**：专为云环境设计，支持分布式部署和水平扩展
- **AI 集成**：内置与多种 AI 模型提供商的集成，支持 RAG 和生成式搜索

### 1.2 版本信息

当前最新版本为 **v1.38.0-rc.0**，包含 HFresh（GA）、命名空间（Namespaces）、嵌套对象过滤（Nested Object Filtering）和 Alter Schema Reindex property 等特性。

## 2. 整体架构

Weaviate 采用分层架构设计，主要分为以下几个层次：

```mermaid
graph TD
    subgraph "客户端层"
        Python[Python Client]
        TS[TypeScript Client]
        Java[Java Client]
        Go[Go Client]
        CSharp[C# Client]
    end
    
    subgraph "API 网关层"
        REST[REST API]
        gRPC[gRPC API]
        GraphQL[GraphQL API]
    end
    
    subgraph "业务逻辑层"
        Modules[Modules]
        Search[Search Engine]
        Schema[Schema Manager]
    end
    
    subgraph "存储层"
        VectorIndex[Vector Index HNSW]
        ObjectStore[Object Store]
        TxStore[Transaction Store]
    end
    
    subgraph "集群层"
        RAFT[RAFT Consensus]
        Sharding[Sharding]
        Replication[Replication]
    end
    
    Python --> REST
    TS --> REST
    Java --> gRPC
    Go --> gRPC
    CSharp --> gRPC
    
    REST --> Modules
    gRPC --> Modules
    REST --> Search
    gRPC --> Search
    
    Modules --> VectorIndex
    Search --> VectorIndex
    Modules --> ObjectStore
    
    VectorIndex --> RAFT
    ObjectStore --> RAFT
    RAFT --> Sharding
    Sharding --> Replication
```

### 2.1 服务入口点

Weaviate 服务的启动入口位于 `cmd/weaviate-server/main.go`，该文件负责初始化和启动整个服务。资料来源：[cmd/weaviate-server/main.go](https://github.com/weaviate/weaviate/blob/main/cmd/weaviate-server/main.go)

### 2.2 API 服务层

Weaviate 提供三种主要的 API 接口：

| API 类型 | 协议 | 默认端口 | 用途 |
|---------|------|---------|------|
| REST API | HTTP | 8080 | 通用 CRUD 操作，导入/导出 |
| gRPC API | HTTP/2 | 50051 | 高性能搜索和批量操作 |
| GraphQL API | HTTP | 8080 | 复杂查询和数据聚合 |

REST API 服务器在 `adapters/handlers/rest/server.go` 中定义，gRPC API 服务器在 `adapters/handlers/grpc/server.go` 中定义。资料来源：[adapters/handlers/rest/server.go](https://github.com/weaviate/weaviate/blob/main/adapters/handlers/rest/server.go), [adapters/handlers/grpc/server.go](https://github.com/weaviate/weaviate/blob/main/adapters/handlers/grpc/server.go)

## 3. 核心组件

### 3.1 模块系统

Weaviate 采用模块化设计，支持多种向量化和处理模块：

```mermaid
graph LR
    subgraph "向量化和处理模块"
        T2V_Contextionary[text2vec-contextionary]
        T2V_OpenAI[text2vec-openai]
        T2V_Cohere[text2vec-cohere]
        T2V_HuggingFace[text2vec-huggingface]
        Sum_Transformers[sum-transformers]
        Ref2Vec[ref2vec]
    end
    
    subgraph "多向量支持"
        Multi2Vec[multi2vec-*]
    end
```

主要模块包括：

| 模块名称 | 功能描述 | 集成提供商 |
|---------|---------|-----------|
| text2vec-contextionary | 上下文向量化 | Weaviate 原生 |
| text2vec-openai | OpenAI 向量化 | OpenAI |
| text2vec-cohere | Cohere 向量化 | Cohere |
| text2vec-huggingface | HuggingFace 向量化 | HuggingFace |
| text2vec-google | Google 向量化 | Google |
| sum-transformers | 摘要生成 | Transformers |
| multi2vec-* | 多模态向量化 | 多提供商 |

资料来源：[modules/text2vec-contextionary/client/contextionary.go](https://github.com/weaviate/weaviate/blob/main/modules/text2vec-contextionary/client/contextionary.go), [modules/sum-transformers/client/client.go](https://github.com/weaviate/weaviate/blob/main/modules/sum-transformers/client/client.go)

### 3.2 向量索引

Weaviate 使用 HNSW（Hierarchical Navigable Small World）算法作为主要的向量索引结构，提供高效的近似最近邻搜索能力。

### 3.3 集群协议

集群内部通信使用 Protocol Buffers 定义的消息格式，主要消息类型定义在 `cluster/proto/api/message.pb.go` 中。资料来源：[cluster/proto/api/message.pb.go](https://github.com/weaviate/weaviate/blob/main/cluster/proto/api/message.pb.go)

支持的集群操作类型包括：

| 操作类型 | 描述 |
|---------|------|
| TYPE_GET_SHARDING_STATE | 获取分片状态 |
| TYPE_GET_CLASS_VERSIONS | 获取类版本 |
| TYPE_GET_REPLICATION_DETAILS | 获取复制详情 |
| TYPE_GET_NAMESPACES | 获取命名空间 |
| TYPE_RESOLVE_ALIAS | 解析别名 |

## 4. 客户端库

Weaviate 提供官方支持的多种编程语言客户端库：

| 客户端语言 | 文档链接 | 状态 |
|-----------|---------|------|
| Python | [官方文档](https://docs.weaviate.io/weaviate/client-libraries/python) | 官方支持 |
| JavaScript/TypeScript | [官方文档](https://docs.weaviate.io/weaviate/client-libraries/typescript) | 官方支持 |
| Java | [官方文档](https://docs.weaviate.io/weaviate/client-libraries/java) | 官方支持 |
| Go | [官方文档](https://docs.weaviate.io/weaviate/client-libraries/go) | 官方支持 |
| C#/.NET | [官方文档](https://docs.weaviate.io/weaviate/client-libraries/csharp) | 官方支持 |

此外还存在社区维护的客户端库，可在 [官方社区库页面](https://docs.weaviate.io/weaviate/client-libraries/community) 查看。

## 5. 配置管理

Weaviate 的配置管理系统位于 `usecases/config/runtime/` 目录。配置管理器支持热更新功能，允许在运行时动态修改配置而无需重启服务。资料来源：[usecases/config/runtime/manager_test.go](https://github.com/weaviate/weaviate/blob/main/usecases/config/runtime/manager_test.go)

配置管理器的核心特性：

- **热更新支持**：配置文件修改后自动重新加载
- **并发安全**：支持多个协程并发读取配置
- **类型安全**：强类型配置结构
- **验证机制**：配置变更前进行验证

### 5.1 配置示例

```yaml
backup_interval: 10s
```

配置管理器会以指定间隔检查配置文件的变化，并在检测到变更时自动重新加载。

## 6. 监控与遥测

Weaviate 内置遥测系统，用于收集和分析使用数据。遥测仪表板位于 `tools/telemetry-dashboard/` 目录。资料来源：[tools/telemetry-dashboard/README.md](https://github.com/weaviate/weaviate/blob/main/tools/telemetry-dashboard/README.md)

### 6.1 遥测功能

| 功能 | 描述 |
|-----|------|
| 实时数据接收 | 接收 Weaviate 实例发送的遥测 POST 请求 |
| 机器统计 | 按机器 ID 聚合统计 |
| 客户端追踪 | 追踪 Python、Java、TypeScript、Go、C# 客户端使用情况 |
| 模块使用信息 | 记录模块使用情况 |
| 对象和集合统计 | 追踪数据量 |

### 6.2 仪表板启动

```bash
go run tools/telemetry-dashboard/main.go
```

仪表板将在 `http://localhost:8080` 启动，自动刷新间隔为 2 秒。

## 7. 核心功能特性

### 7.1 搜索性能

Weaviate 的架构使用 Go 语言构建，确保高速和可靠性，能够在毫秒级时间内对数十亿向量执行复杂语义搜索。资料来源：[README.md](https://github.com/weaviate/weaviate/blob/main/README.md)

### 7.2 灵活的向量化

支持两种向量化方式：

1. **导入时自动向量化**：使用集成的向量化器在数据导入时自动生成向量
2. **自定义向量**：直接导入预先生成的向量嵌入

### 7.3 混合搜索

Weaviate 支持将语义搜索与传统 BM25 关键词搜索、图像搜索和高级过滤组合使用：

```mermaid
graph LR
    A[查询请求] --> B{Hybrid Search}
    B --> C[Semantic Search<br/>向量相似度]
    B --> D[BM25 Search<br/>关键词匹配]
    C --> E[结果融合]
    D --> E
    E --> F[返回结果]
```

### 7.4 RAG 和重排序

内置生成式搜索（RAG）能力，支持在查询时直接调用 LLM 生成答案，无需额外的应用层处理。

## 8. 集成生态

Weaviate 与多种外部服务集成：

| 类别 | 集成数量 | 主要提供商 |
|-----|---------|----------|
| 云超大规模 | 2+ | AWS, Google |
| 计算基础设施 | 3+ | Modal, Replicate, Replicated |
| 数据平台 | 12+ | Airbyte, Databricks, Confluent |
| LLM 和 Agent 框架 | 5+ | CrewAI, LangChain, LlamaIndex |
| 运维工具 | 10+ | Weights & Biases, Arize, Comet |

## 9. 开发工具

### 9.1 发布说明生成器

位于 `tools/dev/generate_release_notes/` 的工具用于自动生成 GitHub 发布说明：

```bash
GITHUB_TOKEN="<token>" CURRENT_VERSION=v1.26.12 PREVIOUS_VERSION=v1.26.11 go run .
```

### 9.2 索引错误演示 UI

位于 `tools/dev/bench/demo_indexing_mistakes_ui/` 的工具提供索引配置错误的可视化演示，帮助开发者识别和解决常见的索引配置问题。

## 10. 许可

Weaviate 采用 BSD 3-Clause License 开源许可，具体内容详见项目根目录的 LICENSE 文件。

## 11. 社区资源

### 11.1 参与贡献

Weaviate 欢迎社区贡献，贡献指南包括：

- 开发环境设置
- 代码风格规范
- 测试要求
- Pull Request 流程

### 11.2 获取帮助

- [社区论坛](https://forum.weaviate.io/)：讨论想法和获取帮助
- GitHub Issues：报告问题和功能请求
- 官方文档：详细的使用指南和 API 文档

---

<a id='page-core-concepts'></a>

## 核心概念

### 相关页面

相关主题：[项目概述](#page-overview), [LSMKV存储引擎](#page-lsmkv-storage)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [entities/schema/collection.go](https://github.com/weaviate/weaviate/blob/main/entities/schema/collection.go)
- [entities/schema/properties.go](https://github.com/weaviate/weaviate/blob/main/entities/schema/properties.go)
- [entities/models/class.go](https://github.com/weaviate/weaviate/blob/main/entities/models/class.go)
- [entities/models/object.go](https://github.com/weaviate/weaviate/blob/main/entities/models/object.go)
- [entities/models/property.go](https://github.com/weaviate/weaviate/blob/main/entities/models/property.go)
- [usecases/schema/parser.go](https://github.com/weaviate/weaviate/blob/main/usecases/schema/parser.go)
</details>

# 核心概念

Weaviate 是一个开源的云原生向量数据库，同时存储对象和向量，支持大规模语义搜索。本页详细介绍 Weaviate 的核心数据概念和架构，帮助开发者理解其数据模型、查询机制和系统设计。

## 数据模型概述

Weaviate 的数据模型采用面向对象的设计，核心概念包括：

- **Collection（集合）**：相当于传统数据库中的"表"或"类"
- **Object（对象）**：存储在集合中的具体数据记录
- **Property（属性）**：对象包含的各个字段
- **Vector（向量）**：对象的语义表示，用于相似度搜索

```mermaid
graph TB
    subgraph Weaviate数据模型
        C[Collection<br/>集合]
        O[Object<br/>对象]
        P[Property<br/>属性]
        V[Vector<br/>向量]
    end
    
    C --> O
    O --> P
    O --> V
```

资料来源：[entities/models/class.go:1-50](https://github.com/weaviate/weaviate/blob/main/entities/models/class.go)

## Collection（集合）

Collection 是 Weaviate 中组织数据的基本单元，对应传统数据库中的表或文档集合的概念。每个 Collection 拥有独立的名称、配置和向量索引。

### Collection 的核心属性

| 属性 | 类型 | 说明 |
|------|------|------|
| `Name` | string | Collection 的唯一标识名称 |
| `Description` | string | Collection 的描述信息 |
| `Properties` | []Property | 数据属性定义 |
| `VectorIndexType` | string | 向量索引类型（如 HNSW） |
| `Vectorizer` | string | 向量化模块配置 |
| `ModuleConfig` | map | 模块特定配置 |

资料来源：[entities/schema/collection.go:15-80](https://github.com/weaviate/weaviate/blob/main/entities/schema/collection.go)

### Collection 配置

Collection 的配置决定了数据的存储方式和查询行为：

```go
type Class struct {
    Class             string           `json:"class"`
    Description       string           `json:"description,omitempty"`
    Vectorizer        string           `json:"vectorizer,omitempty"`
    Properties        []*Property      `json:"properties,omitempty"`
    VectorIndexConfig VectorIndexConfig `json:"vectorIndexConfig,omitempty"`
    // ... 其他配置字段
}
```

资料来源：[entities/models/class.go:40-60](https://github.com/weaviate/weaviate/blob/main/entities/models/class.go)

## Property（属性）

Property 定义了 Collection 中每个 Object 可以包含的数据字段。每个 Property 都有特定的数据类型，支持多种字段类型。

### 支持的数据类型

| 数据类型 | 说明 | 示例 |
|----------|------|------|
| `text` | 文本数据 | 标题、描述 |
| `int` | 整数 | ID、计数 |
| `number` | 浮点数 | 价格、评分 |
| `boolean` | 布尔值 | 状态标志 |
| `date` | 日期时间 | 创建时间 |
| `geoCoordinates` | 地理坐标 | 经纬度 |
| `phoneNumber` | 电话号码 | 联系方式 |
| `blob` | 二进制数据 | 图片、文件 |
| `object` | 嵌套对象 | 复杂结构数据 |
| `text[]` | 文本数组 | 标签列表 |

资料来源：[entities/schema/properties.go:10-50](https://github.com/weaviate/weaviate/blob/main/entities/schema/properties.go)

### Property 定义结构

```go
type Property struct {
    Name        string     `json:"name"`
    Description string     `json:"description,omitempty"`
    DataType    []string   `json:"dataType"`
    IndexInverted *bool    `json:"indexInverted,omitempty"`
    IndexSearchable *bool  `json:"indexSearchable,omitempty"`
    Tokenization string    `json:"tokenization,omitempty"`
    NestedProperties []*Property `json:"nestedProperties,omitempty"`
}
```

资料来源：[entities/models/property.go:30-55](https://github.com/weaviate/weaviate/blob/main/entities/models/property.go)

## Object（对象）

Object 是存储在 Collection 中的具体数据记录。每个 Object 包含属性数据和对应的向量表示。

### Object 结构

```go
type Object struct {
    Class              string              `json:"class"`
    CreationTimeUnix   int64               `json:"creationTimeUnix"`
    LastUpdateTimeUnix int64               `json:"lastUpdateTimeUnix"`
    ID                 strfmt.UUID          `json:"id"`
    Vector             []float32            `json:"vector,omitempty"`
    Properties         map[string]interface{} `json:"properties"`
    VectorWeights      map[string]float64  `json:"vectorWeights,omitempty"`
}
```

资料来源：[entities/models/object.go:35-60](https://github.com/weaviate/weaviate/blob/main/entities/models/object.go)

### Object 的生命周期

```mermaid
graph LR
    A[创建 Object] --> B[自动向量化]
    B --> C[存储到向量索引]
    C --> D[存储到对象存储]
    D --> E[更新 Object]
    E --> F[重新索引]
    F --> G[删除 Object]
    G --> H[标记删除]
```

## Schema（模式）

Schema 是 Collection 定义的集合，定义了数据库的完整结构。Weaviate 使用 Schema 来验证和解析数据。

### Schema 解析器

Schema 解析器负责验证 Collection 和 Property 定义的合法性：

```go
func (p *Parser) ParseClass(src interface{}) (*models.Class, error) {
    // 解析 Collection 定义
    // 验证 Property 配置
    // 应用默认值
}
```

资料来源：[usecases/schema/parser.go:50-120](https://github.com/weaviate/weaviate/blob/main/usecases/schema/parser.go)

### Schema 示例

```json
{
  "classes": [
    {
      "class": "Article",
      "description": "新闻文章集合",
      "properties": [
        {
          "name": "title",
          "dataType": ["text"],
          "indexSearchable": true
        },
        {
          "name": "content",
          "dataType": ["text"],
          "indexSearchable": true
        },
        {
          "name": "author",
          "dataType": ["text"]
        },
        {
          "name": "publishDate",
          "dataType": ["date"]
        }
      ],
      "vectorizer": "text2vec-contextionary"
    }
  ]
}
```

## 向量与索引

Weaviate 的核心能力之一是向量相似度搜索。数据导入时可以自动向量化，也可以使用预先计算好的向量。

### 向量索引类型

| 索引类型 | 说明 | 适用场景 |
|----------|------|----------|
| `hnsw` | Hierarchical Navigable Small World | 默认索引，高查询性能 |
| `dynamic` | 动态索引 | 数据变化频繁的场景 |
| `flat` | 暴力索引 | 小数据集，精确搜索 |

### HFresh 向量索引

v1.37.0 版本引入的 HFresh（GA）是一个重要的向量索引优化，提供了大量性能改进：

- 减少内存使用
- 降低磁盘写入
- 优化内存分配

资料来源：社区发布说明 [v1.37.0](https://github.com/weaviate/weaviate/releases/tag/v1.37.0)

## 搜索能力

Weaviate 提供多种搜索模式，可以组合使用：

### 向量搜索 (Vector Search)

基于语义相似度进行搜索，将查询文本向量化后与存储的向量进行比较。

### 关键词搜索 (BM25)

基于传统 TF-IDF 算法的关键词搜索，适合精确匹配场景。

### 混合搜索 (Hybrid Search)

结合向量搜索和 BM25 的优势，使用以下公式计算综合得分：

```
score = (1 - alpha) * vector_score + alpha * bm25_score
```

其中 `alpha` 参数控制两种搜索方式的权重（0 = 纯向量搜索，1 = 纯关键词搜索）。

> **社区注意**：元数据过滤器在混合搜索中的行为有时不符合预期，参见 [Issue #11262](https://github.com/weaviate/weaviate/issues/11262)。

### 过滤机制

Weaviate 支持在搜索时添加属性过滤器，支持的运算符包括：

| 运算符 | 说明 | 示例 |
|--------|------|------|
| `Equal` | 等于 | `title == "Hello"` |
| `NotEqual` | 不等于 | `status != "deleted"` |
| `GreaterThan` | 大于 | `price > 100` |
| `LessThan` | 小于 | `rating < 4.0` |
| `And` | 逻辑与 | `status == "active" && price < 50` |
| `Or` | 逻辑或 | `category == "A" or category == "B"` |

> **功能请求**：社区正在请求添加 `Not` 操作符以支持 "Not Like" 等过滤场景，参见 [Issue #3683](https://github.com/weaviate/weaviate/issues/3683)。

## 模块系统

Weaviate 采用模块化架构，通过模块扩展核心功能。

### 向量化模块

| 模块 | 说明 |
|------|------|
| `text2vec-contextionary` | Weaviate 自研词向量 |
| `text2vec-transformers` | HuggingFace Transformer 模型 |
| `multi2vec-clip` | 多模态（图像+文本）向量 |
| `text2vec-openai` | OpenAI Embeddings |
| `text2vec-cohere` | Cohere Embeddings |

### 生成模块

| 模块 | 说明 |
|------|------|
| `generative-openai` | OpenAI GPT 生成 |
| `generative-anthropic` | Anthropic Claude 生成 |

### 可扩展分词器

v1.37.0 引入的可扩展分词器允许用户自定义文本处理流程：

```yaml
properties:
- name: content
  dataType: ["text"]
  tokenization: "whitespace"
```

资料来源：[v1.37.0-rc.1 发布说明](https://github.com/weaviate/weaviate/releases/tag/v1.37.0-rc.1)

## 多租户与命名空间

v1.38.0 引入了 Namespaces 功能，允许在同一 Weaviate 实例中创建逻辑隔离的数据空间。

### 多租户配置

```go
type CollectionConfig struct {
    MultiTenancyConfig MultiTenancyConfig `json:"multiTenancyConfig,omitempty"`
}
```

多租户模式下，数据按租户隔离，适合 SaaS 应用场景。

## 备份与恢复

Weaviate 支持多种备份存储后端：

| 后端类型 | 说明 |
|----------|------|
| `filesystem` | 本地文件系统 |
| `s3` | Amazon S3 或兼容存储 |
| `gcs` | Google Cloud Storage |
| `azure` | Azure Blob Storage |

### 增量备份

v1.37.0 引入的增量备份功能显著减少了备份时间和存储空间：

```bash
# 创建增量备份
POST /v1/backups/{backend}?wait=1

{
  "id": "backup- incremental-001",
  "include": ["Article"]
}
```

## 集群与复制

Weaviate 支持分布式部署，提供高可用性和水平扩展能力。

### 复制策略

| 策略 | 说明 | 适用场景 |
|------|------|----------|
| `eventual` | 最终一致性 | 追求性能，可容忍短暂不一致 |
| `consistent` | 强一致性 | 数据关键应用 |

### RAFT 共识

Weaviate 使用 RAFT 协议进行集群节点间的状态同步，确保分布式环境下的一致性。

> **稳定性修复**：近期版本持续修复 RAFT 相关问题，包括 v1.36.13 和 v1.35.19 的递归 RAFT 命令修复。

## 配置管理

Weaviate 支持运行时配置热更新，通过 `ConfigManager` 实现：

```go
type ConfigManager[T any] struct {
    path     string
    interval time.Duration
    parse    Parser[T]
    update   Updater[T]
}
```

配置文件使用 YAML 格式，支持热重载：

```yaml
backup_interval: 10s
```

资料来源：[usecases/config/runtime/manager.go:20-45](https://github.com/weaviate/weaviate/blob/main/usecases/config/runtime/manager.go)

## 快速开始示例

以下是一个完整的 Weaviate 使用流程：

```python
import weaviate

# 连接 Weaviate
client = weaviate.Client("http://localhost:8080")

# 定义 Collection
article_schema = {
    "class": "Article",
    "description": "新闻文章",
    "properties": [
        {"name": "title", "dataType": ["text"]},
        {"name": "content", "dataType": ["text"]},
        {"name": "category", "dataType": ["text"]}
    ],
    "vectorizer": "text2vec-contextionary"
}

# 创建 Collection
client.schema.create_class(article_schema)

# 导入数据
client.data_object.create(
    class_name="Article",
    data_object={
        "title": "Weaviate 核心概念介绍",
        "content": "本文详细介绍 Weaviate 的核心概念...",
        "category": "技术文档"
    }
)

# 混合搜索
results = client.query.get("Article", ["title", "content", "category"]) \
    .with_hybrid("向量数据库概念", alpha=0.7) \
    .with_limit(10) \
    .do()

client.close()
```

## 常见问题与限制

### 社区关注的特性请求

| Issue | 描述 | 状态 |
|-------|------|------|
| [#2124](https://github.com/weaviate/weaviate/issues/2124) | 批量更新支持（Partial Update） | 开放 |
| [#2465](https://github.com/weaviate/weaviate/issues/2465) | 对象支持多个向量 | 开放 |
| [#3694](https://github.com/weaviate/weaviate/issues/3694) | 嵌套对象过滤和向量化 | 进行中 |
| [#3683](https://github.com/weaviate/weaviate/issues/3683) | 添加 Not 操作符 | 开放 |

### 已知问题

- 混合搜索中元数据过滤器可能不生效（[#11262](https://github.com/weaviate/weaviate/issues/11262)）

## 相关资源

- [Weaviate 官方文档](https://docs.weaviate.io)
- [Python 客户端文档](https://docs.weaviate.io/weaviate/client-libraries/python)
- [GraphQL API 参考](https://docs.weaviate.io/weaviate/api/graphql)
- [REST API 参考](https://docs.weaviate.io/weaviate/api/rest)
- [gRPC API 参考](https://docs.weaviate.io/weaviate/api/grpc)

---

<a id='page-architecture'></a>

## 系统架构

### 相关页面

相关主题：[项目概述](#page-overview), [API层实现](#page-api-layer), [集群与复制机制](#page-cluster-replication)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [adapters/handlers/rest/configure_api.go](https://github.com/weaviate/weaviate/blob/main/adapters/handlers/rest/configure_api.go)
- [adapters/handlers/rest/configure_server.go](https://github.com/weaviate/weaviate/blob/main/adapters/handlers/rest/configure_server.go)
- [adapters/handlers/grpc/v1/service.go](https://github.com/weaviate/weaviate/blob/main/adapters/handlers/grpc/v1/service.go)
- [usecases/objects/manager.go](https://github.com/weaviate/weaviate/blob/main/usecases/objects/manager.go)
- [usecases/schema/manager.go](https://github.com/weaviate/weaviate/blob/main/usecases/schema/manager.go)
- [cluster/service.go](https://github.com/weaviate/weaviate/blob/main/cluster/service.go)
</details>

# 系统架构

Weaviate 是一个用 Go 语言编写的云原生向量数据库，其系统架构采用分层设计，核心由**API 层**、**业务逻辑层**、**集群管理层**和**存储层**组成。这种分层架构使得 Weaviate 能够同时支持向量相似性搜索、关键词过滤（BM25）、检索增强生成（RAG）以及重排序等功能。 资料来源：[README.md]()

## 整体架构概览

Weaviate 的架构设计遵循**适配器模式**，将外部通信协议（REST/gRPC）与内部业务逻辑解耦。整个系统可分为以下几个核心层次：

```mermaid
graph TD
    A[客户端] --> B[API 层<br/>REST API / gRPC API]
    B --> C[业务逻辑层<br/>Use Cases]
    C --> D[集群管理层<br/>Cluster Service]
    C --> E[存储层<br/>Vector Index + Object Store]
    D --> F[RAFT 共识]
    E --> G[HNSW 索引]
    E --> H[对象存储]
```

## API 层

Weaviate 提供多种 API 接口供客户端访问，包括 REST API、gRPC API 和 GraphQL API。

### REST API

REST API 是主要的 HTTP 接口，负责处理客户端请求并进行协议转换。API 配置通过 `configure_api.go` 完成，其中定义了各端点的路由映射和中间件配置。 资料来源：[adapters/handlers/rest/configure_api.go]()

REST API 的核心功能包括：

- 集合（Collection）管理：创建、更新、删除集合
- 对象（Object）操作：插入、查询、更新、删除对象
- 搜索接口：向量搜索、BM25 搜索、混合搜索
- 向量压缩配置
- 备份与恢复

### gRPC API

gRPC API 提供高性能的二进制协议通信，适用于对延迟敏感的场景。gRPC 服务层通过 `adapters/handlers/grpc/v1/service.go` 实现，定义了分布式任务的处理接口。 资料来源：[adapters/handlers/grpc/v1/service.go]()

gRPC API 支持的查询类型定义在 `cluster/proto/api/message.pb.go` 中：

| 类型常量 | 说明 | 用途 |
|---------|------|------|
| TYPE_GET_CLASSES | 获取类列表 | 元数据查询 |
| TYPE_GET_SCHEMA | 获取完整 schema | Schema 查询 |
| TYPE_GET_TENANTS | 获取租户信息 | 多租户支持 |
| TYPE_GET_REPLICATION_DETAILS | 获取复制详情 | 集群状态 |
| TYPE_DISTRIBUTED_TASK_LIST | 分布式任务列表 | 分布式计算 |
| TYPE_GET_NAMESPACES | 获取命名空间 | 命名空间支持 |

资料来源：[cluster/proto/api/message.pb.go]()

## 业务逻辑层

业务逻辑层（Use Cases）是系统的核心，包含了对象管理、Schema 管理等关键业务逻辑。

### 对象管理器

对象管理器（Objects Manager）负责处理所有对象级别的操作，包括增删改查和批量处理。对象管理器通过 `usecases/objects/manager.go` 实现，提供了对象生命周期的完整管理能力。 资料来源：[usecases/objects/manager.go]()

对象管理器的主要职责：

- **对象导入**：批量导入对象，支持自动向量化
- **对象查询**：根据 ID 或条件查询对象
- **对象更新**：部分更新（Partial Update），支持批量操作
- **对象删除**：单条删除和批量删除
- **TTL 管理**：对象存活时间管理，支持租户自动停用

### Schema 管理器

Schema 管理器负责定义和管理数据模型，包括集合配置、属性定义和索引设置。Schema 管理的核心实现在 `usecases/schema/manager.go` 中。 资料来源：[usecases/schema/manager.go]()

Schema 管理器支持的功能：

- 集合的创建、修改和删除
- 属性配置（数据类型、索引选项）
- 向量索引配置（HNSW 参数调优）
- 多租户配置（TENANT ACTIVITY STATUS）
- 别名管理

### 模块系统

Weaviate 采用模块化设计，支持多种向量化模块和数据处理模块。主要模块包括：

| 模块类型 | 示例 | 功能 |
|---------|------|------|
| 向量化模块 | text2vec-contextionary, multi2vec-google | 文本/图像向量化 |
| 摘要模块 | sum-transformers | 文本摘要生成 |
| 重排序模块 | reranker-cohere, reranker-transformers | 搜索结果重排序 |

向量化客户端（如 `modules/text2vec-contextionary/client/contextionary.go`）负责与外部向量化服务通信，支持 Schema 语义搜索功能。 资料来源：[modules/text2vec-contextionary/client/contextionary.go]()

## 集群管理层

Weaviate 内置分布式集群管理能力，通过 RAFT 共识协议实现节点间的一致性协调。

### 集群服务

集群服务的核心实现在 `cluster/service.go` 中，提供了节点发现、领导者选举和分布式协调能力。 资料来源：[cluster/service.go]()

```mermaid
graph TD
    A[节点 A] -->|RAFT| B[领导者节点]
    A -->|数据同步| C[(分布式存储)]
    B -->|复制| D[节点 B]
    B -->|复制| E[节点 C]
```

### 复制与分片

Weaviate 采用分片（Sharding）策略将数据分布到多个节点，每个分片可以有多个副本以保证高可用性：

- **分片策略**：基于哈希的分片，每个集合可配置分片数量
- **副本同步**：使用 RAFT 协议保证副本间一致性
- **故障转移**：节点故障时自动触发副本重新分配

### 分布式任务

gRPC 层支持分布式任务的协调执行，包括：

- 任务准备阶段（Preparation）
- 任务分发（Distribution）
- 结果聚合（Aggregation）

分布式任务请求结构定义包含：命名空间、任务 ID、负载数据、提交时间戳和单元规格。 资料来源：[cluster/proto/api/message.pb.go]()

## 存储层

存储层负责数据的持久化，包含向量索引和对象存储两大核心组件。

### HNSW 向量索引

HNSW（Hierarchical Navigable Small World）是最常用的 ANN（Approximate Nearest Neighbor）算法实现，用于高效的高维向量相似性搜索。Weaviate 的 HNSW 实现支持：

- **距离度量**：余弦距离、点积距离、欧几里得距离
- **压缩支持**：PQ（Product Quantization）压缩，减少内存占用
- **参数调优**：efConstruction、maxConnections 等参数优化

### 对象存储

对象存储负责存储数据的原始属性，支持：

- **数据类型**：字符串、整数、浮点数、布尔值、日期、地理位置、嵌套对象
- **倒排索引**：支持属性过滤和 BM25 搜索
- **TTL 索引**：对象生命周期管理

### 备份系统

Weaviate 支持完整备份和增量备份：

- **完整备份**：快照整个集合或命名空间
- **增量备份**：仅备份变更数据
- **存储后端**：支持 S3、GCS、Azure Blob 等云存储

## 配置管理

Weaviate 使用配置管理器（ConfigManager）实现配置的动态更新，配置文件变更可以热加载而无需重启服务。配置管理器通过 `usecases/config/runtime/manager_test.go` 实现了线程安全的配置访问机制。 资料来源：[usecases/config/runtime/manager_test.go]()

支持的配置项包括：

- `backup_interval`：备份间隔时间
- 向量化参数
- 集群通信参数

## 核心工作流程

### 数据导入流程

```mermaid
sequenceDiagram
    客户端->>REST API: POST /objects (批量导入)
    REST API->>对象管理器: 创建对象请求
    对象管理器->>Schema管理器: 验证 Schema
    对象管理器->>模块系统: 请求向量化
    模块系统-->>对象管理器: 返回向量
    对象管理器->>存储层: 存储对象和向量
    存储层->>对象管理器: 确认写入
    对象管理器-->>REST API: 返回结果
    REST API-->>客户端: 200 OK
```

### 搜索查询流程

```mermaid
sequenceDiagram
    客户端->>REST API: 混合搜索请求
    REST API->>对象管理器: 解析查询条件
    对象管理器->>存储层: HNSW 搜索
    存储层-->>对象管理器: 向量搜索结果
    对象管理器->>存储层: BM25 搜索
    存储层-->>对象管理器: 关键词搜索结果
    对象管理器->>对象管理器: 结果融合
    对象管理器->>模块系统: 生成式搜索 (RAG)
    模块系统-->>对象管理器: 生成结果
    对象管理器-->>REST API: 返回结果
    REST API-->>客户端: 搜索结果
```

## 社区关注的功能与问题

根据社区反馈，以下功能和问题受到较多关注：

| Issue | 说明 | 相关模块 |
|-------|------|---------|
| #11262 | 元数据过滤在混合搜索中不工作 | 搜索 + 过滤 |
| #2124 | 批量补丁（部分更新）性能问题，40 万条记录更新需约 20 小时 | 对象管理 |
| #2465 | 支持对象上的多个向量索引 | 向量存储 |
| #3683 | 缺少 NOT 操作符实现过滤排除 | 过滤系统 |

## 总结

Weaviate 的系统架构体现了现代化的云原生设计理念：

1. **分层解耦**：API 层与业务逻辑分离，便于扩展和维护
2. **多协议支持**：REST、gRPC、GraphQL 多种接口满足不同场景需求
3. **内置分布式**：RAFT 共识和分片机制提供开箱即用的分布式能力
4. **模块化设计**：向量化、摘要、重排序等功能可插拔
5. **高性能**：Go 语言实现结合 HNSW 算法，支持毫秒级查询

这种架构设计使 Weaviate 能够高效处理海量向量数据的存储和检索，同时保持良好的可扩展性和容错能力。

---

<a id='page-api-layer'></a>

## API层实现

### 相关页面

相关主题：[系统架构](#page-architecture), [混合搜索实现](#page-hybrid-search)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [adapters/handlers/rest/handlers_objects.go](https://github.com/weaviate/weaviate/blob/main/adapters/handlers/rest/handlers_objects.go)
- [adapters/handlers/rest/handlers_schema.go](https://github.com/weaviate/weaviate/blob/main/adapters/handlers/rest/handlers_schema.go)
- [adapters/handlers/grpc/v1/batch/handler.go](https://github.com/weaviate/weaviate/blob/main/adapters/handlers/grpc/v1/batch/handler.go)
- [adapters/handlers/grpc/v1/parse_search_request.go](https://github.com/weaviate/weaviate/blob/main/adapters/handlers/grpc/v1/parse_search_request.go)
- [adapters/handlers/grpc/v1/prepare_reply.go](https://github.com/weaviate/weaviate/blob/main/adapters/handlers/grpc/v1/prepare_reply.go)
- [grpc/proto/v1/weaviate.proto](https://github.com/weaviate/weaviate/blob/main/grpc/proto/v1/weaviate.proto)
- [cluster/proto/api/message.pb.go](https://github.com/weaviate/weaviate/blob/main/cluster/proto/api/message.pb.go)
- [modules/text2vec-contextionary/client/contextionary.go](https://github.com/weaviate/weaviate/blob/main/modules/text2vec-contextionary/client/contextionary.go)
</details>

# API层实现

## 概述

Weaviate的API层是系统的核心接口，负责处理客户端请求并协调底层存储和检索功能。该层采用多层架构设计，同时支持REST和gRPC两种通信协议，为不同场景提供高效的API访问能力。

Weaviate提供三种主要的API接口：

| API类型 | 协议 | 特点 | 适用场景 |
|---------|------|------|----------|
| REST API | HTTP/1.1 | 易于使用，兼容性好 | Web应用，简单集成 |
| gRPC API | HTTP/2 | 高性能，低延迟 | 高吞吐场景，批量操作 |
| GraphQL API | HTTP/1.1 | 灵活查询 | 复杂查询，关联数据 |

资料来源：[README.md](https://github.com/weaviate/weaviate/blob/main/README.md)

## 架构设计

### API层组件结构

```mermaid
graph TD
    A[客户端请求] --> B{REST API}
    A --> C{gRPC API}
    B --> D[REST Handlers]
    C --> E[gRPC Handlers]
    D --> F[业务逻辑层]
    E --> F
    F --> G[存储层]
    F --> H[向量化模块]
    G --> I[向量索引 HNSW]
    G --> J[对象存储]
```

### 协议定义

API层的核心协议定义位于 `grpc/proto/v1/weaviate.proto`，定义了所有gRPC服务的接口规范。这些proto文件会被编译成各语言的客户端和服务端代码。

主要服务包括：

- **WeaviateService** - 主服务，处理搜索、对象操作等核心功能
- **BatchService** - 批量操作服务，用于高效导入大量数据
- **ClusterService** - 集群内部通信服务

资料来源：[grpc/proto/v1/weaviate.proto](https://github.com/weaviate/weaviate/blob/main/grpc/proto/v1/weaviate.proto)

## REST API实现

### 对象操作处理器

`handlers_objects.go` 文件实现了REST风格的对象操作接口，包括CRUD操作：

```go
// 主要处理函数签名示例
func (h *Handlers) CreateObject(params ...) middleware.Responder
func (h *Handlers) GetObject(params ...) middleware.Responder
func (h *Handlers) UpdateObject(params ...) middleware.Responder
func (h *Handlers) DeleteObject(params ...) middleware.Responder
```

核心功能：

| 功能 | HTTP方法 | 端点 | 说明 |
|------|----------|------|------|
| 创建对象 | POST | /v1/objects | 插入单个对象 |
| 批量创建 | POST | /v1/batch/objects | 批量导入对象 |
| 查询对象 | GET | /v1/objects/{id} | 根据ID获取对象 |
| 更新对象 | PUT | /v1/objects/{id} | 更新现有对象 |
| 删除对象 | DELETE | /v1/objects/{id} | 删除指定对象 |
| 搜索对象 | POST | /v1/graphql | GraphQL查询接口 |

资料来源：[adapters/handlers/rest/handlers_objects.go](https://github.com/weaviate/weaviate/blob/main/adapters/handlers/rest/handlers_objects.go)

### Schema操作处理器

Schema处理器负责管理数据集合的定义，包括创建、修改和删除Collection（Collection = 传统意义上的Class）。

```go
// Schema处理函数
func (h *Handlers) CreateCollection(params ...) middleware.Responder
func (h *Handlers) GetCollection(params ...) middleware.Responder
func (h *Handlers) UpdateCollection(params ...) middleware.Responder
func (h *Handlers) DeleteCollection(params ...) middleware.Responder
```

资料来源：[adapters/handlers/rest/handlers_schema.go](https://github.com/weaviate/weaviate/blob/main/adapters/handlers/rest/handlers_schema.go)

## gRPC API实现

### gRPC处理架构

gRPC API采用分层处理架构，核心组件位于 `adapters/handlers/grpc/v1/` 目录：

```mermaid
graph LR
    A[gRPC请求] --> B[Handler入口]
    B --> C[请求解析 parse_search_request.go]
    C --> D[业务逻辑处理]
    D --> E[响应准备 prepare_reply.go]
    E --> F[gRPC响应]
```

### 批量操作处理器

批量操作是gRPC API的重要组成部分，特别适用于大规模数据导入场景：

```go
// 批量处理器核心接口
type BatchHandler interface {
    AddObjects(context.Context, *grpc.BatchAddObjectsRequest) (*grpc.BatchAddObjectsReply, error)
    DeleteObjects(context.Context, *grpc.BatchDeleteObjectsRequest) (*grpc.BatchDeleteObjectsReply, error)
}
```

批量操作支持：

- **AddObjects** - 批量添加对象，支持向量化
- **DeleteObjects** - 批量删除对象
- **BatchReference** - 批量创建对象间引用关系

资料来源：[adapters/handlers/grpc/v1/batch/handler.go](https://github.com/weaviate/weaviate/blob/main/adapters/handlers/grpc/v1/batch/handler.go)

### 请求解析模块

`parse_search_request.go` 负责将gRPC协议格式的搜索请求转换为内部数据模型：

```go
// 搜索请求解析函数
func ParseSearchRequest(req *grpc.SearchRequest, scheme *models.Schema) (*search.Request, error)
func ParseHybridRequest(req *grpc.HybridSearch, scheme *models.Schema) (*search.HybridParams, error)
func ParseBM25Request(req *grpc.BM25Search, scheme *models.Schema) (*search.BM25Params, error)
func ParseNearVectorRequest(req *grpc.NearVector, scheme *models.Schema) (*search.NearVectorParams, error)
```

支持的搜索类型：

| 搜索类型 | 参数 | 说明 |
|----------|------|------|
| 混合搜索 | HybridSearch | 结合向量相似度和关键词搜索 |
| BM25搜索 | BM25Search | 纯关键词搜索，基于TF-IDF |
| 向量搜索 | NearVector | 基于向量相似度检索 |
| 近文本搜索 | NearText | 基于文本语义向量检索 |
| 近图像搜索 | NearImage | 基于图像向量检索 |

资料来源：[adapters/handlers/grpc/v1/parse_search_request.go](https://github.com/weaviate/weaviate/blob/main/adapters/handlers/grpc/v1/parse_search_request.go)

### 响应格式化模块

`prepare_reply.go` 负责将内部数据格式转换为gRPC响应格式：

```go
// 响应准备函数
func PrepareSearchReply(results *search.Results, msg *grpc.SearchReply) error
func PrepareObjectReply(obj *models.Object, msg *grpc.ObjectReply) error
```

该模块处理：

- 对象数据的Protobuf序列化
- 向量数据的格式转换
- 元数据的过滤和投影
- 分页信息的处理

资料来源：[adapters/handlers/grpc/v1/prepare_reply.go](https://github.com/weaviate/weaviate/blob/main/adapters/handlers/grpc/v1/prepare_reply.go)

## 协议缓冲区定义

### Proto消息类型

Weaviate的gRPC协议定义包含丰富的消息类型，用于精确描述API请求和响应：

```protobuf
// 核心消息类型示例
message SearchRequest {
    string collection = 1;
    int32 limit = 2;
    int32 offset = 3;
    SearchParams params = 4;
    vector<string> additional = 5;
}

message SearchReply {
    repeated SearchResult results = 1;
    int64 took_ms = 2;
}
```

### Cluster内部通信

集群节点间的通信同样使用Protocol Buffers定义，位于 `cluster/proto/api/message.pb.go`：

| 消息类型 | 用途 |
|----------|------|
| AddDistributedTaskRequest | 添加分布式任务请求 |
| RecordDistributedTaskUnitCompletionRequest | 任务单元完成记录 |
| CleanUpDistributedTaskRequest | 清理分布式任务 |
| RecordDistributedTaskPreparationCompleteAckRequest | 任务准备完成确认 |

资料来源：[cluster/proto/api/message.pb.go](https://github.com/weaviate/weaviate/blob/main/cluster/proto/api/message.pb.go)

## 向量化模块接口

### Contextionary客户端

Contextionary是Weaviate内置的词向量模块，通过gRPC与主服务通信：

```go
// Contextionary客户端接口
type Client interface {
    SchemaSearch(ctx context.Context, params traverser.SearchParams) (traverser.SearchResults, error)
    GetVectorForWord(ctx context.Context, word string) ([]float32, error)
    IsWordPresent(ctx context.Context, word string) (bool, error)
}
```

搜索类型支持：

| 类型 | 说明 |
|------|------|
| SearchTypeClass | 在Collection级别搜索 |
| SearchTypeProperty | 在属性级别搜索 |

资料来源：[modules/text2vec-contextionary/client/contextionary.go](https://github.com/weaviate/weaviate/blob/main/modules/text2vec-contextionary/client/contextionary.go)

## 社区相关问题

### 元数据过滤问题

社区反馈在n8n集成中使用混合搜索时，元数据过滤器无法正常工作（Issue #11262）。该问题影响使用Weaviate Vector Store节点进行混合查询的场景。

**问题表现**：

1. 创建包含文本类型元数据字段的向量存储
2. 添加至少两条不同元数据值的记录
3. 使用"Hybrid: Query Text"选项进行搜索
4. 元数据过滤条件被忽略

### 批量更新需求

社区长期关注批量更新（Patch/Partial Update）功能（Issue #2124）。当前需要逐个更新对象，40万条记录的更新可能需要约20小时。用户期望的批量更新功能可显著提升大规模数据维护效率。

### 过滤操作符缺失

社区请求添加"Not"操作符以支持"Not Like"等排除式过滤（Issue #3683）。此前有缺陷的Not操作符已被移除，目前缺乏排除匹配的过滤能力。

## 性能优化

### 压缩向量索引缓存

近期版本优化了压缩向量索引缓存，减少内存占用和磁盘写入：

- 优化内存分配策略
- 减少不必要的磁盘IO操作
- 提升缓存命中率

资料来源：[v1.35.19 Release Notes](https://github.com/weaviate/weaviate/releases/tag/v1.35.19)

### 启动速度优化

通过增加数据库状态检查频率优化启动速度，减少服务不可用时间：

```go
// 优化后的状态检查逻辑
startup: speedup startup by checking db status more often
```

资料来源：[v1.37.1 Release Notes](https://github.com/weaviate/weaviate/releases/tag/v1.37.1)

## 配置管理

### 运行时配置加载

API层使用 `ConfigManager` 实现配置的热更新：

```go
// 配置管理器
type ConfigManager[T any] struct {
    path      string              // 配置文件路径
    interval  time.Duration      // 加载间隔
    parse     Parser[T]           // 配置解析器
    update    Updater[T]          // 配置更新器
    hooks     map[string]func() error  // 回调钩子
}
```

配置变更流程：

```mermaid
graph TD
    A[配置文件变更] --> B[ConfigManager检测]
    B --> C[解析新配置]
    C --> D{解析成功?}
    D -->|是| E[应用新配置]
    D -->|否| F[保持旧配置]
    E --> G[触发回调钩子]
    F --> H[记录错误日志]
```

资料来源：[usecases/config/runtime/manager.go](https://github.com/weaviate/weaviate/blob/main/usecases/config/runtime/manager.go)

## 客户端库

Weaviate官方提供多语言客户端库：

| 语言 | 仓库 | 说明 |
|------|------|------|
| Python | weaviate-client | 官方维护，功能完整 |
| JavaScript/TypeScript | weaviate-client | 官方维护 |
| Java | weaviate-java-client | 官方维护 |
| Go | go-client | 官方维护 |
| C#/.NET | csharp-client | 官方维护 |

社区维护的额外客户端库可在官方文档查看。

## 相关文档

- [REST API参考](https://docs.weaviate.io/weaviate/api/rest)
- [gRPC API参考](https://docs.weaviate.io/weaviate/api/grpc)
- [GraphQL API参考](https://docs.weaviate.io/weaviate/api/graphql)
- [客户端库文档](https://docs.weaviate.io/weaviate/client-libraries/python)

---

<a id='page-lsmkv-storage'></a>

## LSMKV存储引擎

### 相关页面

相关主题：[向量索引实现](#page-vector-indexes), [集群与复制机制](#page-cluster-replication)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [adapters/repos/db/lsmkv/bucket.go](https://github.com/weaviate/weaviate/blob/main/adapters/repos/db/lsmkv/bucket.go)
- [adapters/repos/db/lsmkv/segment_group.go](https://github.com/weaviate/weaviate/blob/main/adapters/repos/db/lsmkv/segment_group.go)
- [adapters/repos/db/lsmkv/store.go](https://github.com/weaviate/weaviate/blob/main/adapters/repos/db/lsmkv/store.go)
- [adapters/repos/db/lsmkv/compactor_replace.go](https://github.com/weaviate/weaviate/blob/main/adapters/repos/db/lsmkv/compactor_replace.go)
- [adapters/repos/db/lsmkv/compactor_map.go](https://github.com/weaviate/weaviate/blob/main/adapters/repos/db/lsmkv/compactor_map.go)
- [adapters/repos/db/lsmkv/memtable.go](https://github.com/weaviate/weaviate/blob/main/adapters/repos/db/lsmkv/memtable.go)
- [adapters/repos/db/lsmkv/segment.go](https://github.com/weaviate/weaviate/blob/main/adapters/repos/db/lsmkv/segment.go)
- [adapters/repos/db/lsmkv/strategies.go](https://github.com/weaviate/weaviate/blob/main/adapters/repos/db/lsmkv/strategies.go)
</details>

# LSMKV存储引擎

## 概述

LSMKV（Log-Structured Key-Value）是Weaviate中核心的键值存储引擎，基于LSM（Log-Structured Merge）树数据结构实现。该引擎专为高性能写入和高效范围查询而设计，是Weaviate底层数据持久化的关键组件。LSMKV通过将随机写入转换为顺序写入，显著提升了写入吞吐量，同时通过多层级合并机制优化存储空间利用率。

在Weaviate架构中，LSMKV负责存储对象的属性数据、倒排索引以及向量索引的元数据。与传统B树索引相比，LSMKV在写入密集型工作负载中表现更为出色，这对于向量数据库中频繁的导入和更新操作至关重要。

## 架构设计

### 核心组件

```mermaid
graph TD
    A[Write Request] --> B[MemTable]
    B --> C[WAL - Write-Ahead Log]
    C --> D{Flush Condition}
    D -->|达到阈值| E[Segment文件]
    E --> F[Level 0]
    F --> G[Level 1-N]
    G --> H[Compaction合并]
    H --> F
    
    style B fill:#90EE90
    style E fill:#87CEEB
    style G fill:#DDA0DD
```

LSMKV存储引擎由以下几个核心组件构成：

| 组件 | 功能描述 | 文件位置 |
|------|----------|----------|
| **Store** | 顶层存储管理器，协调多个Bucket | `store.go` |
| **Bucket** | 独立的数据桶，支持不同数据结构 | `bucket.go` |
| **MemTable** | 内存中的写缓冲表，接收实时写入 | `memtable.go` |
| **Segment** | 磁盘上的只读数据段 | `segment.go` |
| **SegmentGroup** | 管理同一层级的多个Segment | `segment_group.go` |
| **Compactor** | 后台压缩任务执行器 | `compactor_replace.go`, `compactor_map.go` |

资料来源：[adapters/repos/db/lsmkv/store.go:1-50](https://github.com/weaviate/weaviate/blob/main/adapters/repos/db/lsmkv/store.go)

### Store层设计

Store是LSMKV的最顶层抽象，负责管理多个独立的Bucket。每个Bucket可以配置不同的数据结构和压缩策略：

```go
// Store管理结构示意
type Store struct {
    dir     string                    // 数据目录
    buckets map[string]*Bucket        // Bucket映射表
    config  Config                    // 存储配置
}
```

Store的主要职责包括：
- 初始化和加载已有的数据目录
- 创建和管理多个Bucket实例
- 协调后台压缩任务
- 处理崩溃恢复

资料来源：[adapters/repos/db/lsmkv/store.go:50-100](https://github.com/weaviate/weaviate/blob/main/adapters/repos/db/lsmkv/store.go)

## 数据结构与策略

### Bucket类型

LSMKV支持两种主要的Bucket策略，用于不同的数据访问模式：

| 策略类型 | 适用场景 | 特性 |
|----------|----------|------|
| **Replace** | 主键唯一的数据，如对象属性 | 同一Key的多次写入会覆盖 |
| **Map** | 支持多值的数据，如倒排索引 | 同一Key可关联多个Value |

#### Replace策略

Replace策略适用于具有唯一主键的数据结构。每次写入时，系统直接覆盖该Key对应的Value，不需要额外的合并逻辑：

```go
type CompactorReplace struct {
    // 用于合并两个Segment中的Replace类型数据
    // 较新Segment中的数据会覆盖较旧的数据
}
```

资料来源：[adapters/repos/db/lsmkv/compactor_replace.go:1-30](https://github.com/weaviate/weaviate/blob/main/adapters/repos/db/lsmkv/compactor_replace.go)

#### Map策略

Map策略支持一个Key关联多个Value的场景，常用于倒排索引和嵌套对象存储：

```go
type CompactorMap struct {
    // 合并时会将同一Key的所有Value聚合
    // 支持按Key进行批量查询
}
```

资料来源：[adapters/repos/db/lsmkv/compactor_map.go:1-30](https://github.com/weaviate/weaviate/blob/main/adapters/repos/db/lsmkv/compactor_map.go)

### 压缩策略

LSMKV使用分层压缩策略管理磁盘空间：

```mermaid
graph LR
    A[MemTable<br/>内存] -->|Flush| B[L0: Segment 1<br/>Segment 2]
    B -->|Compaction| C[L1: Segment A]
    C -->|Compaction| D[L2: Segment B]
    D -->|Compaction| E[LN: Segment Z]
    
    style A fill:#90EE90
    style B fill:#87CEEB
    style C fill:#DDA0DD
    style D fill:#FFD700
    style E fill:#FF6B6B
```

| 层级 | 说明 | 特性 |
|------|------|------|
| **MemTable** | 内存缓冲 | 随机写入，顺序flush到磁盘 |
| **Level 0** | 多个SSTable | 每文件独立键范围，可能重叠 |
| **Level 1-N** | 分层压缩 | 键范围不重叠，容量逐层倍增 |

资料来源：[adapters/repos/db/lsmkv/strategies.go:1-50](https://github.com/weaviate/weaviate/blob/main/adapters/repos/db/lsmkv/strategies.go)

## MemTable机制

MemTable是LSMKV写入路径的第一环，所有新数据首先写入MemTable：

### 写入流程

```mermaid
sequenceDiagram
    participant Client as 写入请求
    participant MemTable as MemTable
    participant WAL as WAL日志
    participant Segment as Segment文件
    
    Client->>MemTable: 写入Key/Value
    MemTable->>WAL: 追加预写日志
    MemTable->>MemTable: 更新内存结构
    Note over MemTable: MemTable满时触发
    MemTable->>Segment: Flush到磁盘
```

### 关键特性

- **Write-Ahead Log（WAL）**：每次写入都会先记录到WAL，确保崩溃恢复能力
- **内存索引**：使用跳表或红黑树维护键的有序性
- **阈值控制**：当MemTable大小达到配置阈值时触发flush操作

资料来源：[adapters/repos/db/lsmkv/memtable.go:1-60](https://github.com/weaviate/weaviate/blob/main/adapters/repos/db/lsmkv/memtable.go)

## Segment结构

Segment是LSMKV存储数据的基本单元，每个Segment是一个包含多个BTree的只读文件：

### Segment组成

| 部分 | 说明 |
|------|------|
| **Data Bloom Filter** | 快速判断Key是否可能存在 |
| **Index B-Tree** | 键到数据位置的映射 |
| **Primary Data** | 实际键值数据 |
| **Commit Log** | Segment元数据 |

```go
type Segment struct {
    Contents []byte        // 文件内容
    index    *btree.BTree   // 内存索引
    bloomFilter *BloomFilter
    dataStart  uint64       // 数据起始位置
    dataEnd    uint64       // 数据结束位置
}
```

资料来源：[adapters/repos/db/lsmkv/segment.go:1-80](https://github.com/weaviate/weaviate/blob/main/adapters/repos/db/lsmkv/segment.go)

## Compaction压缩机制

### 压缩触发条件

压缩任务会在以下情况触发：
1. Level 0 的Segment数量超过阈值
2. Level N 的总大小超过该层容量
3. 手动触发的后台压缩

### 压缩类型

#### Replace类型Compaction

Replace策略的Compaction相对简单，只需要保留每个Key的最新值：

```go
func (c *CompactorReplace) Do() error {
    // 1. 读取两个要合并的Segment
    // 2. 按Key排序遍历
    // 3. 保留每个Key的最新版本
    // 4. 写入新的Segment
}
```

资料来源：[adapters/repos/db/lsmkv/compactor_replace.go:30-100](https://github.com/weaviate/weaviate/blob/main/adapters/repos/db/lsmkv/compactor_replace.go)

#### Map类型Compaction

Map策略需要聚合同一Key的所有Value：

```go
func (c *CompactorMap) Do() error {
    // 1. 读取两个Segment中的Map数据
    // 2. 将相同Key的所有Value合并
    // 3. 写入新的Segment
}
```

资料来源：[adapters/repos/db/lsmkv/compactor_map.go:30-100](https://github.com/weaviate/weaviate/blob/main/adapters/repos/db/lsmkv/compactor_map.go)

### 近期修复记录

根据社区发布记录，LSMKV在以下版本中进行了稳定性修复：

| 版本 | 修复内容 | 相关Issue |
|------|----------|-----------|
| v1.37.1 | 修复可变键数量的二级索引大小累积问题 | [#11060](https://github.com/weaviate/weaviate/pull/11060) |
| v1.37.2 | TTL稳定性和向量缓存修复 | - |
| v1.36.12-v1.36.13 | 二级索引大小累积修复 | [#11060](https://github.com/weaviate/weaviate/pull/11060) |

这些修复确保了在高写入负载下存储空间的正确管理和对象的正确过期删除。

## Bucket API

### 核心操作

```go
// Bucket主要接口
type Bucket struct {
    // 写入操作
    Put(key []byte, value []byte) error
    PutList(key []byte, values [][]byte) error
    
    // 读取操作
    Get(key []byte) ([]byte, error)
    GetList(key []byte) ([][]byte, error)
    
    // 范围查询
    GetBySecondary(index, key []byte) ([]byte, error)
    
    // 删除操作
    Delete(key []byte) error
    DeleteGarbageCollection() (uint64, error)
}
```

资料来源：[adapters/repos/db/lsmkv/bucket.go:50-200](https://github.com/weaviate/weaviate/blob/main/adapters/repos/db/lsmkv/bucket.go)

### 使用示例

```go
// 创建或打开Bucket
bucket, err := store.CreateOrGetBucket("objects", "replace")
if err != nil {
    return err
}

// 写入数据
err = bucket.Put([]byte("key1"), []byte("value1"))

// 读取数据
val, err := bucket.Get([]byte("key1"))

// 范围查询
iter := bucket.Iter()
for iter.Next() {
    fmt.Printf("Key: %s, Value: %s\n", iter.Key(), iter.Value())
}
```

## 配置选项

LSMKV存储引擎支持多种配置参数：

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `MemTableSize` | int | 12MB | MemTable最大内存占用 |
| `SegmentMaxSize` | int | 512MB | 单个Segment文件最大大小 |
| `Level0Level1Cap` | int | 10 | L0层可容纳的Segment数 |
| `TombstoneDeletionInterval` | duration | 10min | 墓碑删除检查间隔 |
| `WalEnabled` | bool | true | 是否启用WAL日志 |

这些配置可以通过Weaviate的配置文件进行调整，以适应不同的工作负载需求。

## 性能优化建议

### 写入优化

1. **批量写入**：使用事务批量提交减少I/O次数
2. **合理设置MemTable大小**：更大的MemTable减少flush频率
3. **监控Compaction进度**：避免Compaction影响查询性能

### 读取优化

1. **配置Bloom Filter**：有效减少无效磁盘访问
2. **合理分层**：根据数据量调整各层容量
3. **定期维护**：运行DeleteGarbageCollection清理已删除数据

## 与Weaviate集成的关键场景

### TTL（Time-To-Live）支持

LSMKV支持对象级别的TTL功能，通过墓碑标记和后台垃圾回收实现：

- 过期对象写入墓碑标记
- Compactor会跳过墓碑记录
- DeleteGarbageCollection清理真正的物理删除

### 对象批量导入

在批量导入场景中，LSMKV的顺序写入特性提供了出色的吞吐量：

```go
// 批量导入优化路径
batch := bucket.NewBatch()
for _, obj := range objects {
    batch.Put(obj.ID, obj.Data)
}
batch.Flush()
```

### 二级索引

LSMKV的Map策略用于存储二级索引，支持高效的多条件过滤查询：

- 倒排索引存储在Map类型的Bucket中
- 支持按属性值快速定位对象
- 结合向量搜索实现混合查询

## 常见问题排查

| 问题 | 可能原因 | 解决方案 |
|------|----------|----------|
| 写入延迟高 | Compaction积压 | 调整压缩策略，增加资源 |
| 存储空间持续增长 | 墓碑未清理 | 检查GC配置和执行状态 |
| 查询超时 | Segment过多 | 执行手动Compaction合并 |

## 总结

LSMKV存储引擎是Weaviate高性能存储能力的基石，通过LSM树结构实现了写入与读取性能的平衡。其模块化设计支持Replace和Map两种数据结构，可灵活适配不同数据模型的存储需求。压缩机制确保了长期运行中的存储空间效率，而WAL和墓碑机制则保证了数据的持久性和一致性。随着Weaviate的持续迭代，LSMKV也在不断优化，最近的修复重点关注了可变键索引和TTL稳定性等关键场景。

---

<a id='page-vector-indexes'></a>

## 向量索引实现

### 相关页面

相关主题：[LSMKV存储引擎](#page-lsmkv-storage), [混合搜索实现](#page-hybrid-search)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [adapters/repos/db/vector/hnsw/index.go](https://github.com/weaviate/weaviate/blob/main/adapters/repos/db/vector/hnsw/index.go)
- [adapters/repos/db/vector/hnsw/insert.go](https://github.com/weaviate/weaviate/blob/main/adapters/repos/db/vector/hnsw/insert.go)
- [adapters/repos/db/vector/hnsw/search.go](https://github.com/weaviate/weaviate/blob/main/adapters/repos/db/vector/hnsw/search.go)
- [adapters/repos/db/vector/hfresh/hfresh.go](https://github.com/weaviate/weaviate/blob/main/adapters/repos/db/vector/hfresh/hfresh.go)
- [adapters/repos/db/vector/hfresh/search.go](https://github.com/weaviate/weaviate/blob/main/adapters/repos/db/vector/hfresh/search.go)
- [adapters/repos/db/vector/compressionhelpers/product_quantization.go](https://github.com/weaviate/weaviate/blob/main/adapters/repos/db/vector/compressionhelpers/product_quantization.go)
- [adapters/repos/db/vector/compressionhelpers/scalar_quantization.go](https://github.com/weaviate/weaviate/blob/main/adapters/repos/db/vector/compressionhelpers/scalar_quantization.go)
- [adapters/repos/db/vector/flat/index.go](https://github.com/weaviate/weaviate/blob/main/adapters/repos/db/vector/flat/index.go)
</details>

# 向量索引实现

## 概述

Weaviate 是一个开源的云原生向量数据库，其核心功能之一是高效的向量索引与相似度搜索。向量索引模块负责组织和管理高维向量数据，支持 ANN（近似最近邻）搜索，在保证搜索精度的同时实现毫秒级响应。

Weaviate 当前支持两种主要的向量索引实现：

| 索引类型 | 用途 | 特点 |
|---------|------|------|
| **HNSW** | 主要生产级索引 | 基于 Hierarchical Navigable Small World 算法，支持高质量 ANN 搜索 |
| **HFresh** | 文本检索专用索引 | 针对倒排索引优化的新鲜内容搜索，v1.37+ GA |
| **Flat** | 简单场景/基准测试 | 暴力穷举搜索，无索引优化 |

资料来源：[adapters/repos/db/vector/hnsw/index.go:1-50]()

## 索引架构设计

### 索引接口抽象

所有向量索引都实现了统一的 `VectorIndex` 接口，定义了插入、搜索、删除等核心操作。这种设计允许 Weaviate 在运行时切换不同的索引实现，同时也支持用户根据场景选择最合适的索引类型。

```mermaid
graph TB
    subgraph "向量索引接口层"
        VI[VectorIndex 接口]
    end
    
    subgraph "索引实现"
        HNSW[HNSW 索引]
        HFR[HFresh 索引]
        FLAT[Flat 索引]
    end
    
    subgraph "压缩层"
        PQ[Product Quantization]
        SQ[Scalar Quantization]
    end
    
    VI --> HNSW
    VI --> HFR
    VI --> FLAT
    HNSW --> PQ
    HNSW --> SQ
```

资料来源：[adapters/repos/db/vector/flat/index.go:1-30]()

## HNSW 索引实现

### 核心概念

HNSW（Hierarchical Navigable Small World）是一种基于图的高维向量索引算法。它通过构建多层图结构实现高效的近似最近邻搜索：

- **多层结构**：从底层到顶层，节点连接数逐渐减少
- **贪婪搜索**：从顶层开始，向下逐层搜索直到最底层
- **小世界特性**：确保搜索路径长度与维度呈对数关系

资料来源：[adapters/repos/db/vector/hnsw/index.go:50-150]()

### 插入流程

向量插入 HNSW 索引时经过以下步骤：

1. **选择插入层**：根据概率分布随机选择目标层
2. **构建邻居**：在新层中搜索最近邻，构建图连接
3. **更新指针**：在各层中维护双向链表指针

```mermaid
graph LR
    A[接收向量] --> B{选择插入层}
    B -->|高层| C[构建稀疏图]
    B -->|底层| D[构建稠密图]
    C --> E[搜索最近邻]
    D --> E
    E --> F[插入到各层图]
    F --> G[更新连接]
```

资料来源：[adapters/repos/db/vector/hnsw/insert.go:1-100]()

### 搜索流程

HNSW 的搜索过程采用自顶向下的贪婪策略：

```go
// 简化搜索逻辑
func (h *hnsw) Search(query vector, k int, filters filters) ([]uint64, error) {
    // 1. 从顶层开始搜索
    entryPoint := h.findEntryPoint()
    
    // 2. 自顶向下逐层搜索
    for level := h.maxLevel; level >= 0; level-- {
        entryPoint = h.searchLayer(entryPoint, query, level)
    }
    
    // 3. 收集候选集并返回最终结果
    return h.collectResults(entryPoint, query, k), nil
}
```

资料来源：[adapters/repos/db/vector/hnsw/search.go:1-80]()

### HNSW 配置参数

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `efConstruction` | int | 128 | 构建时候选集大小，影响索引质量与构建时间 |
| `ef` | int | 128 | 搜索时候选集大小，影响搜索精度与性能 |
| `maxObjects` | int | 10000000 | 索引支持的最大对象数 |
| `m` | int | 16 | 每层邻居数量 |

## HFresh 索引实现

HFresh 是 Weaviate v1.37+ GA 的新型向量索引，专门针对文本检索场景优化。它基于倒排索引和不对称距离计算，提供更优的新鲜内容搜索性能。

### HFresh 架构

HFresh 采用了不同于 HNSW 的索引结构，主要优化点包括：

- **非对称距离计算**：针对查询向量和文档向量的差异特性优化
- **增量索引更新**：支持更高效的新数据插入
- **内存优化**：减少内存占用和磁盘写入

```mermaid
graph TB
    Q[查询向量] --> AD[非对称距离]
    D1[文档向量1] --> AD
    D2[文档向量2] --> AD
    AD --> R[结果排序]
    R --> O[输出Top-K]
```

资料来源：[adapters/repos/db/vector/hfresh/hfresh.go:1-100]()

### HFresh 搜索

HFresh 的搜索实现针对高召回率场景进行了优化：

```go
func (h *HFresh) Search(query vector, k int, opts ...Option) ([]uint64, error) {
    // 非对称搜索实现
    candidates := h.searchCandidates(query)
    return h.rankByAsymmetricDistance(query, candidates, k)
}
```

资料来源：[adapters/repos/db/vector/hfresh/search.go:1-60]()

### 版本演进

根据社区发布记录，HFresh 在 v1.37 系列版本中经历了重要改进：

| 版本 | 改进内容 |
|------|---------|
| v1.37.0 | 预览版发布，包含大量性能优化 |
| v1.37.2 | 使用非对称距离计算 |

## 向量压缩

为了支持大规模向量数据，Weaviate 实现了两种向量压缩技术：

### Product Quantization（乘积量化）

PQ 将高维向量分割成多个子空间，对每个子空间分别进行聚类量化。这种方法可以显著减少存储空间，同时保持较高的搜索精度。

```mermaid
graph LR
    V[原始向量 128维] --> SPLIT[分割为8个子向量]
    SPLIT --> Q1[量化子向量1]
    SPLIT --> Q2[量化子向量2]
    SPLIT --> Qn[量化子向量8]
    Q1 --> C[码本存储]
    Qn --> C
    C --> ID[存储ID而非向量]
```

资料来源：[adapters/repos/db/vector/compressionhelpers/product_quantization.go:1-50]()

### Scalar Quantization（标量量化）

SQ 将浮点向量转换为低比特整数表示，例如将 float32 转换为 uint8。这是最简单的压缩方式，压缩率约为 4 倍。

| 压缩类型 | 压缩率 | 精度损失 | 适用场景 |
|---------|--------|---------|---------|
| PQ | 4-16x | 中等 | 大规模向量集 |
| SQ | 4x | 较低 | 内存敏感场景 |

资料来源：[adapters/repos/db/vector/compressionhelpers/scalar_quantization.go:1-50]()

## Flat 索引

Flat 索引是最简单的向量索引实现，执行暴力穷举搜索。它适用于以下场景：

- **小规模数据集**：向量数量较少（<10万）
- **基准测试**：作为性能对比基准
- **精确搜索**：需要 100% 精确结果时

```go
type Flat struct {
    vectors    [][]float32
    distances  []float32
    size       int
}
```

资料来源：[adapters/repos/db/vector/flat/index.go:1-40]()

## 社区相关问题

### 多向量索引需求

社区存在对任意数量向量索引的功能请求（Issue #2465）。当前 Weaviate 每个对象仅支持 0-1 个向量，用户期望能够为同一对象添加多个向量属性，例如：

```yaml
properties:
- name: title
  dataType: ["text"]
- name: title_vector
  dataType: ["vector"]
- name: description_vector
  dataType: ["vector"]
```

### 元数据过滤与混合搜索

社区反馈混合搜索中元数据过滤不工作的问题（Issue #11262）。这涉及到向量索引与过滤器的集成实现，需要在搜索过程中正确应用过滤条件。

### 相关发布版本

| 版本 | 向量索引相关改进 |
|------|-----------------|
| v1.35.17 | HNSW visited lists 改进 |
| v1.36.13 | HNSW 稳定性修复 |
| v1.37.0 | HFresh GA，Alter Schema Drop vector index |
| v1.38.0-rc.0 | Alter Schema Reindex property |

## 性能优化

### 缓存优化

Weaviate 在向量索引层面实现了多层缓存：

- **向量缓存**：预加载常用向量到内存
- **压缩向量缓存**：优化压缩后向量的访问
- **搜索结果缓存**：减少重复查询计算

### 并发控制

索引操作采用细粒度的锁机制：

- 读写分离锁
- 分片级锁
- 无锁读操作

## 总结

Weaviate 的向量索引实现提供了灵活且高性能的向量存储与搜索能力。HNSW 作为主要索引类型，提供可靠的 ANN 搜索性能；HFresh 作为新兴索引，针对特定场景进行了优化。用户可以根据数据规模、精度要求和性能需求选择合适的索引配置。

---

<a id='page-cluster-replication'></a>

## 集群与复制机制

### 相关页面

相关主题：[多租户支持](#page-multi-tenancy)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [cluster/raft.go](https://github.com/weaviate/weaviate/blob/main/cluster/raft.go)
- [cluster/store.go](https://github.com/weaviate/weaviate/blob/main/cluster/store.go)
- [cluster/schema/manager.go](https://github.com/weaviate/weaviate/blob/main/cluster/schema/manager.go)
- [cluster/replication/manager.go](https://github.com/weaviate/weaviate/blob/main/cluster/replication/manager.go)
- [cluster/replication/shard_replication_engine.go](https://github.com/weaviate/weaviate/blob/main/cluster/replication/shard_replication_engine.go)
- [adapters/repos/db/replication.go](https://github.com/weaviate/weaviate/blob/main/adapters/repos/db/replication.go)
- [adapters/repos/db/async_replication_scheduler.go](https://github.com/weaviate/weaviate/blob/main/adapters/repos/db/async_replication_scheduler.go)
- [usecases/replica/coordinator.go](https://github.com/weaviate/weaviate/blob/main/usecases/replica/coordinator.go)
- [cluster/proto/api/message.pb.go](https://github.com/weaviate/weaviate/blob/main/cluster/proto/api/message.pb.go)
</details>

# 集群与复制机制

## 概述

Weaviate 是一个云原生的向量数据库，其集群与复制机制是实现高可用性、水平扩展和数据持久性的核心基础设施。该机制基于 **RAFT 一致性算法** 构建分布式状态机，通过多副本复制确保数据在节点故障时的可用性和一致性。

Weaviate 集群架构支持：
- **水平扩展**：通过增加节点分摊负载
- **故障转移**：节点故障时自动切换到健康副本
- **数据一致性**：强一致性保证下的读写操作
- **分布式任务协调**：跨节点任务的统一调度

> 资料来源：[cluster/raft.go:1-50]()

## 核心组件

### 集群组件架构

```mermaid
graph TB
    subgraph "集群层"
        RAFT[RAFT 共识模块]
        SM[Schema 管理器]
        RM[复制管理器]
        CM[协调器]
    end
    
    subgraph "数据层"
        DB[(数据库节点)]
        Shard[分片]
        Index[向量索引]
    end
    
    subgraph "通信层"
        GRPC[gRPC 通信]
        Proto[Protocol Buffers]
    end
    
    RAFT --> SM
    RAFT --> RM
    RAFT --> CM
    RM --> Shard
    CM --> Shard
    Shard --> Index
    GRPC --> Proto
```

### 关键组件说明

| 组件 | 文件位置 | 职责 |
|------|---------|------|
| RAFT 共识模块 | `cluster/raft.go` | 维护集群一致性状态，处理日志复制和领导者选举 |
| Schema 管理器 | `cluster/schema/manager.go` | 管理集合定义、索引配置和分片策略 |
| 复制管理器 | `cluster/replication/manager.go` | 协调副本间数据同步和一致性 |
| 协调器 | `usecases/replica/coordinator.go` | 路由读写请求到合适的副本节点 |
| 分片复制引擎 | `cluster/replication/shard_replication_engine.go` | 执行单个分片的数据复制操作 |

> 资料来源：[cluster/raft.go:1-30](), [cluster/replication/manager.go:1-40]()

## RAFT 一致性算法

### 算法原理

Weaviate 采用 RAFT 算法实现分布式一致性，该算法将问题分解为三个子问题：

1. **领导者选举**：集群启动或领导者故障时选举新的领导者
2. **日志复制**：领导者接收客户端请求并复制到所有追随者节点
3. **安全性**：确保状态机的一致性复制

### 节点状态机

```mermaid
stateDiagram-v2
    [*] --> 追随者: 集群初始化
    
    追随者 --> 候选人: 选举超时
    候选人 --> 领导者: 获得多数选票
    候选人 --> 追随者: 发现当前领导者
    领导者 --> 追随者: 发现更高任期号
    追随者 --> [*]: 节点移除
    
    领导者 --> 候选人: 领导者故障
```

### 消息类型定义

根据 `cluster/proto/api/message.pb.go` 中的定义，集群消息类型包括：

| 消息类型 | 用途 | 相关常量 |
|---------|------|---------|
| `TYPE_ADD_REPLICA` | 添加新副本 | `0xc0` |
| `TYPE_UPDATE_REPLICA` | 更新副本状态 | `0xc1` |
| `TYPE_DELETE_REPLICA` | 删除副本 | `0xc2` |
| `TYPE_READ_REPLICA` | 读取副本数据 | `0xc3` |
| `TYPE_DISTRIBUTED_TASK_*` | 分布式任务消息 | 多个子类型 |
| `TYPE_GET_REPLICATION_DETAILS` | 获取复制详情 | `0xc8` |

> 资料来源：[cluster/proto/api/message.pb.go:100-150]()

## 复制策略

### 多副本复制架构

Weaviate 支持配置副本因子（`replicationFactor`），数据会在多个节点间同步复制：

```mermaid
graph LR
    subgraph "写入流程"
        Client[客户端] --> CM[协调器]
        CM --> Leader[领导者节点]
        Leader --> Follower1[副本节点1]
        Leader --> Follower2[副本节点2]
        Follower1 --> Ack1[确认]
        Follower2 --> Ack2[确认]
        Ack1 --> CM
        Ack2 --> CM
        CM --> Client[客户端]
    end
```

### 复制协调器

复制协调器（`usecases/replica/coordinator.go`）负责：

- 将写请求路由到领导者节点
- 等待达到 `WriteCoordinator` 配置的确认数
- 处理副本节点故障和恢复

> 资料来源：[usecases/replica/coordinator.go:1-50]()

### 异步复制调度

```mermaid
graph TD
    subgraph "异步复制调度器"
        Scheduler[async_replication_scheduler]
        Queue[任务队列]
        Worker[工作线程池]
    end
    
    subgraph "复制操作"
        Prepare[准备阶段]
        Execute[执行阶段]
        Finalize[完成阶段]
    end
    
    Scheduler --> Queue
    Queue --> Worker
    Worker --> Prepare
    Prepare --> Execute
    Execute --> Finalize
    Finalize --> Queue: 下一任务
```

异步复制调度器 (`adapters/repos/db/async_replication_scheduler.go`) 通过任务队列和工作线程池实现高效的批量复制操作。

> 资料来源：[adapters/repos/db/async_replication_scheduler.go:1-30]()

## 数据一致性保证

### 一致性级别

Weaviate 支持不同的一致性级别配置：

| 一致性级别 | 描述 | 适用场景 |
|-----------|------|---------|
| `QUORUM` | 等待多数节点确认 | 平衡性能与一致性 |
| `ALL` | 等待所有副本确认 | 强一致性要求 |
| `ONE` | 等待至少一个节点确认 | 高性能场景 |

### 副本状态追踪

复制状态通过以下字段追踪：

- `id`: 副本唯一标识
- `version`: 数据版本号
- `node_id`: 所属节点 ID
- `success`: 操作是否成功
- `acked_at_unix_millis`: 确认时间戳
- `error`: 错误信息（如有）

> 资料来源：[cluster/proto/api/message.pb.go:50-80]()

## 分布式任务机制

### 任务类型

Weaviate 使用分布式任务框架处理需要跨节点协调的操作：

```mermaid
graph TB
    subgraph "任务生命周期"
        Submit[提交任务]
        Prepare[准备阶段]
        Execute[执行阶段]
        Complete[完成阶段]
        Cleanup[清理阶段]
    end
    
    Submit --> Prepare
    Prepare --> Execute
    Execute --> Complete
    Complete --> Cleanup
```

### 任务消息类型

| 任务类型 | 功能描述 |
|---------|---------|
| `AddDistributedTaskRequest` | 添加分布式任务 |
| `PrepareDistributedTaskRequest` | 准备任务执行 |
| `MarkTaskFinalizedRequest` | 标记任务完成 |
| `CleanUpDistributedTaskRequest` | 清理任务资源 |

> 资料来源：[cluster/proto/api/message.pb.go:200-250]()

### 任务协调流程

```mermaid
sequenceDiagram
    participant C as 协调器
    participant L as 领导者
    participant F1 as 副本节点1
    participant F2 as 副本节点2
    
    C->>L: AddDistributedTaskRequest
    L->>F1: PrepareDistributedTaskRequest
    L->>F2: PrepareDistributedTaskRequest
    F1-->>L: Ack
    F2-->>L: Ack
    L->>F1: ExecuteTask
    L->>F2: ExecuteTask
    F1-->>L: 完成确认
    F2-->>L: 完成确认
    L->>C: MarkTaskFinalized
    C->>F1: CleanUpDistributedTask
    C->>F2: CleanUpDistributedTask
```

## Schema 复制

Schema 管理器负责在集群中传播集合定义和索引配置：

| 操作 | 描述 |
|------|------|
| 创建集合 | 在领导者节点创建，自动同步到所有节点 |
| 更新集合 | Schema 版本控制，确保一致性更新 |
| 删除集合 | 级联删除关联的索引和分片 |
| 分片策略 | 决定数据如何分布到不同节点 |

> 资料来源：[cluster/schema/manager.go:1-60]()

## 分片复制引擎

分片复制引擎 (`cluster/replication/shard_replication_engine.go`) 处理细粒度的数据复制：

- **向量索引复制**：HNSW 索引结构同步
- **对象数据复制**：原始数据记录复制
- **元数据复制**：属性值和索引信息复制

> 资料来源：[cluster/replication/shard_replication_engine.go:1-40]()

## 配置与调优

### 集群配置参数

| 参数 | 默认值 | 描述 |
|------|--------|------|
| `cluster.hostname` | - | 集群通信主机地址 |
| `cluster advertiseaddr` | - | 对外广播地址 |
| `replication.factor` | 1 | 默认副本因子 |
| `raft.join` | - | 初始节点列表 |

### 性能优化

社区反馈和版本更新中涉及的性能优化：

| 版本 | 优化内容 |
|------|---------|
| v1.36.13 | 修复 RAFT 稳定性问题 |
| v1.35.19 | 修复递归 RAFT 命令问题 |
| v1.37.0 | 改进集群内部通信 |

> 资料来源：v1.36.13 Release Notes, v1.35.19 Release Notes, v1.37.0 Release Notes

## 故障处理

### 节点故障检测

集群通过心跳机制检测节点故障：

1. 追随者定期向领导者发送心跳
2. 领导者追踪最后收到心跳的时间
3. 超时后标记节点为不可用
4. 触发副本重新分配

### 恢复流程

```mermaid
flowchart TD
    A[节点故障检测] --> B{剩余节点数足够?}
    B -->|是| C[自动重新分配副本]
    B -->|否| D[进入只读模式]
    C --> E[数据同步完成]
    E --> F[恢复正常]
    D --> G[等待节点恢复]
    G --> F
```

### TTL 与租户去激活

v1.36.13 版本修复了 TTL 上下文取消时的租户去激活问题，确保即使删除操作被中断也能正确完成状态转换。

> 资料来源：v1.36.13 Release Notes - TTL Stability Fix

## 最佳实践

### 副本数量选择

| 数据量级 | 推荐副本因子 | 原因 |
|---------|-------------|------|
| 小规模 (<100万对象) | 1-2 | 减少存储开销 |
| 中等规模 (100万-1亿) | 2-3 | 平衡可用性与开销 |
| 大规模 (>1亿) | 3 | 最大程度保证可用性 |

### 社区常见问题

根据社区反馈整理的常见问题：

| Issue | 问题描述 | 状态 |
|-------|---------|------|
| #11262 | 元数据过滤在混合搜索中不工作 | 开放 |
| 批量更新性能 | 40万条记录更新需要约20小时 | 长期需求 |

## 相关链接

- [官方文档 - 复制配置](https://docs.weaviate.io/weaviate/concepts/replication)
- [官方文档 - 集群架构](https://docs.weaviate.io/weaviate/concepts/cluster-architecture)
- [GitHub Issue #2124](https://github.com/weaviate/weaviate/issues/2124) - 批量更新性能优化需求
- [GitHub Issue #11262](https://github.com/weaviate/weaviate/issues/11262) - 元数据过滤问题

---

<a id='page-multi-tenancy'></a>

## 多租户支持

### 相关页面

相关主题：[集群与复制机制](#page-cluster-replication)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [usecases/schema/tenant.go](https://github.com/weaviate/weaviate/blob/main/usecases/schema/tenant.go)
- [usecases/multitenancy/extensions.go](https://github.com/weaviate/weaviate/blob/main/usecases/multitenancy/extensions.go)
- [adapters/repos/db/multitenancy/validator.go](https://github.com/weaviate/weaviate/blob/main/adapters/repos/db/multitenancy/validator.go)
- [usecases/namespace_cleanup/coordinator.go](https://github.com/weaviate/weaviate/blob/main/usecases/namespace_cleanup/coordinator.go)
- [adapters/repos/db/index_objects_ttl.go](https://github.com/weaviate/weaviate/blob/main/adapters/repos/db/index_objects_ttl.go)
- [usecases/object_ttl/object_ttl.go](https://github.com/weaviate/weaviate/blob/main/usecases/object_ttl/object_ttl.go)
</details>

# 多租户支持

## 概述

Weaviate 的多租户支持（Multi-Tenancy）允许在单一数据库集群中隔离多个租户的数据和操作。每个租户拥有独立的数据空间，实现资源的逻辑分离，同时共享底层基础设施以优化成本和资源利用率。

在 Weaviate 的架构中，多租户通过 **命名空间（Namespace）** 和 **租户（Tenant）** 两层机制实现。命名空间提供顶层的逻辑隔离，而租户则在集合（Collection）级别进一步细分数据存储空间。

## 核心概念

### 命名空间（Namespace）

命名空间是多租户架构的第一层隔离单元。每个命名空间维护独立的：

- 数据索引
- 向量存储
- 元数据索引

命名空间通过唯一标识符进行区分，系统支持在运行时动态创建、查询和管理命名空间。

**API 操作类型：**

| 操作类型 | 标识符 | 说明 |
|---------|--------|------|
| TYPE_GET_NAMESPACES | 63 | 获取所有命名空间 |
| TYPE_RESOLVE_ALIAS | 100 | 解析命名空间别名 |

```protobuf
// 资料来源：cluster/proto/api/message.pb.go
QueryRequest_Type_value = map[string]int32{
    "TYPE_GET_NAMESPACES": 63,
    "TYPE_RESOLVE_ALIAS": 100,
}
```

### 租户（Tenant）

租户是集合级别的隔离单元，允许在同一个 Collection 下创建多个独立的数据空间。租户机制特别适用于 SaaS 应用场景，其中多个客户共享相同的 Schema 结构，但需要完全隔离的数据存储。

**租户状态管理：**

租户具有以下生命周期状态：

1. **激活（ACTIVE）**：租户正在被使用，数据可读写
2. **未激活（INACTIVE）**：租户暂时未使用，数据保留但不可访问
3. **热删除（HOT_DELETE）**：租户正在被删除操作清理

## 租户管理架构

### 层级结构

```mermaid
graph TD
    A[Weaviate 集群] --> B[命名空间 Namespace]
    B --> C[集合 Collection]
    C --> D[租户 Tenant]
    D --> E[数据对象 Objects]
    D --> F[向量 Vector]
```

### 核心组件

| 组件 | 文件路径 | 职责 |
|------|----------|------|
| Schema Manager | `usecases/schema/tenant.go` | 租户的创建、更新、删除和状态管理 |
| Multi-Tenancy Extensions | `usecases/multitenancy/extensions.go` | 租户上下文扩展和隔离逻辑 |
| Validator | `adapters/repos/db/multitenancy/validator.go` | 租户数据验证和权限检查 |
| Namespace Cleanup | `usecases/namespace_cleanup/coordinator.go` | 未使用命名空间的自动清理协调 |
| Object TTL Manager | `usecases/object_ttl/object_ttl.go` | 租户对象生命周期管理 |

## 租户生命周期管理

### 租户激活与停用

租户的激活状态直接影响数据的可用性。当租户被激活时，其所有关联数据立即可读写；当租户被停用时，数据保持持久化但访问受限。

**TTL 稳定性修复（v1.36.13）：**

在之前的版本中，当 TTL 上下文在删除操作中途被取消时，可能导致租户无法正确重新停用。修复确保即使在删除流程中断的情况下，租户也能正确转换到非激活状态。

```go
// 资料来源：usecases/object_ttl/object_ttl.go
// 租户重新激活保证逻辑
func ensureTenantRedeactivation(ctx context.Context, tenant *Tenant) error {
    // 确保在 TTL 上下文取消时，租户能正确停用
}
```

### Collection Export 与租户管理

在 v1.37.2 版本中，Collection Export 功能增强了与租户去激活的并发处理能力。通过并发式租户停用机制，显著加快了快照创建速度。

```go
// 资料来源：adapters/repos/db/index_objects_ttl.go
// 并发处理租户去激活以加速导出
func (idx *Index) processTenantsConcurrently(tenants []string) {
    // 使用 worker pool 并行处理租户停用
}
```

## 租户数据验证

### 验证器职责

`adapters/repos/db/multitenancy/validator.go` 中的验证器确保：

1. 租户标识符格式正确
2. 租户属于指定的 Collection
3. 操作权限与租户状态匹配
4. 跨租户数据隔离不被破坏

```go
// 伪代码示例：租户验证逻辑
type TenantValidator struct {
    registry *租户注册表
}

func (v *TenantValidator) ValidateOperation(tenantID string, op Operation) error {
    if !v.registry.Exists(tenantID) {
        return ErrTenantNotFound
    }
    if !v.hasPermission(tenantID, op) {
        return ErrUnauthorized
    }
    return nil
}
```

## 命名空间清理机制

### 自动清理协调器

长时间未使用的命名空间会被自动清理协调器识别和处理。该机制定期检查命名空间的使用状态，释放不再需要的资源。

```go
// 资料来源：usecases/namespace_cleanup/coordinator.go
type CleanupCoordinator struct {
    interval    time.Duration
    threshold   time.Duration
    namespaces  map[string]*Namespace
}

func (c *CleanupCoordinator) Run(ctx context.Context) {
    ticker := time.NewTicker(c.interval)
    for {
        select {
        case <-ticker.C:
            c.evaluateInactiveNamespaces()
        case <-ctx.Done():
            return
        }
    }
}
```

### 清理策略

| 阶段 | 操作 | 说明 |
|------|------|------|
| 评估 | 检查命名空间最后访问时间 | 确定是否达到清理阈值 |
| 通知 | 向关联租户发送警告 | 给予恢复机会 |
| 执行 | 移除命名空间数据 | 释放存储资源 |

## API 使用示例

### 获取租户列表

```python
import weaviate

client = weaviate.Client("http://localhost:8080")

# 获取集合的所有租户
collection = client.collections.get("Article")
tenants = collection.tenants.get()

for tenant in tenants:
    print(f"租户: {tenant.name}, 状态: {tenant.activity_status}")
```

### 租户上下文操作

```go
// 资料来源：usecases/multitenancy/extensions.go
// 租户上下文扩展实现

type TenantContext struct {
    TenantID   string
    Collection string
    Options    TenantOptions
}

func WithTenant(ctx context.Context, tenantID string) context.Context {
    return context.WithValue(ctx, tenantKey, tenantID)
}

func GetTenant(ctx context.Context) (string, bool) {
    tenant, ok := ctx.Value(tenantKey).(string)
    return tenant, ok
}
```

## 已知问题与限制

### 社区报告的问题

| Issue | 问题描述 | 相关版本 |
|-------|----------|----------|
| #11262 | 在 n8n 集成中，混合搜索的元数据过滤器不工作 | 当前活跃 |

### 性能考虑

1. **批量操作**：大量租户的批量更新可能耗时较长，社区建议优化批量 patch 功能（Issue #2124）
2. **租户数量**：单 Collection 支持的租户数量受内存和存储限制
3. **索引开销**：每个租户维护独立的索引结构，过多租户可能影响查询性能

## 配置与管理

### Schema 定义中的租户配置

```json
{
  "class": "Article",
  "multiTenancyConfig": {
    "enabled": true
  },
  "properties": [
    {
      "name": "title",
      "dataType": ["text"]
    }
  ]
}
```

### 运行时配置

租户管理相关的运行时参数：

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `TENANT_STATUS_CHECK_INTERVAL` | 60s | 租户状态检查间隔 |
| `TTL_CLEANUP_INTERVAL` | 300s | TTL 清理任务间隔 |
| `NAMESPACE_INACTIVE_THRESHOLD` | 30d | 命名空间被视为不活跃的阈值 |

## 最佳实践

1. **合理规划租户粒度**：根据数据量和访问模式选择合适的隔离级别
2. **监控租户活跃度**：定期检查租户使用情况，及时停用不活跃租户以节省资源
3. **批量操作优化**：使用异步批量接口减少单次操作开销
4. **资源配额设置**：为关键租户设置资源使用上限，避免资源争用

## 相关文档

- [Schema 管理](https://docs.weaviate.io/weaviate/schema)
- [集合配置](https://docs.weaviate.io/weaviate/configuration/indexes)
- [数据导入](https://docs.weaviate.io/weaviate/import)
- [备份与恢复](https://docs.weaviate.io/weaviate/backup)

## 发布历史

| 版本 | 变更内容 |
|------|----------|
| v1.38.0 | Namespaces 功能正式发布 |
| v1.37.2 | Collection Export 与租户去激活并发优化 |
| v1.37.0 | Collection Export 快照功能引入 |
| v1.36.13 | TTL 租户重新激活保证修复 |

---

<a id='page-hybrid-search'></a>

## 混合搜索实现

### 相关页面

相关主题：[向量索引实现](#page-vector-indexes), [API层实现](#page-api-layer)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [adapters/repos/db/inverted/bm25_searcher.go](https://github.com/weaviate/weaviate/blob/main/adapters/repos/db/inverted/bm25_searcher.go)
- [adapters/repos/db/inverted/bm25_searcher_block.go](https://github.com/weaviate/weaviate/blob/main/adapters/repos/db/inverted/bm25_searcher_block.go)
- [adapters/repos/db/inverted/searcher.go](https://github.com/weaviate/weaviate/blob/main/adapters/repos/db/inverted/searcher.go)
- [adapters/handlers/graphql/local/common_filters/hybrid.go](https://github.com/weaviate/weaviate/blob/main/adapters/handlers/graphql/local/common_filters/hybrid.go)
- [adapters/handlers/graphql/local/common_filters/filters.go](https://github.com/weaviate/weaviate/blob/main/adapters/handlers/graphql/local/common_filters/filters.go)
- [adapters/handlers/graphql/local/common_filters/group_by.go](https://github.com/weaviate/weaviate/blob/main/adapters/handlers/graphql/local/common_filters/group_by.go)
- [adapters/handlers/graphql/local/get/class_builder.go](https://github.com/weaviate/weaviate/blob/main/adapters/handlers/graphql/local/get/class_builder.go)
</details>

# 混合搜索实现

## 概述

混合搜索（Hybrid Search）是 Weaviate 中一种将语义向量搜索与 BM25 关键词搜索相结合的高级检索方式。它通过融合两种搜索方法的结果，为用户提供更准确、更全面的搜索体验。

在 Weaviate 的架构中，混合搜索涉及多个核心组件的协作：

```mermaid
graph TD
    A[GraphQL 查询] --> B[hybrid.go 解析器]
    B --> C[向量搜索模块]
    B --> D[BM25 搜索模块]
    C --> E[结果融合层]
    D --> E
    E --> F[分组/过滤处理]
    F --> G[返回结果]
```

资料来源：[adapters/handlers/graphql/local/common_filters/hybrid.go:1-50]()

## 核心组件架构

### 1. BM25 关键词搜索器

BM25 搜索是混合搜索的关键词匹配组件，负责基于文本相似度的搜索功能。

#### 主搜索器实现

`bm25_searcher.go` 文件实现了核心的 BM25 搜索逻辑：

| 组件 | 文件路径 | 功能描述 |
|------|----------|----------|
| BM25Searcher | bm25_searcher.go | BM25 算法核心实现 |
| BM25SearcherBlock | bm25_searcher_block.go | 分块 BM25 搜索优化 |
| InvertedSearcher | searcher.go | 倒排索引搜索基础设施 |

资料来源：[adapters/repos/db/inverted/bm25_searcher.go:1-30]()

#### 分块搜索优化

对于大规模数据集，BM25 搜索采用分块处理策略以提高性能：

```mermaid
graph LR
    A[查询文本] --> B[分词处理]
    B --> C[倒排索引查询]
    C --> D[分块评分]
    D --> E[结果合并]
    E --> F[最终排序]
```

分块搜索器 (`bm25_searcher_block.go`) 允许将倒排索引数据分割成多个块并行处理，有效降低大数据集搜索的内存占用和响应时间。

资料来源：[adapters/repos/db/inverted/bm25_searcher_block.go:1-50]()

### 2. GraphQL 查询处理层

混合搜索的 GraphQL 接口由 `common_filters` 目录下的多个文件协作处理。

#### Hybrid 解析器

`hybrid.go` 是混合搜索的核心解析器，负责：
- 解析 hybrid 查询参数
- 配置向量搜索和 BM25 搜索的融合策略
- 处理搜索结果的去重和排序

```go
// 混合搜索参数结构（简化示意）
type HybridParams struct {
    Query      string      // 搜索查询文本
    Alpha      float64     // 向量/BM25 权重比例 (0-1)
    Vector     []float64   // 可选：提供自定义向量
    Properties []string    // 搜索属性列表
    Limit      int         // 返回结果数量限制
    Offset     int         // 分页偏移量
}
```

资料来源：[adapters/handlers/graphql/local/common_filters/hybrid.go:20-60]()

#### 过滤器集成

`filters.go` 提供与混合搜索配合使用的过滤功能：

- 支持 `Where` 过滤器
- 支持 `NearText` / `NearVector` / `NearObject` 等近邻过滤
- 支持 `ContainsAny` / `ContainsAll` 数组包含过滤

资料来源：[adapters/handlers/graphql/local/common_filters/filters.go:1-40]()

#### 分组处理

`group_by.go` 实现搜索结果的分组功能，允许用户对混合搜索结果按指定属性进行分组聚合：

```go
type GroupParams struct {
    Strategy  GroupStrategy  // 分组策略
    Properties []string      // 分组属性
    Force     float64       // 分组强制值
}
```

资料来源：[adapters/handlers/graphql/local/common_filters/group_by.go:1-30]()

### 3. 类构建器

`class_builder.go` 负责将混合搜索配置构建为底层的 GraphQL 字段解析器，建立从用户查询到具体搜索实现的映射关系。

资料来源：[adapters/handlers/graphql/local/get/class_builder.go:1-50]()

## 搜索流程详解

### 查询处理流程

```mermaid
sequenceDiagram
    participant Client as 客户端
    participant GQL as GraphQL 层
    participant Hybrid as Hybrid 解析器
    participant BM25 as BM25 搜索器
    participant Vector as 向量搜索器
    participant Fusion as 融合层

    Client->>GQL: Get { Articles (hybrid: { query: "关键词" }) }
    GQL->>Hybrid: 解析 hybrid 参数
    Hybrid->>BM25: 执行 BM25 搜索
    Hybrid->>Vector: 执行向量搜索
    BM25-->>Fusion: 返回 BM25 结果及评分
    Vector-->>Fusion: 返回向量相似度结果
    Fusion->>Fusion: 分数归一化与融合
    Fusion-->>Client: 返回融合排序结果
```

### BM25 评分机制

BM25（Best Matching 25）是经典的信息检索算法，其核心公式考虑：

1. **词频（TF）**：搜索词在文档中出现的频率
2. **逆文档频率（IDF）**：词在所有文档中的稀有程度
3. **文档长度归一化**：对不同长度文档的标准化处理

公式核心概念：
```
score = IDF × (TF × (k1 + 1)) / (TF + k1 × (1 - b + b × dl/avgdl))
```

其中：
- `k1`：词频饱和参数（通常 1.2-2.0）
- `b`：文档长度归一化参数（通常 0.75）
- `dl`：文档长度
- `avgdl`：平均文档长度

资料来源：[adapters/repos/db/inverted/bm25_searcher.go:50-100]()

### 结果融合策略

混合搜索的核心在于将 BM25 和向量搜索的结果进行有效融合。典型的融合策略包括：

| 策略名称 | 描述 | 适用场景 |
|----------|------|----------|
| Relative Score Fusion | 基于相对分数的融合 | 平衡两种搜索结果 |
| Reciprocal Rank Fusion | 基于排名倒数融合 | 重视排名顺序 |
| 动态权重融合 | 根据 Alpha 参数调整 | 用户可控制的融合方式 |

`Alpha` 参数控制融合权重：
- `alpha = 0`：仅使用 BM25
- `alpha = 1`：仅使用向量搜索
- `0 < alpha < 1`：混合模式，值越大向量搜索权重越高

资料来源：[adapters/handlers/graphql/local/common_filters/hybrid.go:80-120]()

## API 使用示例

### GraphQL 查询

```graphql
{
  Get {
    Articles (
      hybrid: {
        query: "机器学习入门"
        alpha: 0.75
        vector: [0.1, 0.2, 0.3, ...]
      }
      where: {
        path: ["category"]
        operator: Equal
        valueText: "技术"
      }
      limit: 10
    ) {
      title
      content
      _score
      _hybridScore
    }
  }
}
```

### Python 客户端

```python
import weaviate

client = weaviate.Client("http://localhost:8080")

result = client.query.get(
    "Article",
    ["title", "content"]
).with_hybrid(
    query="机器学习入门",
    alpha=0.75,
    properties=["title", "content"]
).with_where({
    "path": ["category"],
    "operator": "Equal",
    "valueText": "技术"
}).with_limit(10).do()

print(result)
```

### Go 客户端

```go
result, err := client.GraphQL().Get().
    WithClassName("Article").
    WithFields(weaviate.SelectProperties{...}).
    WithHybrid(weaviate.HybridQuery{
        Query:  "机器学习入门",
        Alpha:  0.75,
    }).
    WithWhere(filter).
    WithLimit(10).
    Do(ctx)
```

## 配置参数

### 混合搜索参数表

| 参数 | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `query` | string | 必填 | 搜索查询文本 |
| `alpha` | float | 0.5 | 向量搜索权重 (0-1) |
| `vector` | []float | nil | 可选：自定义向量 |
| `properties` | []string | nil | 搜索属性列表 |
| `limit` | int | 10 | 返回结果数量 |
| `offset` | int | 0 | 分页偏移量 |
| `scoreModifiers` | object | nil | 分数修饰器配置 |

### 过滤参数表

| 参数 | 类型 | 描述 |
|------|------|------|
| `where` | object | 结构化过滤条件 |
| `nearText` | object | 文本近邻搜索 |
| `nearVector` | object | 向量近邻搜索 |
| `nearObject` | object | 对象近邻搜索 |
| `group` | object | 结果分组配置 |

资料来源：[adapters/handlers/graphql/local/common_filters/filters.go:40-80]()

## 已知限制与社区问题

### 元数据过滤在混合搜索中的限制

根据社区反馈（Issue #11262），**在 n8n 集成中使用混合搜索时，元数据过滤器可能无法正常工作**。

**问题描述：**
- 创建包含文本类型元数据字段的向量存储
- 添加至少两条具有不同元数据值的条目
- 在 n8n 中使用 Weaviate Vector Store 节点版本 1.3
- 选择 "Hybrid: Query Text" 选项进行混合搜索

相关链接：[GitHub Issue #11262](https://github.com/weaviate/weaviate/issues/11262)

### 其他相关社区问题

| Issue | 描述 | 优先级 |
|-------|------|--------|
| #2124 | 批量更新性能问题（部分用户期望混合搜索能加速批量更新） | 中 |
| #3683 | 缺少 "Not" 操作符支持，无法排除特定匹配条件 | 中 |

## 性能优化建议

### 1. 合理设置 Alpha 值

根据搜索场景选择合适的 alpha 值：
- **精确关键词匹配为主**：设置 `alpha = 0.2~0.4`
- **语义相似度为主**：设置 `alpha = 0.7~0.9`
- **平衡模式**：`alpha = 0.5`

### 2. 限制搜索属性

通过 `properties` 参数限制搜索范围，减少不必要的计算：

```python
.with_hybrid(
    query="关键词",
    properties=["title", "summary"]  # 仅搜索标题和摘要
)
```

### 3. 利用分组减少结果量

对大量结果使用分组功能，减少传输数据量：

```python
.with_group_by(["category"])
```

### 4. 分块 BM25 搜索

对于大规模数据集，系统会自动使用分块搜索优化内存使用，无需手动配置。

## 相关源码文件索引

| 功能模块 | 文件路径 |
|----------|----------|
| BM25 核心实现 | adapters/repos/db/inverted/bm25_searcher.go |
| BM25 分块搜索 | adapters/repos/db/inverted/bm25_searcher_block.go |
| 倒排索引搜索器 | adapters/repos/db/inverted/searcher.go |
| Hybrid GraphQL 解析 | adapters/handlers/graphql/local/common_filters/hybrid.go |
| 过滤器处理 | adapters/handlers/graphql/local/common_filters/filters.go |
| 分组处理 | adapters/handlers/graphql/local/common_filters/group_by.go |
| 类构建器 | adapters/handlers/graphql/local/get/class_builder.go |

## 总结

Weaviate 的混合搜索实现通过整合 BM25 关键词搜索和向量语义搜索，为用户提供了强大的混合检索能力。其架构设计遵循模块化原则，核心组件包括 BM25 搜索器、向量搜索器和结果融合层。开发者可通过调整 `alpha` 参数灵活控制搜索行为，结合过滤和分组功能满足复杂业务场景需求。

值得注意的是，当前版本中混合搜索与某些第三方工具（如 n8n）的元数据过滤集成存在已知问题，社区正在积极修复中。

---

<a id='page-modules'></a>

## 模块系统

### 相关页面

相关主题：[系统架构](#page-architecture)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [modules/text2vec-contextionary/module.go](https://github.com/weaviate/weaviate/blob/main/modules/text2vec-contextionary/module.go)
- [modules/text2vec-contextionary/client/contextionary.go](https://github.com/weaviate/weaviate/blob/main/modules/text2vec-contextionary/client/contextionary.go)
- [modules/text2vec-contextionary/client/meta_provider.go](https://github.com/weaviate/weaviate/blob/main/modules/text2vec-contextionary/client/meta_provider.go)
- [modules/generative-openai/module.go](https://github.com/weaviate/weaviate/blob/main/modules/generative-openai/module.go)
- [modules/reranker-cohere/module.go](https://github.com/weaviate/weaviate/blob/main/modules/reranker-cohere/module.go)
- [modules/sum-transformers/client/client.go](https://github.com/weaviate/weaviate/blob/main/modules/sum-transformers/client/client.go)
- [cluster/proto/api/message.pb.go](https://github.com/weaviate/weaviate/blob/main/cluster/proto/api/message.pb.go)
- [tools/telemetry-dashboard/README.md](https://github.com/weaviate/weaviate/blob/main/tools/telemetry-dashboard/README.md)
</details>

# 模块系统

## 概述

Weaviate 的模块系统是一个可扩展的插件架构，允许用户通过模块来扩展数据库的核心功能。该系统支持多种类型的模块，包括向量化模块（Vectorizers）、生成式模块（Generative）、重排序模块（Rerankers）、其他模块（Misc）以及数据提取模块（Data extractors）。

模块系统在 Weaviate 中的定位是通过标准化的接口定义实现功能的解耦与扩展。开发者可以实现自定义模块来满足特定的业务需求，例如使用特定的嵌入模型、调用不同的 LLM 提供商，或实现自定义的数据处理逻辑。

## 模块类型

Weaviate 支持以下核心模块类型：

| 模块类型 | 功能描述 | 示例 |
|---------|---------|------|
| **Vectorizer** | 在数据导入时自动将文本等数据转换为向量嵌入 | text2vec-contextionary, text2vec-openai, text2vec-cohere |
| **Generative** | 支持生成式搜索（RAG），结合向量检索与 LLM 生成 | generative-openai, generative-anthropic |
| **Reranker** | 对搜索结果进行重排序以提高相关性 | reranker-cohere, reranker-transformers |
| **Misc** | 提供额外的辅助功能 | backup-s3, backup-gcs |
| **Data Extractor** | 从非结构化数据中提取结构化信息 | pdf-parser, img2vec-neural |

## 模块架构

### 模块注册机制

Weaviate 的模块系统采用注册表模式进行管理。每个模块在初始化时向中心注册表注册其名称、类型以及提供的功能。

```mermaid
graph TD
    A[Weaviate 启动] --> B[加载模块注册表]
    B --> C[遍历可用模块]
    C --> D{模块是否启用?|
    D -->|是| E[初始化模块]
    D -->|否| F[跳过模块]
    E --> G[注册到中心管理器]
    F --> H[下一个模块]
    G --> H
    H --> C
    C --> I[模块加载完成]
```

### 模块能力接口

每个模块必须实现相应的能力接口。以向量化模块为例，需要提供以下核心功能：

1. **向量生成**：将输入文本转换为向量表示
2. **词频统计**：返回模型训练时的词汇量信息
3. **版本信息**：提供模块版本用于兼容性检查
4. **元数据提供**：返回模块运行状态和配置信息

资料来源：[modules/text2vec-contextionary/client/meta_provider.go:10-22]()

### 客户端通信架构

模块通常采用 gRPC 协议与外部服务进行通信。客户端负责处理连接管理、请求序列化和错误处理。

```mermaid
graph LR
    A[Weaviate Core] -->|gRPC| B[Module gRPC Client]
    B --> C[外部服务]
    C -->|响应| B
    B -->|反序列化| D[结果处理]
    D --> A
```

资料来源：[modules/text2vec-contextionary/client/contextionary.go:1-30]()

## 向量化模块

### 功能职责

向量化模块的核心职责是在数据导入阶段将非结构化文本转换为高维向量嵌入。这一过程对于实现语义搜索至关重要。

### text2vec-contextionary 模块

text2vec-contextionary 是 Weaviate 内置的默认向量化模块，它基于词共现统计构建概念向量空间。

**核心功能**：

| 功能 | 方法 | 说明 |
|------|------|------|
| 版本检查 | `version()` | 获取 Contextionary 版本 |
| 词汇统计 | `wordCount()` | 返回训练词汇量 |
| 模式搜索 | `SchemaSearch()` | 支持概念级别的模式搜索 |
| 向量验证 | 内部处理 | 确保向量维度一致性 |

资料来源：[modules/text2vec-contextionary/client/contextionary.go:8-18]()

### 模块元数据

每个向量化模块都需要提供元数据接口，用于系统诊断和监控：

```go
meta := map[string]interface{}{
    "version":   c11yVersion,
    "wordCount": c11yWordCount,
}
```

元数据包含版本信息和运行状态，可供运维人员监控系统健康状况。

资料来源：[modules/text2vec-contextionary/client/meta_provider.go:14-19]()

## 生成式模块

### 功能职责

生成式模块使 Weaviate 能够执行检索增强生成（RAG）操作。在完成向量检索后，模块将检索结果发送给 LLM 生成回答。

### generative-openai 模块

generative-openai 是调用 OpenAI GPT 模型进行生成式搜索的模块。它接收检索到的对象列表，并生成针对用户问题的定制化回答。

**工作流程**：

```mermaid
sequenceDiagram
    用户->>Weaviate: 发起生成式查询
    Weaviate->>向量检索: 执行相似度搜索
    向量检索-->>Weaviate: 返回相关对象
    Weaviate->>生成式模块: 发送检索结果
    生成式模块->>OpenAI API: 调用 LLM
    OpenAI API-->>生成式模块: 生成回答
    生成式模块-->>Weaviate: 返回结果
    Weaviate-->>用户: 最终响应
```

### 模块配置

生成式模块支持自定义参数传递，包括模型选择、温度设置等配置选项。

## 重排序模块

### 功能职责

重排序模块对初步搜索结果进行二次排序，以提高结果的相关性评分准确性。常见应用场景包括整合多种信号（向量相似度、关键词匹配、语义相关性）进行综合排序。

### reranker-cohere 模块

reranker-cohere 调用 Cohere 的重排序 API，对初始搜索结果进行重新评分排序。

## 数据提取模块

### 功能职责

数据提取模块从非结构化数据（如 PDF、图像）中提取结构化信息，为后续的向量化和存储做准备。

### sum-transformers 模块

sum-transformers 模块提供文档摘要功能，可用于生成长文档的简短摘要：

```go
out := make([]ent.SummaryResult, len(resBody.Summary))
for i, elem := range resBody.Summary {
    out[i].Result = elem.Result
    out[i].Property = property
}
```

资料来源：[modules/sum-transformers/client/client.go:1-50]()

## 模块与集群通信

### gRPC 接口定义

模块系统通过 Protocol Buffers 定义的消息类型进行通信。系统支持多种查询类型，包括权限检查、角色管理和数据复制相关操作。

| 查询类型 | 功能 | 编号 |
|---------|------|------|
| TYPE_UNSPECIFIED | 未指定 | 0 |
| TYPE_GET_CLASSES | 获取类信息 | 1 |
| TYPE_GET_SCHEMA | 获取完整模式 | 2 |
| TYPE_GET_TENANTS | 获取租户信息 | 3 |
| TYPE_HAS_PERMISSION | 权限验证 | 30 |
| TYPE_GET_ROLES | 获取角色列表 | 31 |
| TYPE_GET_REPLICATION_DETAILS | 复制详情 | 200 |

资料来源：[cluster/proto/api/message.pb.go:1-100]()

### 分布式任务处理

模块系统支持分布式任务调度，通过以下消息类型协调：

- `AddDistributedTaskRequest`：添加分布式任务
- `RecordDistributedTaskPreparationCompleteAckRequest`：任务准备完成确认
- `CleanUpDistributedTaskRequest`：清理分布式任务

每个任务包含命名空间、ID、负载、提交时间戳等信息。

## 模块配置管理

### 配置热更新

Weaviate 支持模块配置的热更新功能，无需重启服务即可应用配置变更：

```mermaid
graph TD
    A[配置文件变更] --> B[检测文件修改]
    B --> C[重新加载配置]
    C --> D[验证配置有效性]
    D -->|有效| E[应用新配置]
    D -->|无效| F[保持旧配置]
    E --> G[通知相关模块]
    F --> H[记录错误日志]
```

配置管理器使用 100ms 的轮询间隔检测配置文件变更，并发场景下通过通道机制确保配置读取的线程安全。

资料来源：[usecases/config/runtime/manager_test.go:1-80]()

### 配置项

模块支持的主要配置项包括：

| 配置项 | 类型 | 说明 |
|--------|------|------|
| 备份间隔 | duration | 定期备份触发间隔 |
| 向量缓存大小 | integer | 缓存的向量数量上限 |
| 压缩元数据 | boolean | 是否持久化压缩信息 |

## 遥测系统

### 功能概述

Weaviate 包含遥测数据收集功能，用于收集匿名的使用统计信息。遥测仪表板可本地运行以可视化这些数据。

**遥测数据包含**：

- 客户端使用统计（Python, Java, TypeScript, Go, C#）
- 模块使用信息
- 对象和集合数量
- 机器运行状态

资料来源：[tools/telemetry-dashboard/README.md:1-40]()

### 仪表板功能

| 功能 | 说明 |
|------|------|
| 实时接收 | 接收 Weaviate 实例的遥测 POST 请求 |
| 实时仪表板 | Web 界面展示近期遥测数据 |
| 机器统计 | 按机器 ID 聚合统计信息 |
| 客户端追踪 | 跟踪各语言客户端使用情况 |
| 自动刷新 | 每 2 秒自动更新显示 |

## 社区相关问题

### 功能请求

社区用户提出了多项与模块系统相关的功能请求：

1. **多向量属性支持**（Issue #2465）：用户希望单个对象支持多个向量属性，便于针对不同用途使用不同的嵌入模型

2. **嵌套对象过滤与向量化**（Issue #3694）：扩展向量化能力以支持嵌套对象的处理和过滤

3. **批量更新优化**（Issue #2124）：虽然不直接涉及模块，但用户反馈批量更新 40 万条记录的耗时问题，部分场景下可考虑使用流式处理优化

### 已知问题

- **n8n 集成中的元数据过滤**：Issue #11262 报告了在 n8n 工作流中使用混合搜索时元数据过滤不生效的问题
- **版本兼容性**：模块需注意版本匹配，不同版本间的模块可能存在 API 不兼容

## 最佳实践

### 模块选择

| 场景 | 推荐模块 |
|------|---------|
| 快速原型开发 | text2vec-contextionary |
| 高精度语义搜索 | text2vec-openai, text2vec-cohere |
| 隐私敏感数据 | 自托管向量化服务 |
| RAG 场景 | generative-openai, generative-anthropic |
| 大规模重排序 | reranker-cohere |

### 性能优化

1. **向量缓存**：合理配置向量缓存大小以平衡内存使用和查询性能
2. **批量导入**：使用批量导入接口减少网络开销
3. **异步处理**：利用异步 API 提升吞吐量
4. **压缩优化**：启用向量压缩以降低存储成本

### 安全考虑

1. API 密钥应通过环境变量或安全配置管理，避免硬编码
2. 外部模块服务应启用 TLS 加密通信
3. 定期更新模块版本以获取安全修复

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：weaviate/weaviate

摘要：发现 26 个潜在踩坑项，其中 3 个为 high/blocking；最高优先级：安装坑 - 来源证据：Your project scores highest on Maintenance (19.9/20) in an independent trust analysis。

## 1. 安装坑 · 来源证据：Your project scores highest on Maintenance (19.9/20) in an independent trust analysis

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Your project scores highest on Maintenance (19.9/20) in an independent trust analysis
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_123630d837d14b1c83a54d58a53135f4 | https://github.com/weaviate/weaviate/issues/11534 | 来源类型 github_issue 暴露的待验证使用条件。

## 2. 安全/权限坑 · 来源证据：bq.rescoreLimit=-1 accepted and silently discarded (no validation)

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：bq.rescoreLimit=-1 accepted and silently discarded (no validation)
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_4ee4e459abca4d2d85de3fa2a5930252 | https://github.com/weaviate/weaviate/issues/11402 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 3. 安全/权限坑 · 来源证据：replicationFactor=-1 accepted and silently normalized to 1 (no validation)

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：replicationFactor=-1 accepted and silently normalized to 1 (no validation)
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_897580adbd7d461abe5642c6dac0c4c9 | https://github.com/weaviate/weaviate/issues/11401 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 4. 配置坑 · 失败模式：configuration: bq.rescoreLimit=-1 accepted and silently discarded (no validation)

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: bq.rescoreLimit=-1 accepted and silently discarded (no validation)
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: bq.rescoreLimit=-1 accepted and silently discarded (no validation)
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: bq.rescoreLimit=-1 accepted and silently discarded (no validation). Context: Observed when using node, python, docker
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_66059c07dc1bf7e9ba3ae29643f74f6d | https://github.com/weaviate/weaviate/issues/11402 | bq.rescoreLimit=-1 accepted and silently discarded (no validation)

## 5. 配置坑 · 失败模式：configuration: replicationFactor=-1 accepted and silently normalized to 1 (no validation)

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: replicationFactor=-1 accepted and silently normalized to 1 (no validation)
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: replicationFactor=-1 accepted and silently normalized to 1 (no validation)
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: replicationFactor=-1 accepted and silently normalized to 1 (no validation). Context: Observed when using node, python, docker
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_923df3fcace46105c3011afcdccf8664 | https://github.com/weaviate/weaviate/issues/11401 | replicationFactor=-1 accepted and silently normalized to 1 (no validation)

## 6. 配置坑 · 失败模式：configuration: v1.35.20 - Adjust text2vec-google batch limits + qa scripts

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: v1.35.20 - Adjust text2vec-google batch limits + qa scripts
- 对用户的影响：Upgrade or migration may change expected behavior: v1.35.20 - Adjust text2vec-google batch limits + qa scripts
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.35.20 - Adjust text2vec-google batch limits + qa scripts. Context: Observed when using docker, linux
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_release | fmev_2b31f056d2e0d7add2fd46a24be9c52d | https://github.com/weaviate/weaviate/releases/tag/v1.35.20 | v1.35.20 - Adjust text2vec-google batch limits + qa scripts

## 7. 配置坑 · 失败模式：configuration: v1.36.14 - Backup GCS module avoid full object scan during listing Fix

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: v1.36.14 - Backup GCS module avoid full object scan during listing Fix
- 对用户的影响：Upgrade or migration may change expected behavior: v1.36.14 - Backup GCS module avoid full object scan during listing Fix
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.36.14 - Backup GCS module avoid full object scan during listing Fix. Context: Observed when using docker, linux
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_release | fmev_595f992aafdc3ac5ef016c95e400760a | https://github.com/weaviate/weaviate/releases/tag/v1.36.14 | v1.36.14 - Backup GCS module avoid full object scan during listing Fix

## 8. 配置坑 · 失败模式：configuration: v1.37.3 - Cluster steadiness & async replication Fixes

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: v1.37.3 - Cluster steadiness & async replication Fixes
- 对用户的影响：Upgrade or migration may change expected behavior: v1.37.3 - Cluster steadiness & async replication Fixes
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.37.3 - Cluster steadiness & async replication Fixes. Context: Observed when using node
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_release | fmev_1aa71228476d3cb06842102005b0b1ad | https://github.com/weaviate/weaviate/releases/tag/v1.37.3 | v1.37.3 - Cluster steadiness & async replication Fixes

## 9. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | github_repo:55072677 | https://github.com/weaviate/weaviate | README/documentation is current enough for a first validation pass.

## 10. 运行坑 · 运行可能依赖外部服务

- 严重度：medium
- 证据强度：source_linked
- 发现：项目说明出现 external service/cloud/webhook/database 等运行依赖关键词。
- 对用户的影响：本地安装成功不等于能力可用，外部服务不可用会阻断体验。
- 建议检查：确认是否有离线 demo、mock 数据或可替代服务。
- 防护动作：外部服务依赖未明确时，不把本地安装成功等同于能力可用。
- 证据：packet_text.keyword_scan | github_repo:55072677 | https://github.com/weaviate/weaviate | matched external service / cloud / webhook / database keyword

## 11. 维护坑 · 失败模式：migration: v1.35.21 - New text2vec-digitalocean module

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this migration risk before relying on the project: v1.35.21 - New text2vec-digitalocean module
- 对用户的影响：Upgrade or migration may change expected behavior: v1.35.21 - New text2vec-digitalocean module
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.35.21 - New text2vec-digitalocean module. Context: Observed during version upgrade or migration.
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_release | fmev_8e7fecd34326feab3c938f272056b706 | https://github.com/weaviate/weaviate/releases/tag/v1.35.21 | v1.35.21 - New text2vec-digitalocean module

## 12. 维护坑 · 失败模式：migration: v1.36.15 - new text2vec-digitalocean module, fixed text2vec-google batch logic

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this migration risk before relying on the project: v1.36.15 - new text2vec-digitalocean module, fixed text2vec-google batch logic
- 对用户的影响：Upgrade or migration may change expected behavior: v1.36.15 - new text2vec-digitalocean module, fixed text2vec-google batch logic
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.36.15 - new text2vec-digitalocean module, fixed text2vec-google batch logic. Context: Observed during version upgrade or migration.
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_release | fmev_c5fbc8f87fe8aa9724f70b1833fd9e6b | https://github.com/weaviate/weaviate/releases/tag/v1.36.15 | v1.36.15 - new text2vec-digitalocean module, fixed text2vec-google batch logic

## 13. 维护坑 · 失败模式：migration: v1.36.16 - Increase SSB memlimit threshold, fix hnsw findnewentrypoint panic

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this migration risk before relying on the project: v1.36.16 - Increase SSB memlimit threshold, fix hnsw findnewentrypoint panic
- 对用户的影响：Upgrade or migration may change expected behavior: v1.36.16 - Increase SSB memlimit threshold, fix hnsw findnewentrypoint panic
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.36.16 - Increase SSB memlimit threshold, fix hnsw findnewentrypoint panic. Context: Observed during version upgrade or migration.
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_release | fmev_3096a0188737b4a1abba29156b0a0407 | https://github.com/weaviate/weaviate/releases/tag/v1.36.16 | v1.36.16 - Increase SSB memlimit threshold, fix hnsw findnewentrypoint panic

## 14. 维护坑 · 失败模式：migration: v1.37.4 - Async replication Fixes

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this migration risk before relying on the project: v1.37.4 - Async replication Fixes
- 对用户的影响：Upgrade or migration may change expected behavior: v1.37.4 - Async replication Fixes
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.37.4 - Async replication Fixes. Context: Observed when using docker, linux
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_release | fmev_97965b2c5cda9d0120fe1f7de913cadb | https://github.com/weaviate/weaviate/releases/tag/v1.37.4 | v1.37.4 - Async replication Fixes

## 15. 维护坑 · 失败模式：migration: v1.37.5 - HFresh task priorities, reduced shard locking

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this migration risk before relying on the project: v1.37.5 - HFresh task priorities, reduced shard locking
- 对用户的影响：Upgrade or migration may change expected behavior: v1.37.5 - HFresh task priorities, reduced shard locking
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.37.5 - HFresh task priorities, reduced shard locking. Context: Observed during version upgrade or migration.
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_release | fmev_0fd13abdad20281622d09c418fe9f191 | https://github.com/weaviate/weaviate/releases/tag/v1.37.5 | v1.37.5 - HFresh task priorities, reduced shard locking

## 16. 维护坑 · 失败模式：migration: v1.37.6 - Core Stability, Backup, and Compression Fixes

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this migration risk before relying on the project: v1.37.6 - Core Stability, Backup, and Compression Fixes
- 对用户的影响：Upgrade or migration may change expected behavior: v1.37.6 - Core Stability, Backup, and Compression Fixes
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.37.6 - Core Stability, Backup, and Compression Fixes. Context: Observed during version upgrade or migration.
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_release | fmev_78ba483c9393a42694b81ffef8595594 | https://github.com/weaviate/weaviate/releases/tag/v1.37.6 | v1.37.6 - Core Stability, Backup, and Compression Fixes

## 17. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:55072677 | https://github.com/weaviate/weaviate | last_activity_observed missing

## 18. 安全/权限坑 · 下游验证发现风险项

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:55072677 | https://github.com/weaviate/weaviate | no_demo; severity=medium

## 19. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:55072677 | https://github.com/weaviate/weaviate | no_demo; severity=medium

## 20. 安全/权限坑 · 来源证据：Security finding — possible pull_request_target pattern (details on request)

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Security finding — possible pull_request_target pattern (details on request)
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_95061db46ee74e2b9541997cfb0e5558 | https://github.com/weaviate/weaviate/issues/11431 | 来源类型 github_issue 暴露的待验证使用条件。

## 21. 能力坑 · 失败模式：capability: Add HVTracker badge to README?

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this capability risk before relying on the project: Add HVTracker badge to README?
- 对用户的影响：Developers may hit a documented source-backed failure mode: Add HVTracker badge to README?
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Add HVTracker badge to README?. Context: Source discussion did not expose a precise runtime context.
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_3ab61b3c6b1f6701d3249ed9ba324c7f | https://github.com/weaviate/weaviate/issues/11546 | Add HVTracker badge to README?

## 22. 能力坑 · 失败模式：capability: Security finding — possible pull_request_target pattern (details on request)

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this capability risk before relying on the project: Security finding — possible pull_request_target pattern (details on request)
- 对用户的影响：Developers may hit a documented source-backed failure mode: Security finding — possible pull_request_target pattern (details on request)
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Security finding — possible pull_request_target pattern (details on request). Context: Source discussion did not expose a precise runtime context.
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_16cc41210ee10ae4d615b5998ad74317 | https://github.com/weaviate/weaviate/issues/11431 | Security finding — possible pull_request_target pattern (details on request)

## 23. 能力坑 · 失败模式：capability: Your project scores highest on Maintenance (19.9/20) in an independent trust analysis

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this capability risk before relying on the project: Your project scores highest on Maintenance (19.9/20) in an independent trust analysis
- 对用户的影响：Developers may hit a documented source-backed failure mode: Your project scores highest on Maintenance (19.9/20) in an independent trust analysis
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Your project scores highest on Maintenance (19.9/20) in an independent trust analysis. Context: Source discussion did not expose a precise runtime context.
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_28765145208f1363f15fbc0a817e6665 | https://github.com/weaviate/weaviate/issues/11534 | Your project scores highest on Maintenance (19.9/20) in an independent trust analysis

## 24. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:55072677 | https://github.com/weaviate/weaviate | issue_or_pr_quality=unknown

## 25. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:55072677 | https://github.com/weaviate/weaviate | release_recency=unknown

## 26. 维护坑 · 失败模式：maintenance: v1.38.0-rc.0 - HFresh, Namespaces, Nested Object Filtering, Alter Schema Reindex property

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: v1.38.0-rc.0 - HFresh, Namespaces, Nested Object Filtering, Alter Schema Reindex property
- 对用户的影响：Upgrade or migration may change expected behavior: v1.38.0-rc.0 - HFresh, Namespaces, Nested Object Filtering, Alter Schema Reindex property
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.38.0-rc.0 - HFresh, Namespaces, Nested Object Filtering, Alter Schema Reindex property. Context: Source discussion did not expose a precise runtime context.
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_release | fmev_d9a10dd9096b3e323069aa6e50877a83 | https://github.com/weaviate/weaviate/releases/tag/v1.38.0-rc.0 | v1.38.0-rc.0 - HFresh, Namespaces, Nested Object Filtering, Alter Schema Reindex property

<!-- canonical_name: weaviate/weaviate; human_manual_source: deepwiki_human_wiki -->