Weaviate 向量数据库手册

适用版本：GitHub 最新 tag v1.40.3（2026-10-28，Latest）；官方「版本支持策略」维护线为 1.39（v1.39.5）/ 1.38 / 1.37，1.36 及更早不再维护（两种口径不一致，核实于 2026-11） 许可与形态：双许可 —— wl/ 目录外 BSD-3-Clause，wl/ 内为企业许可（需 license key）；单机服务 / 分布式集群 / 全托管（Weaviate Cloud） 一句话定位：带模块化向量化能力的专用向量数据库，v4 起以 collections API + gRPC 为核心，检索用 query.near_* 系列。 约定：$ 普通用户、# root 或 sudo、<xxx> 为占位符；标 ⚠️ 的是高危操作。 更新时间：2026-11（版本与 API 变化快，执行前请以官方文档复核）

目录

1. 它是什么、什么时候选它
2. 版本、许可与官方入口
3. 安装与启动
4. 核心概念与数据模型
5. 快速上手：完整 CRUD 示例
6. 索引与检索进阶
7. 生产部署与运维
8. 高频故障与排障
9. 常见坑与避坑清单
10. 速查表
11. 参考与延伸

1. 它是什么、什么时候选它

1.1 定位与架构

Weaviate 是面向向量检索的专用数据库，特点是「向量化模块化」：通过 ENABLE_MODULES 挂载 text2vec-* / generative-* 等模块，既可在写入/查询时由服务端生成向量，也可自带向量（near_vector）。数据以 object（属性 properties + 向量 + 元数据）组织在 collection 里。v4 客户端改为 gRPC 化，官方 Quickstart 用 weaviate.connect_to_local() 连接，检索走 collection.query.near_vector / near_text 系列。对外暴露三个面（官方资料确认）：

未核实 / 口径不一致：官方资料显示「GitHub 最新 tag v1.40.3」与「官方支持策略页维护线 1.39 / 1.38 / 1.37」并不一致。本手册不把任一口径写成「当前唯一稳定版」：镜像示例沿用官方 Quickstart 用的 1.40.3，但生产选型以官方支持策略页与官方文档为准，见第 11 章。

1.2 与同类产品的本质差别

1.3 适合 / 不适合

1.4 规模参考量级（经验值，非官方承诺）

1.5 在 RAG / 推荐 / 以图搜图链路中的位置

Weaviate 处在召回层：文档/物品/图片经向量化模块或外部 embedding 得到向量，连同属性写入 collection；查询用 query.near_vector / query.near_text 取近邻，用 Filter.by_property 做属性过滤，返回候选后交给重排或 LLM 拼 context。重排与融合 API 以官方文档为准、实测为准。

2. 版本、许可与官方入口

2.1 版本状态表（2026-11，两种口径分列）

避坑：写文档、做选型、填工单时必须区分「最新 tag」与「文档支持线」。两者口径不一致，官方资料未给出统一解释，以官方支持策略页为准，见第 11 章。

2.2 许可证与商业版边界

wl/ 目录外为 BSD-3-Clause，wl/ 内为企业许可（需 license key）；Weaviate Cloud 为商业托管，功能与计费以官方为准。企业特性、托管版专属能力与价格未查到官方明确说明，本手册不列举具体价格，请以官网报价为准；双许可边界与许可变更风险以官方 LICENSE 为准。

2.3 官方 URL 表

2.4 版本识别

docker images | grep weaviate                 # 已拉取镜像 tag（注意 cr.weaviate.io 前缀）
pip show weaviate-client                      # 客户端版本
curl -s http://localhost:8080/v1/meta         # 元数据端点，通常含版本信息，以实际返回为准
curl -s http://localhost:8080/v1/nodes        # 节点信息

/v1/meta 的具体版本字段以实际返回为准，本手册不写死字段名。

2.5 近两年重要变更与弃用提醒

版本差异：v3 的 weaviate.Client(...) / data_object.create / with_near_vector({...}) 不再适用；v4 用 connect_to_local() + client.collections.* + query.near_* + Filter.by_property，详见第 5、9 章。

版本差异：镜像 registry 从 Docker Hub 的 semitechnologies/weaviate 迁到 cr.weaviate.io/semitechnologies/weaviate，旧拉取地址不再适用。

版本差异：新增 OPERATIONAL_MODE（v1.35+），具体取值与影响以官方文档为准。v3 客户端的逐字弃用声明官方资料未取得，本手册只按官方资料结论写「不再适用 / 应迁移」，是否已有正式 deprecation 声明以官方迁移文档为准，见第 11 章。

3. 安装与启动

3.1 方式一：Docker Compose（官方 Quickstart yaml）

services:
  weaviate:
    image: cr.weaviate.io/semitechnologies/weaviate:1.40.3
    ports: ["8080:8080", "50051:50051"]
    environment:
      AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED: 'true'
      PERSISTENCE_DATA_PATH: '/var/lib/weaviate'
      ENABLE_MODULES: 'text2vec-ollama,generative-ollama'
      CLUSTER_HOSTNAME: 'node1'

前置：Docker 与 docker compose 可用。注意镜像已带 cr.weaviate.io 前缀（见 2.5）；上述 yaml 来自官方 Quickstart，逐字采用。

3.2 方式二：Python 客户端

pip install -U weaviate-client

本地服务用 weaviate.connect_to_local() 连接；连云用 connect_to_weaviate_cloud(cluster_url=..., auth_credentials=...)，具体参数以官方文档为准。

3.3 方式三：Helm 部署到 Kubernetes

官方资料确认 Helm chart 为 17.8.3（weaviate/weaviate-helm）；具体 helm repo add / helm install 命令官方资料未逐字给出，以官方 K8s 安装文档 https://docs.weaviate.io/weaviate/installation/kubernetes 为准，本手册不编造仓库地址与命令行。

3.4 目录与端口表

3.5 健康检查与连通性验证

curl -s http://localhost:8080/v1/.well-known/live
curl -s http://localhost:8080/v1/.well-known/ready
curl -s http://localhost:8080/v1/meta
curl -s http://localhost:8080/v1/nodes

客户端连通性用第 5 章脚本验证；Prometheus 指标需先设 PROMETHEUS_MONITORING_ENABLED=true 才在 2112 暴露。防火墙放行等基础操作见根目录运维手册。

3.6 生产最小配置建议

4. 核心概念与数据模型

4.1 术语对照表

4.2 数据模型层级

Collection（定义属性、向量化方式、索引与度量）
    └── Object = 属性 properties（如 title / year）+ 向量 + 元数据
            ├── 向量可由模块化向量化（text2vec-*）生成，或自带（near_vector）
            └── 属性可被 Filter.by_property 过滤

client.collections.create("Movie") 建集合，collection.data.insert({...}) 写对象，collection.query.near_* 检索。多租户、命名向量等通用概念的具体 API 以官方文档为准。

4.3 字段 / 向量类型与距离度量

关于「值越大越相似还是越小越相似」：官方资料明确为「值越小越相似」，即 distance 越小越接近。这与以 score 越大越相似的产品正好相反，迁移时务必注意排序方向。

4.4 索引类型与关键参数

4.5 生命周期与一致性模型

collection.data.insert({...}) 写入对象，query.near_* 检索。索引构建是否异步、dynamic 何时从 flat 切到 hnsw、副本一致性语义，未查到官方明确说明，以官方文档与实测为准。

5. 快速上手：完整 CRUD 示例

5.1 完整可运行 Python 示例（基于官方 v4 Quickstart）

官方 Quickstart 的逐字写法要点：连接用 weaviate.connect_to_local()（云用 connect_to_weaviate_cloud(cluster_url=..., auth_credentials=...)），建集合用 client.collections.create("Movie")，插入用 collection.data.insert({"title": "...", "year": 2020})；检索一种是 collection.query.near_vector(near_vector=..., return_metadata=MetadataQuery(distance=True), limit=3)，另一种是 collection.query.near_text(query="...", filters=Filter.by_property("round").equal("Double Jeopardy!"))。

下面把它展开成覆盖「连接 → 建集合 → 插入 → 相似度检索 → 带标量过滤检索」的完整可运行版本（示例用 4 维小向量，实际常见 768 / 1024 / 1536）：

import weaviate
from weaviate.classes.query import MetadataQuery, Filter

client = weaviate.connect_to_local()
collection = client.collections.create("Movie")

# 插入（写入）：属性放同一个 dict
collection.data.insert({"title": "Inception", "year": 2010})
collection.data.insert({"title": "Interstellar", "year": 2014})
collection.data.insert({"title": "The Matrix", "year": 1999})

# 示例用 4 维小向量，实际常见 768 / 1024 / 1536
qv = [0.1, 0.2, 0.3, 0.4]

# 1) 纯相似度检索（自带向量，不依赖向量化模块）
resp = collection.query.near_vector(
    near_vector=qv,
    return_metadata=MetadataQuery(distance=True),
    limit=3,
)
print(resp)

# 2) 带标量过滤检索：属性 year == 2010（同组 API 组合，见下方说明）
resp2 = collection.query.near_vector(
    near_vector=qv,
    filters=Filter.by_property("year").equal(2010),
    return_metadata=MetadataQuery(distance=True),
    limit=3,
)
print(resp2)

避坑：旧教程（v3）会写成 client = weaviate.Client("http://localhost:8080")、client.data_object.create({...})、query.with_near_vector({"vector": qv}).do()。v4 不再适用，当前用 connect_to_local() + client.collections.* + query.near_vector(near_vector=...) + Filter.by_property。完整对照见第 9 章。

逐字骨架里的 near_text 依赖服务端向量化模块（如 3.1 的 text2vec-ollama），且字段名须是集合里真实存在的属性；完整示例用 near_vector + year 以保证自带向量即可运行。near_vector + filters 为按官方同组 API 组合（官方资料注明非逐字完整示例），以官方文档为准、实测为准。

5.2 输出怎么读

返回对象的逐字段结构以 SDK 实际输出为准。

5.3 更新 / 删除 / 清理（经验性说明）

官方 v4 Quickstart 逐字只覆盖到「连接 → 建集合 → 插入 → 检索」，未逐字给出 collection.data 的更新 / 删除方法名与删除集合的方法名。按事实优先原则，不在可运行示例里编造这些调用。经验上 v4 的 collections API 通常具备以下能力，方法名与参数以 weaviate-client 官方文档为准、实测为准：

⚠️ 危险：删除集合不可逆，生产前必须核对集合名、先备份、低峰操作。

5.4 REST / cURL 等价示例（仅状态探测）

curl -s http://localhost:8080/v1/.well-known/live
curl -s http://localhost:8080/v1/.well-known/ready
curl -s http://localhost:8080/v1/meta
curl -s http://localhost:8080/v1/nodes

CRUD 的 REST 路径未查到官方明确说明，以官方 API 文档为准；以上仅列官方资料确认的状态端点。

6. 索引与检索进阶

6.1 索引参数调优表（经验性）

上述参数确切名称、默认值、建议范围均未查到官方明确说明，以官方配置文档为准；本表为经验性讨论。

6.2 检索进阶要点

• recall 与延迟：HNSW 查询范围越大召回越好但 P99 上升；flat 精确但随数据量线性变慢；dynamic 自动切换；hfresh 以磁盘换成本。建议以 flat 精确结果作基线算 recall@k，实测为准。
• 标量过滤：Filter.by_property(...) 把属性过滤与 near_* 组合在一次查询里；过滤过严导致返回少于 limit 是常见现象（见第 8 章），具体 pre / post-filter 实现以官方文档为准。
• 混合检索 / 多向量 / 量化：near_text 与 near_vector 覆盖不同召回路径；关键词+稠密混合、RRF 融合与重排的具体 API 官方未明确。索引侧确认 hnsw / flat / dynamic / hfresh 四类，hfresh 仅 cosine、l2-squared；多向量、稀疏、重排、量化及 OPERATIONAL_MODE（v1.35+）相关能力以官方文档为准。

6.3 内存与磁盘容量估算（经验公式）

原始向量内存 ≈ 条数 N × 维度 D × 每维字节数（float32 = 4 B）
示例：N = 1e7，D = 768，float32 → 1e7 × 768 × 4 B ≈ 30.7 GB（仅原始向量）

不含 HNSW 图、对象属性、倒排/属性索引、副本、量化与系统开销；hfresh 为磁盘型，内存模型不同。为经验估算，实际以压测与监控为准。

7. 生产部署与运维

7.1 高可用、集群与备份

分布式集群通常通过副本与分片提供高可用；CLUSTER_HOSTNAME（见 3.1）与集群相关，具体副本数、分片策略以官方集群文档为准。数据落在 PERSISTENCE_DATA_PATH 指向的目录（3.1 中为 /var/lib/weaviate），通常以官方推荐流程做一致性备份；备份命令、恢复后索引是否需重建、hfresh 等磁盘型索引的备份范围，未查到官方明确说明，以官方备份文档为准。

7.2 监控、容量与扩缩容

具体指标名与告警阈值未查到官方明确说明，以官方监控文档为准。建议至少覆盖：存活/就绪、写入失败率、查询 P99、内存与磁盘水位、对象数；阈值按业务 SLO 设定，实测为准。容量按 6.3 估算后叠加 HNSW 图、对象属性、副本与增长余量；扩缩容以官方集群文档为准。

7.3 升级与跨版本迁移

版本差异：v3 → v4 是客户端代码级迁移，不是简单换版本号：weaviate.Client / data_object.create / with_near_vector 全要改成 connect_to_local() + collections + query.near_*。

版本差异：镜像 registry 迁到 cr.weaviate.io/semitechnologies/weaviate，升级时改拉取地址，勿再从旧地址拉镜像；OPERATIONAL_MODE（v1.35+）新增，升级核对版本时留意相关配置，以官方文档为准。

避坑：升级前先确认目标版本属于「最新 tag」还是「官方支持线」，两者口径不一致（见 2.1），以官方支持策略页为准。跨版本数据格式兼容矩阵、是否需停机，未查到官方明确说明，以官方升级指南为准。

7.4 安全基线与日志

8. 高频故障与排障

9. 常见坑与避坑清单

1. 沿用 v3 客户端：weaviate.Client / data_object.create / with_near_vector 报错或不存在，原因是 v4 已改 collections API；怎么做：改 connect_to_local() + client.collections.* + query.near_* + Filter.by_property。

   未核实：v3 的逐字弃用声明官方资料未取得，是否已有正式 deprecation 以官方迁移文档为准。

2. 镜像从旧 registry 拉：拉取失败或拿到旧镜像，原因是 registry 迁到 cr.weaviate.io/semitechnologies/weaviate；怎么做：所有 yaml / 脚本改用新前缀。
3. 混淆「最新 tag」与「支持线」：按 1.40.3 规划生产却与官方支持口径对不上；怎么做：区分 2.1 两行，生产以官方支持策略页为准。
4. 把 distance 当成越大越相似：排序看起来反了，原因是官方资料明确「值越小越相似」；怎么做：按 distance 升序取 top-k，与 score 类产品区分。
5. 生产沿用匿名访问：8080 可被任意访问，原因是 Quickstart 的 AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED: 'true'；怎么做：生产关闭匿名、配认证。

   ⚠️ 危险：匿名访问 + 公网直曝等于数据裸奔，属高危配置。

6. near_text 没配向量化模块：查询报错或向量为空，原因是缺 text2vec-* 模块；怎么做：按 3.1 设 ENABLE_MODULES，或改用自带向量的 near_vector。
7. 过滤字段名写错：结果为空或变少，原因是 Filter.by_property("round") 里的属性在集合里不存在；怎么做：过滤字段用集合里真实存在的属性（如示例的 year）。
8. 不启用监控却去抓 2112：2112 无数据，原因是需 PROMETHEUS_MONITORING_ENABLED=true；怎么做：显式启用该环境变量。
9. 照搬 v3 的 with_near_vector({"vector": ...}) 字典写法：参数报错，原因是 v4 用 near_vector=qv 关键字；怎么做：按 5.1 的 query.near_vector(near_vector=...) 书写。
10. 误删集合：线上数据丢失；怎么做：先备份、核对集合名、低峰执行。

    ⚠️ 危险：删除集合不可逆，务必先备份。

11. 容器不挂持久化卷：重建后数据全空，原因是 PERSISTENCE_DATA_PATH 未挂可靠卷；怎么做：为 /var/lib/weaviate 挂卷并备份。

    ⚠️ 危险：生产不挂卷等于把数据放在可丢弃层，重建即丢。

12. hfresh 用错度量：建索引/查询异常，原因是 hfresh 仅 cosine、l2-squared；怎么做：用这两种度量，其余以官方文档为准。
13. Helm 命令照抄第三方：仓库地址或 chart 版本对不上，原因是目前仅确认 chart 17.8.3、未给逐字命令；怎么做：以官方 K8s 安装文档为准，不编造命令。

10. 速查表

常用端口与路径

11. 参考与延伸

11.1 官方文档链接清单

官网 https://weaviate.io ｜ 文档 https://docs.weaviate.io ｜ GitHub https://github.com/weaviate/weaviate ｜ Releases https://github.com/weaviate/weaviate/releases/tag/v1.40.3 ｜ 镜像 registry https://cr.weaviate.io ｜ Quickstart https://docs.weaviate.io/weaviate/quickstart ｜ 本地 Quickstart https://docs.weaviate.io/weaviate/quickstart/local ｜ 相似度检索 https://docs.weaviate.io/weaviate/search/similarity ｜ K8s 安装 https://docs.weaviate.io/weaviate/installation/kubernetes ｜ 支持策略 https://docs.weaviate.io/weaviate/roadmap ｜ 距离度量 https://docs.weaviate.io/weaviate/config-refs/distances ｜ 状态 / 监控 https://docs.weaviate.io/deploy/configuration/status

11.2 与同册其他产品的关系

• 已有 PostgreSQL 实例、只需加向量列：见融合型分册 pgvector 篇（模板示例 pgvector.md）。
• 对比同为专用向量库的架构与 API：见 Milvus.md、Qdrant.md；免运维托管见云托管分册 Weaviate Cloud 相关篇；只要进程内索引库见向量索引库分册 Faiss / hnswlib 篇。

11.3 进阶阅读方向

v3 → v4 客户端迁移、模块化向量化（text2vec-* / generative-*）部署与调优、hnsw / flat / dynamic / hfresh 索引选型、OPERATIONAL_MODE（v1.35+）、双许可边界评估；具体 API 与参数以官方文档为准。

11.4 本篇「未核实 / 以官方为准」事项

1. 版本支持线口径不一致（重点）：GitHub 最新 tag v1.40.3 与官方支持策略页维护线 1.39（v1.39.5）/ 1.38 / 1.37 口径不一致，1.36 及更早不再维护。正文 2.1 分列两种口径、未写成「当前唯一稳定版」；生产选型以官方支持策略页为准。
2. v3 客户端弃用声明未取得：官方资料只给出「v3 写法不再适用 / 应迁到 v4」结论，正式 deprecation 声明未取得；正文按结论写「不再适用」，是否已有官方弃用声明以官方迁移文档为准。
3. collection.data 的更新 / 删除方法名、删除集合方法名：v4 Quickstart 未逐字给出，5.3 为经验性说明，以 weaviate-client 官方文档为准、实测为准。
4. 索引 / HNSW 参数确切名称、默认值、建议范围、默认索引类型、一致性模型、写入→可检索细节、多向量 / 稀疏 / 重排 / 量化 / 混合检索（RRF）API、pre/post-filter 具体行为：官方未明确，以官方文档为准、实测为准；第 6 章均为经验性讨论。
5. Helm 的 helm repo add / helm install 逐字命令：目前仅确认 chart 17.8.3（weaviate/weaviate-helm），未给命令；正文不编造，以官方 K8s 安装文档为准。
6. CRUD 的 REST 路径、监控具体指标名、备份恢复具体命令、文件日志默认路径、/v1/meta 版本字段、OPERATIONAL_MODE 具体取值与影响：官方未明确，以官方文档为准。
7. near_vector + filters 组合：为按官方同组 API 组合（官方资料注明「非逐字完整示例」），字段名与可用性以官方文档为准、实测为准。
8. 容量公式、规模量级、告警阈值：为经验估算，非官方承诺，以压测与监控数据为准。