Chapter 7.2 Milvus 3.0:外部集合与快照(实战)
7.2.0 这一章干什么
先看两个真实场面。
场面一。 RAG 系统上线半年,向量表几千万行。商品数据本来就在湖里(S3 / HDFS),向量也是离线算好写回湖里的;为了检索,还得再 ETL 一份进 Milvus——两份存储、两套权限,湖里更新了还得等同步任务。
场面二。 运营批量改了 20 万条标签,或者模型升级回填时脚本写错了字段,第二天搜索全乱。想回到昨天,手里只有全量备份,重导几个小时,业务停着等。
3.0 的两个功能,正好对着这两个场面:
- 外部 Collection:湖上的文件不搬,Milvus 直接在文件上建索引、做检索。数据主副本还在湖里,Milvus 只当查询层。
- 快照:给集合拍一个时间点。出事了恢复成一个新集合,秒级到分钟级。
参考文档:创建外部 Collection · 管理快照 · 存储 V3
7.2.1 动手之前:MySQL、Redis、ES、MongoDB 能直接接吗?
不能直接接。Milvus 3.0 的外部 Collection 没有任何 OLTP 数据库连接器。
按常见数据源对照:
| 你的数据在哪 | 能否直接建外部 Collection | 实际做法 |
|---|---|---|
| MySQL | ❌ | 导出/CDC 成 Parquet 或 Iceberg 表,落到对象存储再做 |
| Redis | ❌ | 本身是 KV 内存库,没有列式文件层;先导出成 Parquet |
| Elasticsearch | ❌ | 用快照/scroll 导出成 Parquet 或 JSON 再转列式 |
| MongoDB | ❌ | 导出 BSON 转 Parquet |
| Hive / Spark 的 Parquet 目录 | ✅ | format: parquet,external_source 指向目录或桶前缀 |
| Iceberg 表 | ✅ | format: iceberg-table,指向 metadata JSON |
| Delta Lake | ❌ | 官方支持清单里没有,转 Iceberg 或导出 Parquet |
| Hudi | ❌ | 同上 |
| Lance | ✅ | format: lance-table |
为什么不做直连?一句话:Milvus 的读路径是列式扫描加向量索引,要求文件可分片、可随机读、按列解码 ;OLTP 库的存储引擎不提供这种访问形态。直连还意味着连接池、事务、权限、限流全要进 Milvus 内核。
所以 MySQL 数据进 Milvus 的路径是:MySQL → 导出 → Parquet / Iceberg → 外部 Collection。本章实操从 Parquet 开始,就是这条路的最后一段。
参考文档:创建外部 Collection · 存储 V3
下面开始动手。先把这一趟要完成的事说清楚:把一份放在 MinIO 上的 Parquet 商品表,变成 Milvus 里一个能 query、能 search 的集合,并且湖上文件变了以后也能跟上;最后再学会出事时回滚。 一共六步,每步一节:
| 步骤 | 做什么 | 做完之后 |
|---|---|---|
| 7.2.2 | 把 Parquet 传进 MinIO,顺手避开 MinIO 版本的坑 | 湖上有一份可读的文件 |
| 7.2.3 | 建外部 Collection:告诉 Milvus 文件在哪、字段怎么对应 | 集合有了 schema,但还查不了 |
| 7.2.4 | 建索引、刷新、加载 | 集合进入可检索状态 |
| 7.2.5 | 查询与检索:查三条、搜一次 | 看到结果,确认集合真的能用 |
| 7.2.6 | 湖上数据更新了,refresh 怎么生效 | 知道改数据后要做什么、有什么副作用 |
| 7.2.7 | 湖上加了一列,在线加字段 | 不重建集合就能跟上 schema 变化 |
| 7.2.8 | 集合被改坏了,用快照回滚(换一个场景) | 恢复到任意一次拍快照的时间点 |
前五步把外部集合搭好、查通、改明白;第六步练回滚——快照只有「拍、改、恢复」三步。
7.2.2 准备环境:MinIO 里放一份 Parquet
问题: 文件在湖上,Milvus 怎么读到它?先把存储和文件准备好。
先查 MinIO 镜像版本。 官方 3.0 的 standalone compose 用的是 milvusdb/minio:RELEASE.2024-12-18T13-15-44Z;
沿用 2.x 的 minio/minio:RELEASE.2023-03-20T20-16-18Z 会让刷新失败,报 HTTP 411 MissingContentLength(旧 MinIO 不接受 Loon 的上传方式)。
改 compose 里 minio 的 tag,docker compose up -d,数据卷不用动。
造一份数据。 1000 行商品,8 维向量——维度压到 8 只是为了让 demo 跑得快、输出短,真实项目一般是 768 或 1024 维。
import numpy as np
import pyarrow as pa
import pyarrow.parquet as pq
rng = np.random.default_rng(42)
N, DIM = 1000, 8
ids = np.arange(1, N + 1)
names = [f"product_{i:04d}" for i in ids]
cats = rng.choice(["phone", "laptop", "headphone", "camera", "watch"], size=N)
price = np.round(rng.uniform(10, 1000, size=N), 2)
emb = rng.standard_normal((N, DIM)).astype(np.float32)
tbl = pa.table({
"id": pa.array(ids),
"name": pa.array(names),
"category": pa.array(cats),
"price": pa.array(price),
"embedding": pa.array(emb.tolist(), pa.list_(pa.float32(), DIM)),
})
pq.write_table(tbl, "products_v1.parquet", compression="snappy")
print("rows:", tbl.num_rows)传上 MinIO。
import boto3
s3 = boto3.client(
"s3",
endpoint_url="http://localhost:9000",
aws_access_key_id="minioadmin",
aws_secret_access_key="minioadmin",
region_name="us-east-1",
config=boto3.session.Config(
signature_version="s3v4",
s3={"addressing_style": "path"},
),
)
s3.create_bucket(Bucket="lake-demo")
s3.upload_file("products_v1.parquet", "lake-demo", "products/products_v1.parquet")
print([o["Key"] for o in s3.list_objects_v2(Bucket="lake-demo", Prefix="products/")["Contents"]])验证:打开 http://localhost:9001(minioadmin / minioadmin),lake-demo/products/ 下应该有一个 64KB 左右的 parquet 文件。
7.2.3 第 1 步:建外部 Collection
问题: 文件有了,怎么让 Milvus 把它认成一个 Collection?答:建 schema,把 Milvus 字段逐个映射到文件列。
先准备 external_spec:格式、认证、endpoint。
import json
from pymilvus import MilvusClient, DataType
EXT_SOURCE = "s3://lake-demo/products/"
EXT_SPEC = json.dumps({
"format": "parquet",
"extfs": {
"access_key_id": "minioadmin",
"access_key_value": "minioadmin",
"region": "us-east-1",
"cloud_provider": "aws",
"endpoint_url": "http://minio:9000",
"use_ssl": "false",
"use_virtual_host": "false",
},
})三个要点:
endpoint_url要写 Milvus 容器能访问到的地址。compose 网络里是http://minio:9000;写localhost:9000,在 Milvus 容器里指向的是它自己,连接必然失败。endpoint_url是 v3.0.2 才加的参数。发布说明原文:「Added support for custom S3-compatible endpoints in external collections via the extfs.endpoint_url option」。v3.0.1 及更早只能连 AWS S3。use_virtual_host: false是 path-style 寻址,MinIO 必须这样。
然后建 schema、加字段:
schema = MilvusClient.create_schema(external_source=EXT_SOURCE, external_spec=EXT_SPEC)
schema.add_field("id", DataType.INT64, external_field="id")
schema.add_field("name", DataType.VARCHAR, max_length=256, external_field="name")
schema.add_field("category", DataType.VARCHAR, max_length=64, external_field="category")
schema.add_field("price", DataType.DOUBLE, external_field="price")
schema.add_field("embedding", DataType.FLOAT_VECTOR, dim=8, external_field="embedding")
client = MilvusClient(uri="http://localhost:19530", token="root:Milvus")
client.create_collection("products_ext", schema=schema)坑 1:不要声明主键。 按普通集合的习惯写 is_primary=True,服务端直接拒绝:
external collection products_ext does not support user-defined primary key field id: invalid parameter外部集合的主键由 Milvus 自动生成,describe_collection 里能看到:
__virtual_pk__ INT64 auto_id=True
description: auto-generated primary key for external collection它每次刷新都会重新分配(7.2.6 验证),所以别把它存进业务库。
坑 2:字段一律可空,空值不补、也不参与比较过滤。
describe_collection 里每个映射字段都是 nullable: true,湖上文件这一列允许为空,Milvus 不会因为空值拒绝文件,也不会补默认值——文件里是空,查出来就是空(None)。
实测一份 3 行数据(第 2 行 price 为 null):
| 查询 | 返回 |
|---|---|
id == 2 | 该行 price: None |
price > 0 或 price >= 0 | 只返回 1、3 两行——空值不参与比较 |
price is null | 返回第 2 行 |
所以空值不会命中普通的比较条件,要专门查它得用 is null。数据质量还是要在湖上管,Milvus 不兜底。
7.2.4 第 2 步:建索引、刷新、加载
问题: 集合建好了,但此刻 Milvus 既不知道数据在哪,也没有索引,更没有加载。
外部集合和托管集合一样要建索引;但多了「刷新」这个动作:Milvus 得去湖上把文件清单扫一遍,才知道数据在哪。
# 1) 建索引
idx = client.prepare_index_params()
idx.add_index(field_name="embedding", index_type="AUTOINDEX", metric_type="L2")
client.create_index("products_ext", index_params=idx)
# 2) 刷新:提交作业,轮询状态
job_id = client.refresh_external_collection(
"products_ext", external_source=EXT_SOURCE, external_spec=EXT_SPEC)
print("job_id:", job_id)
import time
while True:
job = [j for j in client.list_refresh_external_collection_jobs()
if str(j.job_id) == str(job_id)][0]
print(job.state, job.progress)
if "Completed" in str(job.state) or "Failed" in str(job.state):
break
time.sleep(2)
# 3) 加载
client.load_collection("products_ext")
print(client.get_collection_stats("products_ext"))7.2.5 第 3 步:查询与检索
问题: 集合建好、也 load 了,到底能不能查?先查一条标量,再搜一次向量,看到结果就说明通了。
先按分类查三条:
rows = client.query(
"products_ext",
filter="category == 'phone'",
output_fields=["id", "name", "price"],
limit=3,
)
for r in rows:
print(r)输出:
{'id': 1, 'name': 'product_0001', 'price': 739.34}
{'id': 7, 'name': 'product_0007', 'price': 321.31}
{'id': 10, 'name': 'product_0010', 'price': 124.7}再拿一个 8 维向量搜一次:
res = client.search(
collection_name="products_ext",
data=[[0.05, -0.02, 0.11, 0.03, -0.08, 0.07, 0.01, -0.04]],
anns_field="embedding",
limit=3,
output_fields=["id", "name"],
)
for h in res[0]:
print(h["entity"]["id"], h["entity"]["name"], round(h["distance"], 4))输出:
874 product_0874 0.7404
202 product_0202 0.7613
927 product_0927 0.7614三条结果、按距离从小到大——向量检索确实在用湖上的数据跑。distance 的含义取决于建索引时的 metric_type(这里 L2,越小越近);换成 COSINE/IP 数值含义不同,7.3 再展开。检索同样支持 filter,过滤在服务端、召回前完成。
到这里,外部集合就能用了:数据留在湖上,Milvus 里能查、能搜。
7.2.6 第 4 步:湖上数据更新了——refresh 到底做了什么
问题: 湖上的文件改了,Milvus 会自己跟上吗?不会。湖和 Milvus 之间只有一个同步动作:你手动调用的 refresh_external_collection。它做的事只有一件——把 external_source 前缀下的文件重新扫一遍,重建「Milvus 字段 → 文件」的映射。
| 你在湖上做的操作 | refresh 之后的结果 |
|---|---|
| 同一前缀放 v1、v2 两份文件 | count(*) = 2000;id == 1 查出两行,price 分别是 739.34 和 1.23 |
| 删掉 v1、只留 v2,再刷新 | 回到 1000 行,id == 1 的 price 变成 1.23 |
| 只删文件、不加新文件 | 作业被拒 |
| 新文件缺了集合映射的某列 | RefreshFailed,reason 写明 Column 'discount' not found |
| 每次刷新 | __virtual_pk__ 全部重新分配 |
还有一个与数据无关的坑:刷新完要重新 load。我们遇到过刷新完成、get_collection_stats 已经是 2000,查询却还返回旧数据——查询节点上加载的还是旧分段;release_collection + load_collection 之后才看到新数据。所以刷新脚本固定三步:refresh → 轮询到完成 → release + load。
最后,外部集合只读。实测 insert 与 delete 都被拒绝:
insert operation is not supported for external collection products_ext: invalid parameter
delete operation is not supported for external collection products_ext: invalid parameter要改数据,回湖上改,再刷新。
7.2.7 第 5 步:湖上多了列——在线加字段
问题: 运营要上线促销专区。数据团队在湖上的商品表里加了一列 discount,存的是折后价——比如原价 100 元、打九折,discount 就是 90。业务要按「折后价 < 500」筛商品。
可集合是照着旧文件建的,Milvus 里根本没有 discount 这个字段,拿它过滤会直接报字段不存在。重建集合得把全量数据重新映射一遍,期间不可查;轻一点的办法是——给集合在线加一个字段映射到这列,再 refresh。
client.add_collection_field(
"products_ext",
field_name="discount",
data_type=DataType.DOUBLE,
nullable=True, # 必须写
external_field="discount",
)坑:不写 nullable=True 必失败。 服务端报:
added field must be nullable, please check it, field name = discount: invalid parameterpymilvus 的 add_collection_field 默认 nullable=False,而官方文档示例没写这个参数——照抄会挂。
加完字段必须刷新,否则查询看不到它。刷新后 query(output_fields=["id", "price", "discount"]) 就能查到折后价,数值与湖上文件一致。
限制(官方规定):
- 只能加字段;不能删字段、改名、改类型、改向量维度、改
external_field映射; - 新增的
SPARSE_FLOAT_VECTOR和StructArray类型不支持后加; - 加字段只是「映射」,不回填源数据——文件里没有这一列,查出来就是空。
7.2.8 第 6 步:快照
问题: 同事误跑脚本,把集合批量改坏了,业务要的是「十分钟前的样子」。全量备份重导要几个小时,快照是分钟级——前提是那之前你拍过快照。这一节用一个 200 行的托管集合,把「拍 → 改坏 → 恢复」完整走一遍。
先看流程:
import numpy as np
from pymilvus import DataType
schema = client.create_schema(auto_id=False)
schema.add_field("id", DataType.INT64, is_primary=True)
schema.add_field("name", DataType.VARCHAR, max_length=64)
schema.add_field("embedding", DataType.FLOAT_VECTOR, dim=8)
client.create_collection("products_managed", schema=schema)
client.insert("products_managed", [
{"id": i, "name": f"m_{i}", "embedding": np.random.rand(8).astype(np.float32).tolist()}
for i in range(1, 201)
])
idx = client.prepare_index_params()
idx.add_index(field_name="embedding", index_type="AUTOINDEX", metric_type="L2")
client.create_index("products_managed", index_params=idx)
client.load_collection("products_managed")第 1 步,flush。 这一步不是可选项,原因见下面最大的坑。
client.flush("products_managed")第 2 步,拍快照。
client.create_snapshot(
snapshot_name="snap_v1",
collection_name="products_managed",
description="before bulk update",
)
print(client.list_snapshots(collection_name="products_managed"))
info = client.describe_snapshot("snap_v1", "products_managed")
print(info.id, info.create_ts)
print(info.s3_location)s3_location 指向 Milvus 自己的桶,实测:
minio://minio:9000/a-bucket/files/snapshots/470109138426097566/metadata/470109138426298602.json快照文件不在你的业务桶里,它引用已有数据文件和清单,不复制数据——这也是它快的原因。
第 3 步,制造事故。 插 50 行、删 30 行:
client.insert("products_managed", [
{"id": i, "name": f"m_{i}", "embedding": np.random.rand(8).astype(np.float32).tolist()}
for i in range(1001, 1051)
])
client.delete("products_managed", filter="id <= 30")
client.flush("products_managed")
print(client.query("products_managed", filter="", output_fields=["count(*)"]))源集合变成 220 行。
第 4 步,恢复成一个新集合。
job_id = client.restore_snapshot(
"snap_v1",
source_collection_name="products_managed",
target_collection_name="products_restored",
)
while True:
st = client.get_restore_snapshot_state(job_id=job_id)
print(st.state, st.progress)
if "Completed" in str(st.state) or "Failed" in str(st.state):
break
time.sleep(2)实测输出:
restore: RestoreSnapshotPending progress: 0
restore: RestoreSnapshotExecuting progress: 0
restore: RestoreSnapshotCompleted progress: 100
restored count: 200
id == 1001(快照后才插入): []products_restored 是 200 行——正是拍快照那一刻的数字;快照之后插入的 1001–1050 查不到;快照之后删掉的 1–30 还在。时间点精确到那一次 flush。
最大的坑:不 flush 直接拍,恢复出来是 0 行。
我们第一次跑的时候没 flush,快照建的时候集合统计还是 row_count: 0——数据还在 growing segment,没落盘成可引用的 segment。恢复出来的新集合 schema 正确、索引正确,数据是 0 行。flush 之后重跑,200 行精确恢复。
官方建议原话:「在创建快照之前,建议您停止向目标 Collection 写入数据,并调用 flush() 方法,以避免可能的数据丢失」——它不止是「避免丢失」,是快照到底拍没拍到的问题。
恢复的三个要点:
恢复是异步作业:轮询到
Completed才能查,别拍完就查;恢复产出的是新集合,不是原地回滚。
restore_snapshot不会把products_managed改回 200 行——它新建了一个products_restored,装的是快照那一刻的数据;原来的products_managed一行没动,还是被改坏的 220 行。想让业务用回旧数据,得让应用改连新集合:pythonCOLLECTION = "products_managed" # 出事前,应用连的是它 COLLECTION = "products_restored" # 恢复后,改连新集合快照不是永久的,默认会被后台垃圾回收(GC)清掉。Milvus 后台会定期删除没人引用的数据,快照也在其中——如果你只是拍了就走,过一阵真出事时可能发现快照已经没了:
pythonpin_id = client.pin_snapshot_data( snapshot_name="snap_v1", collection_name="products_managed", ttl_seconds=7 * 24 * 3600, # 保护 7 天;0 表示用服务端默认值 )钉住期间 GC 不会碰这个快照,到期后自动解除保护、重新变成可回收状态。不再需要时,先解除钉住、再删除,空间立刻释放,不用等 GC:
pythonclient.unpin_snapshot_data(pin_id=pin_id) # 先解除钉住 client.drop_snapshot("snap_v1", collection_name="products_managed")顺序不能反:钉住的快照直接 drop 会报错,实测原文:
active pins exist, unpin before dropping: snapshot is pinned[snapshot=snap_v1]所以
pin_id要存下来——它只在 pin 的那一刻返回,丢了就只能等 TTL 到期。
一句话记住分工:快照适合几天到几周的快速回滚和测试,长期容灾用独立的备份工具(Milvus Backup),别把快照当备份。
7.2.9 小结
- 外部 Collection 只认文件/表格式。MySQL、Redis、ES、MongoDB 一律先落湖。
- 建集合的流程:
create_schema→add_field→create_collection→create_index→refresh+load。 - refresh 是手动、全量、文件级的:同前缀多文件不去重;前缀下文件的 schema 必须一致,缺列会让刷新整体失败。
- 加列用
add_collection_field,加完再 refresh;只能加,不能删改。字段一律可空:空值原样返回、不参与比较,要查空值用is null。 - 快照先 flush 再拍,不 flush 会拍到 0 行;恢复是异步作业、产出的是新集合,业务要自己切集合名。
- 快照不是备份:会被后台 GC 回收,长期保留要
pin_snapshot_data;删除前先unpin_snapshot_data再drop_snapshot;长期容灾用 Milvus Backup。
参考文档:创建外部 Collection · 修改外部集合 Schema · 管理快照 · 快照用例 · 存储 V3
下一章把 Collection 本身的能力往前推:Schema 在线改、多向量、TEXT 长文本,以及把排序、聚合、分面、重排塞进一次搜索请求。