Milvus 向量数据库手册

适用版本：服务端 3.0 线 v3.0.5（2026-10-30）、2.6 线 v2.6.26（2026-10-26）仍在维护；官方 Quickstart 采用 PyMilvus 3.0.2 + Milvus Lite 3.2.2（SDK / Lite / 服务端为不同版本线，核实于 2026-11） 许可与形态：Apache 2.0（自托管）／Zilliz Cloud 商业托管；嵌入式（Lite）／单机服务（Standalone）／分布式（Distributed）／全托管（Zilliz Cloud） 一句话定位：面向海量向量的专用向量数据库，以「元数据 + 对象存储 + 计算节点」分层，一套 API 覆盖 Lite、单机与分布式。 约定：$ 普通用户、# root 或 sudo、<xxx> 为占位符；标 ⚠️ 的是高危操作。 更新时间：2026-11（版本与 API 变化快，执行前请以官方文档复核）

目录

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

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

1.1 定位与架构

Milvus 是专为向量检索设计的数据库，核心职责：存向量、建 ANN 索引、相似度检索、叠加标量过滤。它不是给现有库加一个向量列，而是围绕向量重新设计存储与查询链路。四种形态（官方资料确认）：

Standalone 3.0 默认 3 个容器：etcd（元数据）、minio（对象存储）、standalone（计算与接入）。通常元数据落 etcd、原始向量与索引文件落对象存储、计算节点负责索引构建与查询，具体流程以官方架构文档为准。分布式形态通常把接入/查询/数据/索引拆成独立节点并配副本，进程名与数量以官方架构文档为准。

版本差异：Standalone 3.0 起消息队列改为内嵌 Woodpecker（作 WAL），不再需要独立 MQ 容器；2.x 教程里"起 Pulsar / Kafka 容器"的步骤已不适用。

1.2 与同类产品的本质差别

1.3 适合 / 不适合

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

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

Milvus 处在召回层：文档/物品/图片经 embedding 模型得到向量，连同标量字段写入；查询时用相似度检索 + 标量过滤取 top-k 候选，再交给重排或 LLM 拼 context。它不负责生成向量、也不负责最终排序；重排通常由业务侧或外部组件实现，具体融合 API 以官方文档为准、实测为准。

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

2.1 版本状态表（2026-11）

避坑：服务端、PyMilvus、Milvus Lite 是三条独立版本线，数字不可互相套用，也不要用 SDK 版本推断服务端功能。

2.2 许可证与商业版边界

自托管为 Apache 2.0；Zilliz Cloud 为商业托管，功能与计费以官方为准。企业特性、托管版专属能力与价格未查到官方明确说明，本手册不列举具体价格，请以官网报价为准；许可变更风险以官方 LICENSE 与当次发版说明为准。

2.3 官方 URL 表

2.4 版本识别

python3 -m pip show pymilvus milvus-lite       # 客户端 / Lite 版本
docker compose images                          # Standalone 各容器镜像 tag
docker images | grep milvusdb/milvus            # 已拉取镜像 tag

服务端精确版本通常通过 WebUI 或管理接口查询，具体入口以官方文档为准。

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

版本差异：ORM（connections.connect() / Collection() / utility.*）官方明确标注 "NEVER use"，当前统一用 MilvusClient（v2.4+），详见第 5、9 章。

版本差异：Milvus Lite 2.x 建单个 .db 文件，3.x 建目录，两者不兼容，须导出后迁移。

版本差异：Helm 仓库 milvus-io/milvus-helm 已归档（chart ≤ 4.0.31），现用 zilliztech/milvus-helm。

版本差异：稀疏索引 SPARSE_WAND 自 2.5.4 弃用，改 DAAT_WAND；GPU_CAGRA 仅见 2.6.x release notes，索引文档逐字条目未核实（见第 11 章），不得当作确定索引名写入生产配置。

3. 安装与启动

3.1 方式一：pip 装 SDK + Lite

python3 -m pip install "pymilvus[milvus-lite]==3.0.2" "milvus-lite==3.2.2"
python3 -m pip install "pymilvus==3.0.2"     # 仅 SDK，连远程服务端时用

前置：Python 3 与 pip。Lite 进程内运行，无需起服务、无需开端口，第 5 章示例即用此方式。

3.2 方式二：Docker Compose 起 Standalone

wget https://github.com/milvus-io/milvus/releases/download/v3.0.5/milvus-standalone-docker-compose.yaml -O docker-compose.yaml
sudo docker compose up -d

前置：Docker 与 docker compose 插件。3.0 起默认拉起 3 个容器（etcd / minio / standalone），消息队列内嵌 Woodpecker，无需额外 MQ 容器。

3.3 方式三：Helm 部署分布式集群

helm repo add zilliztech https://zilliztech.github.io/milvus-helm/
helm install my-release zilliztech/milvus --set image.all.tag=v3.0.5

前置：Kubernetes 集群与 Helm 3。仓库地址以 2.5 节为准，勿用已归档旧仓库。

3.4 目录与端口表

3.5 健康检查与连通性验证

curl -s http://localhost:9091/healthz          # Standalone 存活探测
sudo docker compose ps                          # 3 个容器是否都 Up
sudo docker compose logs --tail=50 standalone   # 启动日志尾段

客户端连通性用第 5 章建集合 + 插入 + 检索冒烟脚本验证。防火墙放行等基础 Linux 操作见根目录运维手册。

3.6 生产最小配置建议

4. 核心概念与数据模型

4.1 术语对照表

上表含通用分层概念，具体层级与官方命名以数据模型文档为准。

4.2 数据模型层级

Database（通用）→ Collection → Partition（可选）→ Segment（物理）
                                  ↓
                  Entity（行）= 主键 + 向量字段 + 若干标量字段

一条 Entity 至少含一个主键与一个向量字段，其余标量字段（如 subject、text）用于过滤与回显。字段/向量类型的具体常量名以官方 schema 文档为准。

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

方向由 metric_type 决定，且与 SDK 返回的 distance / score 绑定；上表为通用经验，实际以官方 metric 文档与实测为准。

4.4 索引类型与关键参数

4.5 生命周期与一致性模型

经验上，新写入先进入增长段并落 WAL，达到阈值后触发 flush / compaction 并构建索引；检索前集合通常需处于已加载状态。是否异步、是否需显式 load、load 方法名，以及一致性级别名称与默认值，均未查到官方明确说明，以官方文档与实测为准。

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

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

from pymilvus import MilvusClient

# 连接：Lite 直接传本地路径（3.x 建的是目录）
# 连 Standalone 用：MilvusClient(uri="http://localhost:19530", token="root:Milvus")
client = MilvusClient("milvus_demo.db")

# 建集合：示例用 4 维小向量，实际常见 768 / 1024 / 1536
client.create_collection(collection_name="demo_collection", dimension=4)

# 插入：data 为 dict 列表，vector 维度须与 dimension 一致
# subject / text 为标量字段，分别用于过滤与回显
data = [
    {"id": 1, "vector": [0.1, 0.2, 0.3, 0.4], "subject": "history", "text": "秦汉史"},
    {"id": 2, "vector": [0.9, 0.8, 0.7, 0.6], "subject": "history", "text": "唐宋史"},
    {"id": 3, "vector": [0.4, 0.3, 0.2, 0.1], "subject": "math", "text": "线性代数"},
    {"id": 4, "vector": [0.2, 0.1, 0.4, 0.3], "subject": "math", "text": "概率论"},
]
client.insert(collection_name="demo_collection", data=data)

query_vec = [0.15, 0.25, 0.35, 0.45]

# 1) 纯相似度检索
res = client.search(
    collection_name="demo_collection",
    data=[query_vec],
    limit=3,
    output_fields=["text"],
)
print(res)

# 2) 带标量过滤检索：只取 subject == 'history'
res2 = client.search(
    collection_name="demo_collection",
    data=[query_vec],
    filter="subject == 'history'",
    limit=3,
    output_fields=["text"],
)
print(res2)

避坑：旧教程会写成 from pymilvus import connections, Collection, utility，再 connections.connect()、Collection("demo_collection")、utility.* 这一套 ORM。官方明确标注 "NEVER use"，当前统一改用 MilvusClient（v2.4+）：Lite 传本地路径，服务端传 uri= + token=。完整对照见第 9 章。

5.2 输出怎么读

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

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

官方 Quickstart 逐字只覆盖到「连接 → 建集合 → 插入 → 检索 → 带过滤检索」，未逐字给出 MilvusClient 的更新 / 删除 / 清理方法名。按事实优先原则，不在可运行示例里编造这些调用。经验上这类客户端通常具备以下能力，方法名与参数以 pymilvus 官方文档为准、实测为准：

⚠️ 危险：删除集合或清空数据不可逆，生产前必须确认目标集合、先备份、低峰操作。

5.4 REST / cURL 等价示例（仅健康探测）

curl -s http://localhost:9091/healthz

Milvus 主接口是 19530 上的 gRPC / SDK，CRUD 的 REST 路径未查到官方明确说明，以官方 API 文档为准；9091 上确认可用的是 /webui/ 与 /healthz。

6. 索引与检索进阶

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

6.2 检索进阶要点

• recall 与延迟：增大查询搜索范围或建图密度，recall 上升但 P99 延迟与内存上升；建议用 FLAT 精确检索作基线算 recall@k，再逐步调参，实测为准。
• 标量过滤：带 filter 检索时候选是否被预剪枝，以及「过滤后返回少于 limit」，与索引实现有关；Milvus 具体 pre / post-filter 行为未查到官方明确说明，以官方文档为准，排障见第 8 章。
• 混合检索：官方资料确认稀疏向量可用 SPARSE_INVERTED_INDEX 与 IP / BM25 度量，稠密 + 稀疏 BM25 混合可行；但融合 / 重排 / RRF 的具体 API 官方未明确，以官方文档为准、实测为准。

  版本差异：SPARSE_WAND 自 2.5.4 弃用，改用 DAAT_WAND。

• 多向量 / 稀疏 / 重排 / 量化：索引枚举已区分浮点 / 二值 / 稀疏三类；IVF_SQ8 IVF_PQ HNSW_SQ HNSW_PQ HNSW_PRQ 为量化类，通常用于降内存；GPU_IVF_FLAT GPU_IVF_PQ 面向 GPU 场景。多向量 schema、重排 API 以官方文档为准。

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

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

不含 ANN 索引结构、副本、标量字段、WAL、系统开销与量化压缩比；为经验估算，实际以压测与监控为准。

7. 生产部署与运维

7.1 高可用、集群与备份

Distributed 跑在 Kubernetes 上，通常通过多副本与分片提供高可用；Standalone 为单机，无节点级 HA。分片数、副本数、节点角色配置以官方 Helm values 与架构文档为准。备份需同时覆盖 etcd 元数据与对象存储中的向量/索引；恢复后索引是否需重建、具体备份命令与桶路径，未查到官方明确说明，以官方备份恢复文档为准。

7.2 监控、容量与扩缩容

具体 Prometheus 指标名、采集端点与告警阈值未查到官方明确说明，以官方监控文档为准。建议至少覆盖：存活、写入失败率、查询 P99、内存/磁盘水位、索引构建状态；阈值按业务 SLO 设定，实测为准。容量按 6.3 估算后叠加索引、副本与增长余量；扩缩容操作以官方 K8s 运维文档为准。

7.3 升级与跨版本迁移

版本差异：Lite 2.x .db 与 3.x 目录不兼容，须导出后迁移，不能直接拿新客户端打开旧文件。

版本差异：3.0 起 Standalone 用内嵌 Woodpecker 作 WAL，从 2.x 升级时不要再拉独立 MQ 容器；Helm 用户须从已归档的 milvus-io/milvus-helm 迁到 zilliztech/milvus-helm。

升级顺序、是否需停机、数据格式兼容矩阵，未查到官方明确说明，以官方升级指南为准。

7.4 安全基线与日志

8. 高频故障与排障

9. 常见坑与避坑清单

1. 照抄旧 ORM 教程：connections / Collection / utility 导入报错或行为异常，原因是官方已标注 "NEVER use"；怎么做：全部改用 MilvusClient（v2.4+），连接方式按 5.1。
2. Lite 2.x 数据直接被 3.x 打开：打开失败或数据不可见，原因是 2.x 是 .db、3.x 是目录；怎么做：从 2.x 导出后迁移，勿直接覆盖。

   ⚠️ 危险：用新版本直接覆盖旧 Lite 数据目录可能造成数据不可用，操作前先整目录备份。

3. 3.0 仍去起独立 MQ 容器：出现多余容器、端口冲突，原因是 3.0 已内嵌 Woodpecker；怎么做：按官方 compose 只起 3 个容器。
4. Helm 用旧仓库：helm repo add 失败或 chart 过旧，原因是 milvus-io/milvus-helm 已归档；怎么做：改 zilliztech/milvus-helm。
5. 混淆三条版本线：拿 SDK 版本号判断服务端功能；怎么做：分别用 2.4 节命令核实各自版本。
6. 插入维度与 dimension 不一致：插入报错；怎么做：create_collection(dimension=...) 与 vector 长度对齐。
7. 忽略默认 COSINE：相似度方向或排序与预期不符；怎么做：显式选 metric_type，与 embedding 模型匹配，实测为准。
8. 索引/集合未就绪就检索：查不到或退化为精确扫描；怎么做：确认加载与索引构建状态，是否需显式 load 以官方文档为准。
9. 把 GPU_CAGRA 当确定索引：建索引报未知索引，原因是该条目仅见 2.6.x release notes、索引文档逐字条目未核实；怎么做：只用 4.4 表中确认的索引名，其余以官方文档为准。
10. 稀疏检索沿用 SPARSE_WAND：弃用告警或行为变化，原因是 2.5.4 起弃用；怎么做：改 DAAT_WAND。
11. 默认 token 上生产：未授权可访问 19530，原因是沿用 root:Milvus；怎么做：部署即改 token，收敛网络暴露面。

    ⚠️ 危险：默认凭据 + 公网直曝等于数据裸奔，属高危配置。

12. 误删集合 / 清库：线上数据丢失；怎么做：删除前备份、核对目标集合名、低峰执行。

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

13. 单机默认资源直接上生产：高峰期 OOM 或查询抖动；怎么做：设 CPU / 内存 limit，按 6.3 估算容量并压测。

10. 速查表

常用端口与路径

11. 参考与延伸

11.1 官方文档链接清单

官网 https://milvus.io ｜ 文档 https://milvus.io/docs ｜ Quickstart https://milvus.io/docs/quickstart.md ｜ GitHub https://github.com/milvus-io/milvus ｜ Releases https://github.com/milvus-io/milvus/releases ｜ Docker 镜像 https://hub.docker.com/r/milvusdb/milvus ｜ Compose 文档 https://milvus.io/docs/install_standalone-docker-compose.md ｜ Helm 文档 https://milvus.io/docs/install_cluster-helm.md ｜ 索引 https://milvus.io/docs/index.md ｜ 度量 https://milvus.io/docs/metric.md

11.2 与同册其他产品的关系

• 已有 PostgreSQL 实例、只需加向量列：见融合型分册 pgvector 篇（模板示例 pgvector.md）。
• 想要纯嵌入式、无服务进程：见同册 LanceDB / Chroma 相关篇。
• 对比专用向量库 API 风格：见 Qdrant.md、Weaviate.md；免运维托管见云托管分册 Zilliz Cloud 篇。

11.3 进阶阅读方向

索引选型与量化（IVF_PQ / HNSW_* / SCANN / DISKANN）、稠密+稀疏 BM25 混合检索、K8s 分布式运维、以 FLAT 为基线的 recall 基准测试；具体 API 与参数以官方文档为准。

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

1. GPU_CAGRA 索引：仅见 2.6.x release notes，索引文档逐字条目未核实；正文未列入确定索引枚举，生产配置不得当作确定可用索引名。
2. MilvusClient 的更新 / 删除 / 清理方法名与参数：Quickstart 未逐字给出，5.3 为经验性说明，以 pymilvus 官方文档为准、实测为准。
3. 各索引关键参数名、默认值、建议范围：官方未明确，以官方 index.md 为准；第 6 章均为经验性讨论。
4. 字段 / 向量类型具体常量名、一致性级别名称与默认值、写入→可检索是否需显式 load：官方未明确，以官方文档为准。
5. CRUD 的 REST 路径、监控具体指标名、备份恢复具体命令、文件日志默认路径、pre/post-filter 具体行为、混合检索融合/RRF API：官方未明确，以官方文档为准、实测为准。
6. 距离 / score 方向（L2 / IP / COSINE）与 pre/post-filter 结论：为通用经验，正文一律以「通常 / 实测为准 / 以官方文档为准」表述，非官方结论。
7. 规模量级、容量公式、告警阈值：为经验估算，非官方承诺，以压测与监控数据为准。