Milvus 向量数据库中文指南：产品能力、源码编译、无状态组件架构与混合查询实现解析

本文以 Milvus 官方中文文档 README_CN.md 为核心骨架，系统讲解 Milvus 作为云原生向量数据库的定位、七大产品亮点、快速上手方式与源码编译流程，并结合当前仓库的 Makefile、cmd/roles/roles.go、DEVELOPMENT.md 等源码与配置，深入剖析其存储计算分离的无状态组件架构、混合查询（RRF/Weighted）rerank 实现与 Docker 部署形态，帮助开发者从"会用"走向"看懂架构、能编译、能排查"。

一、Milvus 是什么

按 README_CN.md 的定义：Milvus 是一款开源向量数据库，面向 AI 应用和向量相似度搜索，用于加速非结构化数据检索，用户在任何部署环境中均可获得始终如一的用户体验。

几个关键事实（均来自仓库文档与源码）：

• 云原生、存储与计算分离：Milvus 2.0 是一次彻底重构的版本，所有组件均为无状态组件，系统弹性与灵活性由此而来。从源码结构看，这一设计体现在 cmd/roles/roles.go 中：MilvusRoles 通过一组 ENABLE_* 环境变量（ENABLE_PROXY、ENABLE_ROOT_COORD、ENABLE_QUERY_NODE、ENABLE_DATA_NODE、ENABLE_STREAMING_NODE、ENABLE_CDC）决定单进程拉起哪些组件，同一二进制既可以跑单机版，也可以按角色拆成集群版。
• 开源协议与出身：基于 Apache 2.0 协议 发布，2019 年 10 月正式开源，是 LF AI & Data 基金会的毕业项目。
• 代码组织：主模块为 go.mod 中的 github.com/milvus-io/milvus；仓库同时内嵌了 Go SDK（client/go.mod 中模块为 github.com/milvus-io/milvus/client/v3），以及 C++ 核心库目录 internal/core/（含 src、unittest、thirdparty 与 CMakeLists.txt）。

版本说明：README 中的提示称"主分支用于 Milvus v2.0 代码开发，Milvus 1.0 于 2021 年 3 月 9 日发布且为首个 LTS 版本"。需要注意，当前仓库代码已明显演进（例如 pkg/v3、client/v3 模块路径），实际版本能力请以具体 release 分支为准。

二、产品亮点（官方七大能力逐项解读）

README_CN.md 以折叠块列出了七大亮点，以下逐项继承原文并结合仓库证据补充：

2.1 针对万亿级向量的毫秒级搜索

完成万亿条向量数据搜索的平均延迟以毫秒计。这是官方 README 给出的能力表述。从源码结构看，搜索热点路径位于 C++ 核心库 internal/core/（包括索引库 Knowhere 与 segcore 执行引擎），Makefile 中 index_engine = knowhere 指明了算法引擎来源。

2.2 简化的非结构化数据管理

• 一整套专为数据科学工作流设计的 API；
• 无论是笔记本、本地集群还是云服务器，始终如一的跨平台用户体验；
• 可以在任何场景下实现实时搜索与分析。

这一点的代码支撑是仓库内置的 Go 客户端 client/milvusclient/：集合、分区、索引、写入（write.go）、读取与搜索（read.go）、RBAC、迭代器（iterator.go）等 API 均在此实现，覆盖了典型数据科学工作流。

2.3 稳定可靠的用户体验

Milvus 具有故障转移和故障恢复机制，即使服务中断，也能确保数据和应用的业务连续性。在 cmd/roles/roles.go 中可以看到其工程化实现：handleSignals 捕获 SIGHUP/SIGINT/SIGTERM/SIGQUIT 后走优雅停机流程——先停协调者（MixCoord），再并发停止各 Node（StreamingNode、QueryNode、DataNode、CDC），最后停 Proxy，并关闭复用的 etcd 客户端，保证关闭过程的有序与幂等。

2.4 高度可扩展，弹性伸缩

组件级别的高扩展性，支持精准扩展。对应地，cmd/components/ 下为每个角色提供了独立入口文件（proxy.go、query_node.go、data_node.go、streaming_node.go、mix_coord.go、cdc.go），分布式部署时即可"按角色独立扩缩容"。

2.5 混合查询（多向量 + 混合搜索框架）

原文要点：Milvus 2.4 引入了多向量支持和混合查询框架，用户可以将多个向量字段（最多 10 个）导入到单个 Collection 中，这些向量来自不同的嵌入模型或处理方法，分别代表不同数据特征；混合搜索结果使用 reranking 策略对各向量列结果进行融合，如 Reciprocal Rank Fusion（RRF） 和 Weighted Scoring。该特性尤其适用于综合搜索场景，例如基于多种属性（照片、声音、指纹等）识别向量库中最相似的人。

仓库源码印证了这两种 rerank 策略的实现位置——Go 客户端中的 client/milvusclient/reranker.go 提供了 NewRRFReranker() 与 NewWeightedReranker(weights) 两个构造函数，分别对应 RRF 融合与按列加权融合，与官方文档描述一一对应。

2.6 基于 Lambda 架构的流批一体式数据存储

Milvus 在存储数据时支持流处理和批处理两种方式，兼顾流处理的时效性和批处理的效率；统一的对外接口使向量相似度查询更便捷。从源码结构看，写入链路（StreamingNode/DataNode，见 internal/streamingnode/、internal/datanode/）与查询链路（QueryNode，internal/querynodev2/）职责分离，正是流批分工的体现。

2.7 广受社区支持和业界认可

README 原文称：Milvus 在 GitHub 获星超 8000，拥有逾 1000 家企业用户，拥有活跃的开源社区，并获 LF AI & Data 基金会背书。这是官方文档的表述，社区规模随时间增长，最新数据请以官方渠道为准。

三、快速开始

3.1 启动 Milvus（Docker 方式）

README 推荐的两条路径是"安装 Milvus 单机版"与"安装 Milvus 分布式版本"（均通过 Docker 部署）。当前仓库提供了对应的部署物料，可直接用于本地验证：

• 单机版编排：docker-compose.yml 与 deployments/docker/standalone/；
• 分布式集群编排：deployments/docker/cluster-distributed-deployment/（含 15 个 yml 组件文件）；
• GPU 部署参考：deployments/docker/gpu/；
• 二进制部署与离线保存镜像：deployments/binary/README.md、deployments/offline/README.md（save_image.py 用于导出镜像）。

3.2 源码编译 Milvus

README 给出的最小依赖清单与编译命令：

go: 1.21
cmake: >=3.18
gcc: >= 11
protobuf: >=3.7

# 克隆项目
$ git clone <Milvus 开源仓库地址>

# 安装第三方依赖
$ cd milvus/
$ ./scripts/install_deps.sh

# 编译 Milvus 单机版
$ make milvus

结合 scripts/install_deps.sh 与 DEVELOPMENT.md 可把上述要求补充为当前仓库实际执行的完整前提：

项	要求	依据
Go	>= 1.21（README 与脚本一致；go.mod 当前声明 go 1.26.6）	scripts/install_deps.sh
CMake	>= 3.26（脚本实际校验版本，比 README 的 3.18 更新）	scripts/install_deps.sh
GCC（Linux）	11、12、13、14	DEVELOPMENT.md
Clang（macOS）	15、16、17	DEVELOPMENT.md
Conan	2.25.1（由 install_deps.sh 自动安装；release-2.5/2.6 分支仍用 1.x）	DEVELOPMENT.md
Rust	1.92（由 install_deps.sh 自动安装）	scripts/install_deps.sh
硬件	8GB RAM、50GB 空闲磁盘	DEVELOPMENT.md
支持平台	macOS 12–15（Intel/Apple Silicon）、Ubuntu 20.04/22.04/24.04、Rocky Linux 9、Amazon Linux 2023	scripts/install_deps.sh

install_deps.sh 会自动检测操作系统与版本，安装编译器（macOS 用 LLVM，Linux 用 GCC）、CMake/Ninja/ccache、Conan 与 Rust 工具链。安装完成后用 clang --version 或 gcc --version 验证。

编译链路的源码视角：Makefile 中 milvus 目标是三段式流水线：

milvus: build-cpp print-build-info build-go

• build-cpp（Makefile）：先经 generated-proto 与 plan-parser-lib 前置步骤，再编译 internal/core/ 下的 C++ 核心库（含 Knowhere 索引引擎）；
• build-go（Makefile）：加载 scripts/setenv.sh 环境后以 CGO 方式编译 Go 侧；构建标签为 dynamic,sonic,with_jemalloc,bytedance_tango（Makefile），其中 jemalloc 通过 LD_PRELOAD 生效（见 cmd/roles/roles.go 的 printLDPreLoad）；
• 产物输出到 bin/milvus（INSTALL_PATH := $(PWD)/bin，Makefile）。

此外，Makefile 还暴露了若干实用开关，可作为编译问题排查线索：macOS 上默认关闭 disk_index（Darwin 不支持 aio，Makefile）、USE_ASAN=ON 开启 AddressSanitizer、MILVUS_FIPS_ENABLED=ON 切换 BoringCrypto（FIPS 模式，Makefile）。

四、组件架构与部署形态：从代码看懂"无状态"

README 强调"所有组件均为无状态组件"。cmd/roles/roles.go 是理解这句话的最佳入口：

1. 角色矩阵：MilvusRoles 结构体（cmd/roles/roles.go）以 ENABLE_* 环境变量为开关，组合出 Standalone / Cluster 形态。Run() 方法（cmd/roles/roles.go）会：
   • mr.Local 为真时注入 StandaloneDeployMode 并启动内嵌 etcd（UseEmbedEtcd），否则注入 ClusterDeployMode（cmd/roles/roles.go）；
   • 按开关并发创建各组件（runComponent 采用 Prepare/Run 两阶段，允许组件并行启动，cmd/roles/roles.go），并通过 waitForAllComponentsReady 做"快速失败"的就绪等待。
2. 当前代码中的角色集合：Proxy、MixCoord（融合协调者，ENABLE_ROOT_COORD 亦映射到它）、QueryNode、DataNode、StreamingNode、CDC，共六个可开关角色（cmd/roles/roles.go）。从源码结构看，相比早期 2.x 的 RootCoord/DataCoord/QueryCoord 三分法，当前版本已将协调层收敛为 MixCoord，并新增 StreamingNode 与 CDC 角色，说明架构在持续演进。
3. 可观测性：每个组件注册到 Prometheus 独立 Registry（cmd/roles/roles.go），HTTP 层暴露 metrics 与健康检查（healthz，见 internal/http/），并提供按角色停止/查询健康状态的接口（cmd/roles/roles.go）。
4. 本地缓存是"无状态"的例外：QueryNode 启动时若非 POSIX 模式会清理本地数据缓存（cleanLocalDir，cmd/roles/roles.go），即本地磁盘只作缓存而非事实来源，数据权威存储在对象存储。

默认配置参考：configs/milvus.yaml 是运行配置的主文件，其中可见：元存储默认 etcd（支持 tikv，configs/milvus.yaml）、数据根路径 rootPath: by-dev（configs/milvus.yaml）等；etcd 独立配置见 configs/advanced/etcd.yaml。日志格式见 configs/glog.conf。

五、教程与应用场景

5.1 官方教程清单（继承自 README_CN.md 表格）

以下 20 个教程覆盖了 RAG、语义搜索、混合搜索、问答、推荐系统、聚类与可视化等主题（原文档链接指向官方文档站，此处保留教程名称与对应的 Milvus 功能映射）：

教程	使用场景	相关 Milvus 功能
使用 Milvus 构建 RAG	RAG	向量搜索
使用 Milvus 构建多模态 RAG	RAG	向量搜索、动态字段
使用 Milvus 进行图像搜索	语义搜索	向量搜索、动态字段
使用 Milvus 进行混合搜索	混合搜索	混合搜索、多向量、密集嵌入、稀疏嵌入
使用多向量实现多模态搜索	语义搜索	多向量、混合搜索
问答系统	问答系统	向量搜索
推荐系统	推荐系统	向量搜索
视频相似性搜索	语义搜索	向量搜索
音频相似性搜索	语义搜索	向量搜索
DNA 分类	分类	向量搜索
文本搜索引擎	语义搜索	向量搜索
通过文本搜索图像	语义搜索	向量搜索
图像去重	重复数据删除	向量搜索
使用 Milvus 构建图形 RAG	RAG	图搜索
使用 Milvus 进行上下文检索	快速入门	向量搜索
使用 Milvus 进行 HDBSCAN 聚类	快速入门	向量搜索
使用 ColPali 实现多模态检索	快速入门	向量搜索
向量可视化	快速入门	向量搜索
基于 Milvus 的电影推荐	推荐系统	向量搜索
使用 Matryoshka 嵌入进行漏斗搜索	快速入门	向量搜索

5.2 典型应用场景

README 给出了三个官方 Demo 场景：

• 以图搜图系统：从海量图片中快速检索最相似图片；
• 智能问答机器人：交互式智能问答机器人帮助用户节省时间和用人成本；
• 分子式检索系统：迅速检索相似化学分子式。

此外，官方训练营（Milvus Bootcamp）可用于系统学习向量数据库操作与性能测评。仓库中的测试目录 tests/ 也按客户端语言组织了配套用例（tests/go_client/、tests/python_client/、tests/restful_client/、tests/restful_client_v2/），可作为各语言接入方式的活文档。

六、SDK 生态

README 列出的官方 SDK 矩阵为：PyMilvus、Java SDK、Go SDK、Cpp SDK、Node SDK。值得强调的是，当前仓库已将 Go SDK 内嵌为一级目录 client/（模块 github.com/milvus-io/milvus/client/v3，见 client/go.mod），其结构包括：

• client/milvusclient/：面向用户的完整客户端 API（集合/分区/索引/读写/RBAC/数据库/资源组/迭代器/快照/遥测等）；
• client/column/ 与 client/entity/：列式数据与 Schema 实体定义（向量、稀疏向量、几何、JSON、数组、动态字段等，见 client/entity/field.go）；
• client/index/：各 ANN 索引参数的类型安全封装（HNSW、IVF、DiskANN、GPU 索引、SCANN、MinHash、稀疏索引等，如 client/index/hnsw.go、client/index/disk_ann.go、client/index/gpu.go）；
• client/bulkwriter/：批量导入工具。

另外，Attu 提供了图形化界面，用于管理数据与 Milvus 集群。

七、贡献代码、文档与社区

• 贡献流程：欢迎向社区贡献代码，代码贡献流程、提交补丁等信息详见 CONTRIBUTING.md；开发者环境搭建与测试运行（单测、覆盖率、E2E、pre-submission verification）见 DEVELOPMENT.md。
• 文档体系：仓库内另有 docs/ 目录，包含 docs/agent_guides/（可观测性、流式系统指南）、docs/design-docs/（约百篇设计文档）、docs/dev/（错误处理规范与案例手册）等，是深入架构细节的可靠入口。
• 社区渠道：README 提到可通过 Slack 频道、官方 FAQ、邮件列表（TSC / 技术讨论 / 公告）以及知乎、CSDN、Bilibili、Medium、Twitter、YouTube 等社交媒体渠道交流（具体入口以官方文档站为准）。
• 分支约定：README 提示主分支为 v2.0 代码开发分支，Milvus 1.0 可切换到 1.0 分支使用；当前仓库代码已演进到 v3 模块路径，跨分支开发需注意 Conan 1.x/2.x 差异（DEVELOPMENT.md 给出了同机共存的双版本方案）。

八、论文引用

如需在研究论文中引用 Milvus，README 给出的 BibTeX 为（SIGMOD 2021）：

@inproceedings{2021milvus,
  title={Milvus: A Purpose-Built Vector Data Management System},
  author={Wang, Jianguo and Yi, Xiaomeng and Guo, Rentong and Jin, Hai and Xu, Peng and Li, Shengjun and Wang, Xiangyu and Guo, Xiangzhou and Li, Chengming and Xu, Xiaohai and others},
  booktitle={Proceedings of the 2021 International Conference on Management of Data},
  pages={2614--2627},
  year={2021}
}

九、致谢与核心依赖

Milvus 采用了以下关键依赖库（README"特别感谢"一节）：

依赖	角色	仓库中的踪迹
FAISS	相似性检索库	由 C++ 核心库 internal/core/ 及 Conan 依赖管理集成
etcd	开源键值存储（元存储）	internal/kv/etcd/、pkg/kv/、configs/advanced/etcd.yaml
Pulsar	分布式发布/订阅平台	internal/kv/ 消息队列抽象与 pkg/mq/（当前版本同时支持 RocksMQ 等 WAL 实现，见 cmd/roles/roles.go 的 stopRocksmqIfUsed）
RocksDB	存储引擎	internal/kv/ 相关本地 KV 实现

十、小结：如何继续阅读本仓库

基于本文建立的脉络，推荐的深入路径是：

1. 部署与配置：从 docker-compose.yml 与 configs/milvus.yaml 起步，理解单机/集群两种形态的参数差异；
2. 进程与角色：读 cmd/main.go → cmd/roles/roles.go → cmd/components/，掌握组件启动、就绪等待与优雅停机的完整生命周期；
3. 数据链路：按 internal/streamingnode/（流式写入）→ internal/datanode/（落盘与索引）→ internal/querynodev2/（查询）的顺序理解读写路径；
4. 客户端 API：以 client/milvusclient/ 为参照，对照 client/index/ 中的索引参数封装，理解各 ANN 索引的可配置项；
5. 架构演进：查阅 docs/design-docs/ 中的设计文档与 milvus20vs1x.md 中对 2.0 相对 1.x 的功能与性能变化说明。

以上所有引用文件均可在当前仓库中直接检索验证，读者可据此在本地完成"阅读配置—编译二进制—Docker 部署—客户端接入—架构走读"的完整闭环。