⚠️ Alpha内测版本警告:此为早期内部构建版本,尚不完整且可能存在错误,欢迎大家提Issue反馈问题或建议。
Skip to content

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 维。

python
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。

python
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。

python
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、加字段:

python
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 得去湖上把文件清单扫一遍,才知道数据在哪。

python
# 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 了,到底能不能查?先查一条标量,再搜一次向量,看到结果就说明通了。

先按分类查三条:

python
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 维向量搜一次:

python
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。

python
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 parameter

pymilvus 的 add_collection_field 默认 nullable=False,而官方文档示例没写这个参数——照抄会挂。

加完字段必须刷新,否则查询看不到它。刷新后 query(output_fields=["id", "price", "discount"]) 就能查到折后价,数值与湖上文件一致。

限制(官方规定):

  • 只能加字段;不能删字段、改名、改类型、改向量维度、改 external_field 映射;
  • 新增的 SPARSE_FLOAT_VECTOR 和 StructArray 类型不支持后加;
  • 加字段只是「映射」,不回填源数据——文件里没有这一列,查出来就是空。

7.2.8 第 6 步:快照 ​

问题: 同事误跑脚本,把集合批量改坏了,业务要的是「十分钟前的样子」。全量备份重导要几个小时,快照是分钟级——前提是那之前你拍过快照。这一节用一个 200 行的托管集合,把「拍 → 改坏 → 恢复」完整走一遍。

先看流程:

python
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。 这一步不是可选项,原因见下面最大的坑。

python
client.flush("products_managed")

第 2 步,拍快照。

python
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 行:

python
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 步,恢复成一个新集合。

python
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 行。想让业务用回旧数据,得让应用改连新集合:

    python
    COLLECTION = "products_managed"     # 出事前,应用连的是它
    COLLECTION = "products_restored"    # 恢复后,改连新集合
  • 快照不是永久的,默认会被后台垃圾回收(GC)清掉。Milvus 后台会定期删除没人引用的数据,快照也在其中——如果你只是拍了就走,过一阵真出事时可能发现快照已经没了:

    python
    pin_id = client.pin_snapshot_data(
        snapshot_name="snap_v1",
        collection_name="products_managed",
        ttl_seconds=7 * 24 * 3600,   # 保护 7 天;0 表示用服务端默认值
    )

    钉住期间 GC 不会碰这个快照,到期后自动解除保护、重新变成可回收状态。不再需要时,先解除钉住、再删除,空间立刻释放,不用等 GC:

    python
    client.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 长文本,以及把排序、聚合、分面、重排塞进一次搜索请求。

下一章:7.3 Milvus 3.0 数据模型与检索增强