Weaviate 是一个云原生的开源向量数据库，主体由 Go 编写而成，其运行时既支持单实例部署，也支持多节点集群部署。仓库根目录下的 README.md 描述项目目标为「将对象与向量同时存储，使语义搜索可在规模化场景下工作」，并强调与 OpenAI、Cohere、HuggingFace 等模型提供方的可插拔集成，以及在单一查询接口内融合向量相似度、BM25 关键字过滤、RAG 与重排序。

整体分层

仓库目录按 adapters/、usecases/、cluster/、modules/、cmd/ 划分职责，呈现典型的 clean-architecture 分层：

• cmd/weaviate-server 提供进程入口与命令行参数装配。
• adapters/ 负责与外部系统对接（HTTP/gRPC 接入、数据库驱动、对象存储等）。
• usecases/ 包含业务编排与运行时配置等用例层逻辑，例如 usecases/config/runtime/manager.go 通过泛型 ConfigManager[T any] 在固定 interval 周期内重新加载配置文件，并在加载失败时保留上一次的 currentConfig。
• cluster/ 处理多节点间的 Raft/共识与状态查询协议。
• modules/ 提供向量生成、摘要、重排序等可选能力。

flowchart TB
    Client["客户端 (REST / gRPC / GraphQL)"] --> Adapter["adapters 层<br/>协议接入与序列化"]
    Adapter --> Usecase["usecases 层<br/>业务编排与运行时配置"]
    Usecase --> Cluster["cluster 层<br/>Raft 状态与复制"]
    Usecase --> Module["modules 层<br/>向量化与生成"]
    Cluster --> Storage["存储后端<br/>LSM / 向量索引"]
    Module --> External["外部模型服务<br/>OpenAI / Cohere / HF ..."]

集群通信与状态查询

cluster/proto/api/message.pb.go 生成的协议缓冲区枚举了大量集群内部消息类型，可作为运行时拓扑的「线索」。其中既包含基础分片状态请求（TYPE_GET_SHARDING_STATE），也涵盖租户操作（TYPE_ADD_TENANT / TYPE_UPDATE_TENANT）、权限查询（TYPE_GET_ROLES / TYPE_HAS_PERMISSION）、命名空间（TYPE_GET_NAMESPACES）、别名解析（TYPE_RESOLVE_ALIAS / TYPE_GET_ALIASES）以及大量与复制相关的细粒度请求（TYPE_GET_REPLICATION_DETAILS_BY_COLLECTION_AND_SHARD、TYPE_GET_REPLICATION_OPERATION_STATE、TYPE_GET_REPLICATION_SCALE_PLAN 等）。

这一枚举表明 Weaviate 的复制控制面是「按集合/分片/目标节点」多层下钻的，社区曾在 issue #2985 中讨论过节点在复制通信中错误地通告 Docker 私有 IP 导致跨节点连接失败的情形。

运行时配置管理

运行时配置（runtime config）由 usecases/config/runtime/manager.go 中的 ConfigManager 统一承载。其设计要点可从源码直接读出：

• 泛型结构体 ConfigManager[T any] 通过 Parser[T] 与 Updater[T] 函数注入解析与差异应用逻辑，便于不同配置域复用。
• 构造时校验 filepath 非空，并以 interval 作为轮询周期。
• 记录 currentConfig 与 currentHash，保证新配置解析失败时仍可使用上一次成功结果。
• 内置 hooks map[string]func() error 钩子，用于在配置更新后触发实验性特性等副作用。
• 通过 Prometheus 指标（lastLoadSuccess / configHash）暴露加载健康度。

usecases/config/runtime/manager_test.go 中对并发读场景做了 100 个 goroutine 的并发校验，确认多消费者能一致看到最新配置。

模块化与外部依赖

模块客户端在仓库中以独立子包形式存在，遵循「通过 HTTP/gRPC 调用远端服务」的模式。modules/sum-transformers/client/client.go 通过 c.origin + path 拼接 URL，并在返回码 ≥ 400 时以 errors.Errorf 抛出错误；modules/text2vec-contextionary/client/contextionary.go 走 gRPC 通道，并在 SchemaSearch 接口中将内部枚举 traverser.SearchType 与 protobuf 枚举互转。Meta() 实现位于 modules/text2vec-contextionary/client/meta_provider.go，负责暴露远端服务的版本与词表规模。

仓库还提供了 tools/telemetry-dashboard 用来本地观察遥测数据，以及 tools/dev/generate_release_notes 通过 GitHub API 在相邻版本 tag 之间自动汇总发布说明。

已知边界与社区关注点

• 在 1.36.16 / 1.37.6 等多个版本中，开发团队对 HNSW 的 findnewentrypoint 路径做了 panic 修复，并提升了 SSB 内存阈值，社区对此类核心稳定性修复反馈较为集中。
• LSM 存储层在 1.35.22/1.36.17/1.37.7 等版本中反复引入了「compaction 在取消时立即中止」的行为变更 (lsmkv 相关 PR #11461)，是删除集合/分片链路稳定性的关键。
• 1.38.0-rc 中引入的 HFresh 索引、命名空间、嵌套对象过滤与 reindex 属性等都属于存储与索引层面的演进，需要结合具体版本日志评估对现有部署的影响。
• 等距结果的非确定性排序 (issue #11609) 反映出在 ANN 搜索与 BM25/HNSW 混合路径中，「距离相同时的稳定顺序」仍是工程上的开放问题。

参见

• 客户端与协议：REST、gRPC、GraphQL 三套对外接口（详见 README.md）。
• 集群复制与分片：cluster/proto/api/message.pb.go 中枚举的复制细节消息类型。
• 运行时配置：usecases/config/runtime/manager.go。
• 遥测与发布工程：tools/telemetry-dashboard/README.md、tools/dev/generate_release_notes/README.md。

概述

Weaviate 的搜索与查询子系统负责解析来自客户端的查询请求，并在存储的对象与向量之上执行语义搜索、关键字搜索、混合搜索以及过滤组合。该子系统跨越多个层次：客户端 API（REST、gRPC、GraphQL）、适配层、模块化的向量化和转换模块，以及底层的 LSM 存储与 HNSW/Flat 向量索引。

Weaviate 强调"对象与向量同库存储"的设计，使单一查询接口即可同时获得相似度匹配、关键字过滤（BM25）和重排序（Reranking）能力。资料来源：README.md:21-23。

子系统支持两种向量来源：导入时由集成模型（如 OpenAI、Cohere、HuggingFace、Google 等）自动向量化，或由用户直接导入预计算的向量。资料来源：README.md:25-28。

子系统组成

客户端 API 入口

Weaviate 通过多种协议对外暴露查询能力：

• REST API：基于 HTTP 的资源风格接口
• gRPC API：面向高性能客户端
• GraphQL API：灵活的查询语言，原生支持过滤与多字段投影

资料来源：README.md:74-76。多协议并存使得不同语言的客户端库（Python、JavaScript/TypeScript、Java、Go、C#/.NET）可以按需选择。资料来源：README.md:64-72。

向量化与转换模块

向量化模块（如 text2vec-contextionary、sum-transformers 等）以 gRPC 或 HTTP 客户端形式与主进程通信，承担 schema 搜索、摘要生成等职责。contextionary.go 中的 SchemaSearch 方法演示了模块如何接收遍历层传入的 traverser.SearchParams，将搜索类型映射到 protobuf 枚举（SearchType_CLASS / SearchType_PROPERTY），然后将结果反序列化为 traverser.SearchResults。资料来源：modules/text2vec-contextionary/client/contextionary.go:6-23。

模块的元信息（如版本、词表大小）由 meta_provider.go 中的 Meta 方法提供，供系统级信息查询使用。资料来源：modules/text2vec-contextionary/client/meta_provider.go。

集群协调与消息协议

在分布式部署中，查询协调依赖集群消息总线。cluster/proto/api/message.pb.go 定义了大量与状态分发、复制详情、分片状态、租户、命名空间、分布式任务等相关的查询/应用消息类型（如 TYPE_GET_SHARDING_STATE、TYPE_GET_REPLICATION_DETAILS_BY_COLLECTION），并提供 QueryRequest/QueryResponse、ApplyRequest/ApplyResponse 两类核心 RPC 容器。资料来源：cluster/proto/api/message.pb.go。

主要查询类型

flowchart LR
  Client[客户端 SDK] --> REST[REST API]
  Client --> gRPC[gRPC API]
  Client --> GQL[GraphQL API]
  REST --> Coord[查询协调器]
  gRPC --> Coord
  GQL --> Coord
  Coord --> VDB[向量索引 HNSW/Flat]
  Coord --> KV[LSM 存储]
  Coord --> Mod[向量化/转换模块]
  VDB --> Result[排序与合并]
  KV --> Result
  Mod --> Result
  Result --> Client

社区关注点与已知限制

社区反馈与 GitHub Issue 揭示了若干与查询子系统密切相关的痛点：

• 跨距离结果的非确定性排序：当多个结果距离完全相等时，仅按距离排序会产生非确定性顺序。参见 Issue #11609。
• 过滤能力缺位：用户长期呼吁恢复 Not 操作符以支持 Not Like 等排除性过滤。参见 Issue #3683。
• 多向量索引：目前一个对象仅关联 0..1 个向量，社区希望支持任意数量的向量索引。参见 Issue #2465。
• 嵌套对象过滤与向量化：嵌套对象存储已在 #2424 引入，但过滤与向量化能力仍未跟上。参见 Issue #3694。
• 复制节点私网 IP 通告：在多机部署时，副本节点可能向远端通告 Docker 私有 IP，导致连接失败。参见 Issue #2985。

运行时配置

查询子系统的行为受运行时配置影响。usecases/config/runtime/manager_test.go 演示了 ConfigManager 周期性加载 YAML 配置（如 backup_interval）并通知已注册消费者的机制——同一机制也支撑了查询相关的可调参数（如过滤器、向量索引、并发限制等）热更新。资料来源：usecases/config/runtime/manager_test.go:80-100。

See Also

• README.md — 项目总览
• modules/text2vec-contextionary/client/contextionary.go — 模块化搜索客户端参考实现
• cluster/proto/api/message.pb.go — 集群查询/应用消息协议

概述

Weaviate 是一个云原生的开源向量数据库，支持多节点集群部署。集群模式允许在多台机器（通常作为 Docker 容器或 Kubernetes Pod）之间分布数据分片（shards），并通过内置的复制机制提供高可用性与读取扩展能力。根据 README.md 的描述，Weaviate 在生产部署中具备"内置多租户、复制、RBAC 授权"等能力。

集群内的节点通过 Raft 一致性协议进行协调，所有 schema 变更、租户变更以及分片复制相关的元数据操作都通过集群协议进行传递与共识。读取和写入操作则被路由到正确的分片副本上执行。

集群协议消息类型

Weaviate 的集群内部通信通过 Protocol Buffers 定义的消息完成。从 cluster/proto/api/message.pb.go 可以看到，集群消息枚举（QueryType）中包含多种与分布式协调相关的请求类型，例如：

资料来源：cluster/proto/api/message.pb.go:1-15

AddTenantsRequest 与 UpdateTenantsRequest 等结构体则承载了多租户（multi-tenancy）场景下分片管理的具体载荷（包含 cluster_nodes 与 tenants 字段），用于在集群中新增或更新租户分片。资料来源：cluster/proto/api/message.pb.go:18-25

运行时配置管理

集群节点支持在不重启进程的情况下热加载运行时配置。该能力由 usecases/config/runtime/manager.go 中的 ConfigManager 实现，其核心职责为：

type ConfigManager[T any] struct {
    path          string
    interval      time.Duration
    parse         Parser[T]
    update        Updater[T]
    currentConfig *T
    currentHash   string
    log           logrus.FieldLogger
    lastLoadSuccess prometheus.Gauge
    configHash      *prometheus.GaugeVec
    hooks         map[string]func() error
}

ConfigManager 周期性（interval）从指定文件路径加载并解析配置，若新配置加载成功则调用 Updater 将其应用到已注册的运行时对象上。currentHash 字段用于避免重复应用相同配置，加载失败时则继续保留 currentConfig 不变。资料来源：usecases/config/runtime/manager.go:18-50

flowchart LR
    A[配置文件] -->|定时读取| B(ConfigManager)
    B -->|解析| C{Parser}
    C -->|成功| D[更新 currentConfig]
    C -->|失败| E[保留旧配置]
    D --> F[应用至运行时对象]
    D --> G[触发 hooks]

并发安全性由 usecases/config/runtime/manager_test.go 中的测试覆盖：测试启动 100 个 goroutine 同时读取配置值，验证在配置变更期间所有读取者最终都能观察到一致的最新值。资料来源：usecases/config/runtime/manager_test.go:75-105

已知问题与运维注意事项

社区中有不少围绕集群与复制部署的讨论。比较典型的如 Issue #2985 报告的"复制节点向远端节点通告私有 IP 地址"问题：当 Weaviate 节点运行在不同宿主机的 Docker 容器中时，节点会向其它节点通告 Docker 内部网络的私有 IP，从而导致远端节点无法建立连接。运维者在多机部署时需显式配置 CLUSTER_ADVERTISE_ADDR 等环境变量来通告可达地址。

此外，遥测通道（telemetry）是集群健康与使用情况可视化的重要组件。开发模式下可使用 tools/telemetry-dashboard/README.md 中描述的本地遥测面板接收 Weaviate 节点上报的数据，并在 UI 中查看机器状态、客户端使用情况、模块使用情况以及对象与集合计数。资料来源：tools/telemetry-dashboard/README.md:1-30

发行与变更追踪

集群行为在每次发行中都会进行稳定性改进，例如 v1.37.7 与 v1.36.17 中均包含对 LSM 压缩、集合与分片删除路径的修复；v1.35.23 引入了 batch simple 路径的速率限制器；v1.38.0-rc.1 引入了 HFresh、命名空间、嵌套对象过滤以及 Alter Schema 重新索引等与集群操作紧密相关的能力。发行说明的生成由 tools/dev/generate_release_notes/README.md 中的工具自动完成。资料来源：tools/dev/generate_release_notes/README.md:1-10

参见

• Weaviate 官方文档 - 部署
• Weaviate 复制指南
• Raft 共识协议

整体分层架构

graph TB
    Client[客户端 SDK] -->|REST/GraphQL| REST[REST 与 GraphQL 接口]
    Client -->|gRPC| gRPC[gRPC 接口]
    REST --> Core[Weaviate 核心引擎]
    gRPC --> Core
    Core --> Cfg[ConfigManager<br/>YAML 热加载]
    Core --> Cluster[集群内部消息协议]
    Cfg --> Mod[模块: text2vec-contextionary, sum-transformers, ...]
    Mod --> Ext[外部模型 / 推理服务]
    Cluster --> Nodes[其他 Weaviate 节点]
    Cluster --> DT[分布式任务<br/>HFresh / Namespaces]

如上图所示，外部请求先进入 API 接入层，再被核心引擎派发到模块或集群消息层；运行时配置则在引擎启动和运行期间持续生效。

外部 API 协议

Weaviate 通过三套协议为客户端提供访问入口：REST、gRPC 与 GraphQL。官方同时为 Python、JavaScript/TypeScript、Java、Go、C#/.NET 等语言维护了客户端库，并保留社区维护的其他绑定空间。资料来源：README.md:90-96

REST 与 GraphQL 面向人机可读的查询与模式管理场景；gRPC 由于二进制高效，被官方推荐用于批量写入与高吞吐检索请求。三套协议共同覆盖对象 CRUD、批量导入、混合搜索、过滤、重排序与生成式检索等操作。

模块系统与客户端契约

Weaviate 的功能扩展围绕模块化设计展开。每个模块（如 text2vec-contextionary、sum-transformers）都遵循"客户端 + 元数据提供者"的可发现契约。

以 text2vec-contextionary 为例，其客户端既提供 gRPC 调用，又暴露元数据接口。SchemaSearch 方法将入参封装为 pb.SchemaSearchParams，其中包含 Certainty、Name 与 SearchType 字段，并通过 searchTypeToProto 在 SearchTypeClass 与 SearchTypeProperty 枚举之间转换，最后由 schemaSearchResultsFromProto 解析响应。资料来源：modules/text2vec-contextionary/client/contextionary.go:1-58

元数据端点 MetaInfo 通过独立的 HTTP/gRPC 请求获取 version 与 wordCount 信息，便于 Weaviate 主进程在启动时探查模块能力并写入 schema 元信息。资料来源：modules/text2vec-contextionary/client/meta_provider.go:1-15

sum-transformers 模块展示了另一种客户端形态：纯 HTTP 调用。其 client 结构体通过 url(path string) 拼接 origin 与 path，发送请求后解析 SummaryResult 列表，每个结果包含 Result 文本与对应的 Property 字段名。资料来源：modules/sum-transformers/client/client.go:1-25

运行时配置管理

为了支持不停机调整参数，Weaviate 提供了基于 YAML 的运行时配置管理器。ConfigManager 通过 NewConfigManager 构造，接收文件路径、解析器、更新回调以及已注册的配置结构。测试代码展示了修改 backup_interval 从 10s 改为 20s 后，loadConfig 重新加载并通过更新回调将最新值投递到注册结构上的完整路径。资料来源：usecases/config/runtime/manager_test.go:1-80

这种"文件 + 解析器 + 注册结构 + 回调"模式使得任何模块在引入新的可调参数时，只需要注册到该管理器即可被自动加载并广播到对应的运行期消费者，避免硬编码或重启。

集群内部通信与扩展点

在集群模式下，节点之间通过 protobuf 消息进行通信。cluster/proto/api/message.pb.go 中定义了丰富的消息类型，例如 TYPE_GET_SHARDING_STATE、TYPE_GET_CLASS_VERSIONS、TYPE_GET_NAMESPACES、TYPE_RESOLVE_ALIAS、TYPE_GET_ALIASES 等用于模式与副本状态协商。资料来源：cluster/proto/api/message.pb.go:1-15

针对 v1.38 引入的 HFresh 与 Namespaces 特性，消息层新增了分布式任务相关结构：RecordDistributedTaskNodeCompletionRequest 包含 namespace、id、version、node_id、error 与 finished_at_unix_millis 字段，而 CancelDistributedTaskRequest 携带 cancelled_at_unix_millis。UnitSpec 上的 needs_preparation_barrier 字段表示该任务单元是否需要在所有节点准备就绪后再统一执行。资料来源：cluster/proto/api/message.pb.go:17-30

这套消息协议为新功能接入提供了清晰的扩展点——只要定义新的 TYPE_* 枚举与对应的 *Request/*Reply 结构，就可以在不破坏向后兼容的前提下让各节点协同执行新的分布式任务。

工具与开发者支持

仓库同时提供多个面向模块作者与运维的开发工具。tools/telemetry-dashboard 是本地仪表盘，启动后监听 8080 端口，可视化各 Weaviate 实例上报的遥测数据，包括机器 ID 聚合、客户端使用情况、模块使用情况以及对象 / 集合计数，仪表盘默认每 2 秒刷新一次。资料来源：tools/telemetry-dashboard/README.md:1-30

tools/dev/generate_release_notes 工具通过环境变量 GITHUB_TOKEN、CURRENT_VERSION、PREVIOUS_VERSION 拉取对应区间的合并记录并生成 GitHub Release 草稿，使模块作者在提交跨多个组件的 PR 后能快速整理变更说明。资料来源：tools/dev/generate_release_notes/README.md:1-10

See Also

• README.md — 项目总览、API 列表与客户端库
• modules/text2vec-contextionary/client/contextionary.go — 模块 gRPC 客户端契约
• cluster/proto/api/message.pb.go — 集群内部消息定义
• usecases/config/runtime/manager_test.go — 运行时配置管理示例

Pitfall Log / 踩坑日志

项目：weaviate/weaviate

摘要：发现 21 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：Replication node advertises a private IP address to a remote node。

1. 安装坑 · 来源证据：Replication node advertises a private IP address to a remote node

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Replication node advertises a private IP address to a remote node
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/weaviate/weaviate/issues/2985 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

2. 配置坑 · 失败模式：configuration: Replication node advertises a private IP address to a remote node

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: Replication node advertises a private IP address to a remote node
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Replication node advertises a private IP address to a remote node
• 证据：failure_mode_cluster:github_issue | https://github.com/weaviate/weaviate/issues/2985 | Replication node advertises a private IP address to a remote node

3. 能力坑 · 能力判断依赖假设

• 严重度：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.

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

• 严重度：medium
• 证据强度：source_linked
• 发现：项目说明出现 external service/cloud/webhook/database 等运行依赖关键词。
• 对用户的影响：本地安装成功不等于能力可用，外部服务不可用会阻断体验。
• 证据：packet_text.keyword_scan | github_repo:55072677 | https://github.com/weaviate/weaviate | matched external service / cloud / webhook / database keyword

5. 维护坑 · 失败模式：migration: Deterministic Ordering for Equal-Distance Search Results

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this migration risk before relying on the project: Deterministic Ordering for Equal-Distance Search Results
• 对用户的影响：Developers may hit a documented source-backed failure mode: Deterministic Ordering for Equal-Distance Search Results
• 证据：failure_mode_cluster:github_issue | https://github.com/weaviate/weaviate/issues/11609 | Deterministic Ordering for Equal-Distance Search Results

6. 维护坑 · 失败模式：migration: v1.35.22 - Make Compaction Abort Immediately on Cancel

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this migration risk before relying on the project: v1.35.22 - Make Compaction Abort Immediately on Cancel
• 对用户的影响：Upgrade or migration may change expected behavior: v1.35.22 - Make Compaction Abort Immediately on Cancel
• 证据：failure_mode_cluster:github_release | https://github.com/weaviate/weaviate/releases/tag/v1.35.22 | v1.35.22 - Make Compaction Abort Immediately on Cancel

7. 维护坑 · 失败模式：migration: v1.35.23 - Introduce rate limiter in batch simple logic

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this migration risk before relying on the project: v1.35.23 - Introduce rate limiter in batch simple logic
• 对用户的影响：Upgrade or migration may change expected behavior: v1.35.23 - Introduce rate limiter in batch simple logic
• 证据：failure_mode_cluster:github_release | https://github.com/weaviate/weaviate/releases/tag/v1.35.23 | v1.35.23 - Introduce rate limiter in batch simple logic

8. 维护坑 · 失败模式：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
• 证据：failure_mode_cluster:github_release | https://github.com/weaviate/weaviate/releases/tag/v1.36.15 | v1.36.15 - new text2vec-digitalocean module, fixed text2vec-google batch logic

9. 维护坑 · 失败模式：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
• 证据：failure_mode_cluster:github_release | https://github.com/weaviate/weaviate/releases/tag/v1.36.16 | v1.36.16 - Increase SSB memlimit threshold, fix hnsw findnewentrypoint panic

10. 维护坑 · 失败模式：migration: v1.36.17 - Make compaction abort immediately on cancel

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this migration risk before relying on the project: v1.36.17 - Make compaction abort immediately on cancel
• 对用户的影响：Upgrade or migration may change expected behavior: v1.36.17 - Make compaction abort immediately on cancel
• 证据：failure_mode_cluster:github_release | https://github.com/weaviate/weaviate/releases/tag/v1.36.17 | v1.36.17 - Make compaction abort immediately on cancel

11. 维护坑 · 失败模式：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
• 证据：failure_mode_cluster:github_release | https://github.com/weaviate/weaviate/releases/tag/v1.37.5 | v1.37.5 - HFresh task priorities, reduced shard locking

12. 维护坑 · 失败模式：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
• 证据：failure_mode_cluster:github_release | https://github.com/weaviate/weaviate/releases/tag/v1.37.6 | v1.37.6 - Core Stability, Backup, and Compression Fixes

13. 维护坑 · 失败模式：migration: v1.37.7 - Speed up collection and shard delete

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this migration risk before relying on the project: v1.37.7 - Speed up collection and shard delete
• 对用户的影响：Upgrade or migration may change expected behavior: v1.37.7 - Speed up collection and shard delete
• 证据：failure_mode_cluster:github_release | https://github.com/weaviate/weaviate/releases/tag/v1.37.7 | v1.37.7 - Speed up collection and shard delete

14. 维护坑 · 来源证据：Deterministic Ordering for Equal-Distance Search Results

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Deterministic Ordering for Equal-Distance Search Results
• 对用户的影响：可能影响升级、迁移或版本选择。
• 证据：community_evidence:github | https://github.com/weaviate/weaviate/issues/11609 | 来源类型 github_issue 暴露的待验证使用条件。

15. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | github_repo:55072677 | https://github.com/weaviate/weaviate | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | github_repo:55072677 | https://github.com/weaviate/weaviate | no_demo; severity=medium

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

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | github_repo:55072677 | https://github.com/weaviate/weaviate | no_demo; severity=medium

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

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | github_repo:55072677 | https://github.com/weaviate/weaviate | issue_or_pr_quality=unknown

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

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | github_repo:55072677 | https://github.com/weaviate/weaviate | release_recency=unknown

20. 维护坑 · 失败模式：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
• 证据：failure_mode_cluster:github_release | 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

21. 维护坑 · 失败模式：maintenance: v1.38.0-rc.1 - 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.1 - HFresh, Namespaces, Nested Object Filtering, Alter Schema Reindex property
• 对用户的影响：Upgrade or migration may change expected behavior: v1.38.0-rc.1 - HFresh, Namespaces, Nested Object Filtering, Alter Schema Reindex property
• 证据：failure_mode_cluster:github_release | https://github.com/weaviate/weaviate/releases/tag/v1.38.0-rc.1 | v1.38.0-rc.1 - HFresh, Namespaces, Nested Object Filtering, Alter Schema Reindex property