核心概念：Milvus 的词汇表

这一章是词汇表，不是 API 手册。每个概念按同一套结构讲：一句话定义 → 为什么需要它 → 比文档深一层的机制 → 一个带边界的类比。代码片段只用来让概念落地，未在本机运行，按概念读、不必照抄。

1.1Collection、Schema、Entity

Collection 是 Milvus 里的一张表——一组共享同一 schema 的 entity 的集合。

比文档深一层的机制：Collection 本身只是元数据——schema 加配置，存在 etcd 里，不存一行数据。真正的数据被切成 segment 散落在对象存储，Collection 只是“把这些 segment 认作同一张表”的逻辑名义。所以建一个 Collection 几乎零成本（写一条元数据而已）；往里写数据才触发 segment 分配、WAL 写入、异步建索引这一整套。这一点解释了一个常见困惑：建好 collection 立刻去查为什么是空的——因为 collection 的“存在”和数据的“存在”是两件事。

一个 entity 长什么样

一个 entity（一行）= 一个主键 + 一个或多个向量字段 + 任意标量字段。向量字段的类型不止 float32：

主键可以设 AutoID 自动生成。一个容易栽跟头的细节：自动生成的是 snowflake 风格的大整数（按时间戳派生），不是 1、2、3 递增——别在代码里假设主键连续。动态字段（$meta）让你在固定 schema 之外塞任意 JSON key，代价是这些字段上的过滤不如显式定义的字段高效。

# MilvusClient 是 2.4+ 的统一入口；旧的 ORM 风格 Collection() 已被取代
from pymilvus import MilvusClient, DataType

client = MilvusClient(uri="http://localhost:19530")

schema = client.create_schema(auto_id=True, enable_dynamic_field=True)
schema.add_field("pk", DataType.INT64, is_primary=True)        # 主键：snowflake 大整数
schema.add_field("vector", DataType.FLOAT_VECTOR, dim=768)     # 稠密向量字段
schema.add_field("tenant", DataType.VARCHAR, max_length=64)    # 标量：可过滤、可做 partition key

client.create_collection("docs", schema=schema)   # 只写一条元数据到 etcd，几乎零成本

与下一个概念的关系：一张 collection 的数据可以再切分。切分有两个完全不同的维度——一个为了查询裁剪（partition），一个为了写入并行（shard）。下面两节分别讲，它们正交、且最常被混为一谈。

1.2Partition 与 Partition Key

Partition 是 Collection 内部按业务维度切出的逻辑子集，查询时可只扫相关 partition。

比文档深一层的机制：partition 不是另建一张表，而是给 segment 打上 partition 归属标签——一个 partition 拥有自己的一组 segment。查询若指定 partition，调度器直接不把其他 partition 的 segment 派给 query node 去搜。Partition Key 是它的自动版：指定某个标量字段为 partition key，Milvus 用它的哈希把 entity 自动路由到固定数量的 partition，省去手动建和选 partition。

与下一个概念的关系：partition 是“逻辑上把数据分组、给查询裁剪用”；下一个概念 shard 是“物理上把写入分流、给吞吐用”。两者正交——这是本章最重要的一组对照。

1.3Shard：与 Partition 正交的另一条轴

Shard 是 Collection 的水平写入分片，按主键哈希决定一条数据进哪个 shard，建表时定死、之后不可改。

比文档深一层的机制：每个 shard 绑定一个 vchannel（逻辑写入流），vchannel 映射到底层 WAL 的 pchannel。一条 insert 先按 hash(主键) 选 shard → 进对应 vchannel → 落 WAL。所以 shard 数 = 写入并行度，建表时设定且事后难改，因为它绑定了底层日志流的分区，改 shard 数等于重排所有数据所属的日志流。

图 1.2 把这两条轴画成正交的二维网格：一条数据同时落在“某个 shard”（主键哈希决定）和“某个 partition”（业务字段决定）的交叉格里。

1.4Segment：数据真正的物理单元

Segment 是 Milvus 真正存数据的物理单元——一批 entity 的不可变文件，有 growing → sealed → indexed 的生命周期。

比文档深一层的机制：写入先进 growing segment（驻留在流式节点，可持续追加，此时查询只能暴力扫描它）；达到大小或时间阈值后 sealed（密封、只读）；sealed 段被 data node 持久化成 binlog 落对象存储（flushed）；随后异步建向量索引（indexed）。删除不是原地改，而是写一条 tombstone 到 delta binlog，查询时把被删的过滤掉，空间要等 compaction 才回收。这一整套就是“segment 是统一调度单元”的含义——存储、索引、查询、负载均衡、节点间搬运，全部以 segment 为粒度。

1.5Flush

Flush 是把当前 growing segment 立即密封、并触发持久化的操作。

比文档深一层的机制：flush 不等于“数据现在才安全”——数据在落 WAL 那一刻就已经持久（事实源是日志，02 章详述）。flush 真正做的是提前触发 growing → sealed → flushed 这步状态转换，把内存里的增量固化成 binlog。理解这点能避开一个真实的失败模式：手动 flush 过频会制造大量小 segment，反而加重后续 compaction 和查询时的段扇出开销。

1.6Index 与 Metric Type

Index 是建在向量字段上、加速 ANN 检索的结构；Metric Type 是衡量两个向量“多近”的距离函数。

比文档深一层的机制：索引是每个 sealed segment 各建一份，不是整个 collection 一份（呼应 §1.1 的“没有整表大索引”）。所以一次检索其实是“在每个相关 segment 上各跑一次索引检索，再把各段的 top-k 合并”——这条在 04 章会展开成完整读路径。这里只需记住一条硬约束：向量类型 + 索引类型 + 度量类型三者必须相容（例如 GPU 索引不支持 COSINE，要先归一化再用 IP）。索引内部怎么工作，留到 03 章。

与下一个概念的关系：索引决定“查得多快、多准”；下一个概念一致性级别决定“查得多新”。两者是检索质量的两个独立旋钮。

1.7Consistency Level

一致性级别决定一次检索能看到多新的数据，Milvus 提供 Strong / Bounded / Session / Eventually 四档。

比文档深一层的机制：每条写入带一个 TSO 时间戳；每次检索带一个 guarantee timestamp，要求“看到所有 ≤ 该时刻的数据”。Strong 用最新时刻（等待对齐，最慢）；Bounded 用一个略旧的容忍窗口（默认）；Session 保证看到自己这个 client 的写入；Eventually 不等待，最快。时间戳怎么发、guarantee ts 怎么卡，是 04 章的内容。

# 检索时显式指定一致性级别；不指定则用 collection 的默认（Bounded）
res = client.search(
    collection_name="docs",
    data=[query_vector],
    limit=10,
    filter='tenant == "acme"',          # 标量过滤，配合 partition key 可触发裁剪
    search_params={"metric_type": "COSINE", "params": {"ef": 64}},  # ef 是查询旋钮(03 章)
    consistency_level="Session",        # 想要 read-your-writes 就用 Session，不是默认
)