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

Chapter 7.3 Milvus 3.0:数据模型与检索增强(实战) ​

7.3.0 两个真实场景 ​

场景一。 用户在耳机商城搜「降噪耳机」。产品的要求是:最像的排前面,最近上架的要提前,卖得好的也要提前。向量检索只按相似度排——一条两年前上架、早该下架的老款,只要向量最像,就永远占着第一。过去只能把候选拉回应用层,自己算「上架多少天」「热度多少」,自己写加权和排序:多一次往返,多一段代码。

场景二。 换嵌入模型。300 万条商品向量要按新模型重算,可集合里没有地方放新向量,只能建新集合、全量重导——一周的迁移窗口,期间还要双写。

3.0 对这两个场景各给了一样东西:

  1. Function Chain(函数链):把「改分数 → 排序 → 截断」声明成一条有顺序、带类型的处理链,作为一次搜索请求的一部分执行,对搜索得到的结果做后处理,所有操作都在Milvus内部完成。官方发布说明管它叫 Function Chain reranking,列的能力是「分数变换与合成、基于模型的重排、排序、候选裁剪」,并特别强调 without client-side orchestration——不需要客户端在中间编排。
  2. 多向量列 + 部分更新:一个集合里存两套向量,换模型只回填新的一列,查询时改一个字段名。

C++ API 文档对它的定义划清了数据的处理边界:

This class builds a function chain that post-processes search results. A function chain runs a pipeline of operations (map, sort, limit, …) on the result columns of a Search call.

翻译:这个类用来构造一条给搜索结果做后处理的函数链;一条链就是在一次 Search 调用的结果列上,依次执行 map、sort、limit 这些操作。 两个要点:链是声明出去、由服务端执行的;它处理的是结果行(result columns),不是集合里的数据。

下面用一个 12 条耳机 的小商品库来解决这两个场景所对应的问题。

7.3.1 准备:12 条耳机的数据 ​

12 条商品,字段就是业务里常见的那些:名字、价格、上架天数、热度(0~1 的销量分),再加两列向量 vec_v1(老模型)、vec_v2(新模型)。

向量怎么造的:先随机生成一个查询向量 q,每条商品的向量 = q + 一个扰动值,扰动越大越不像。相似度高低也是预先设计好的,排名结果可以肉眼核对,这是为了快速方便的演示效果。

python
import numpy as np
from pymilvus import MilvusClient, DataType, FunctionChain, FunctionChainStage
from pymilvus.function_chain import col, fn

client = MilvusClient(uri="http://localhost:19530", token="root:Milvus")
C = "headphones"
if client.has_collection(C):
    client.drop_collection(C)

rng = np.random.default_rng(1)
q = rng.standard_normal(8).astype(np.float32)
items = [
    ("索尼 WH-1000XM5", 1999, 60, 0.95, 0.05),
    ("苹果 AirPods Max", 4399, 45, 0.80, 0.15),
    ("小米 降噪耳机 4 Pro", 699, 2, 0.30, 0.30),
    ("华为 FreeBuds Pro 3", 1099, 7, 0.60, 0.35),
    ("索尼 WF-1000XM5", 1899, 120, 0.85, 0.45),
    ("苹果 AirPods Pro 2", 1899, 3, 0.90, 0.55),
    ("小米 Redmi Buds 5", 199, 200, 0.70, 0.60),
    ("漫步者 NeoBuds Pro", 499, 1, 0.10, 0.65),
    ("华为 FreeBuds SE 2", 299, 90, 0.40, 0.70),
    ("三星 Galaxy Buds3", 999, 15, 0.55, 0.75),
    ("索尼 WH-CH720N", 899, 30, 0.45, 0.80),
    ("击音 入门耳机", 89, 5, 0.05, 0.90),
]
rows = []
for i, (name, price, days, pop, d) in enumerate(items, start=1):
    u = rng.standard_normal(8)
    u /= np.linalg.norm(u)
    rows.append({"id": i, "name": name, "price": price, "days_ago": days,
                 "popularity": pop,
                 "vec_v1": (q + d * u).astype(np.float32).tolist(),
                 "vec_v2": (q + ((i * 7) % 12 + 1) * 0.08 * u).astype(np.float32).tolist()})

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("price", DataType.DOUBLE)
schema.add_field("days_ago", DataType.INT64)
schema.add_field("popularity", DataType.DOUBLE)
schema.add_field("vec_v1", DataType.FLOAT_VECTOR, dim=8)
schema.add_field("vec_v2", DataType.FLOAT_VECTOR, dim=8)

ip = client.prepare_index_params()
ip.add_index(field_name="vec_v1", index_type="AUTOINDEX", metric_type="COSINE")
ip.add_index(field_name="vec_v2", index_type="AUTOINDEX", metric_type="COSINE")
client.create_collection(collection_name=C, schema=schema, index_params=ip)
client.insert(C, rows)
client.flush(C)
client.load_collection(C)

数一下行数:

python
print(client.query(C, filter="id >= 0", output_fields=["count(*)"])[0])
{'count(*)': 12}

两列向量的度量类型都是 COSINE ——为什么不选 L2,7.3.2 的坑里会说。

7.3.2 Function Chain:一条链完成「新鲜度加权 → 排序 → 截断」 ​

先看纯向量检索给出什么:

python
def show(title, res):
    print(title, flush=True)
    for h in res[0]:
        e = h["entity"]
        print(f'  {e["name"]:<20}{e["days_ago"]:>4} 天前  热度 {e["popularity"]:.2f}  相似度 {h["distance"]:.3f}', flush=True)


res = client.search(C, data=[q], anns_field="vec_v1", limit=5,
                    output_fields=["name", "days_ago", "popularity"])
show("== 裸搜 top5 ==", res)
== 裸搜 top5 ==
  索尼 WH-1000XM5         60 天前  热度 0.95  相似度 1.000
  苹果 AirPods Max        45 天前  热度 0.80  相似度 0.997
  小米 降噪耳机 4 Pro          2 天前  热度 0.30  相似度 0.990
  华为 FreeBuds Pro 3      7 天前  热度 0.60  相似度 0.986
  索尼 WF-1000XM5        120 天前  热度 0.85  相似度 0.977

前两名是 60 天和 45 天前上架的老款,120 天前的 WF-1000XM5 也还在榜上;3 天前上架的 AirPods Pro 2 连前五都没进。纯向量检索只认「像」,不认「新」和「热」。 而常规情况下,我们会对召回的大量数据在客户端再执行一次符合我们标准的重排序。

要补的正是这个:在返回前,给每行算出新鲜度、按权重合成新分数、排序、只留 5 条。FunctionChain 就是把这几步声明下来、随请求发过去:

python
# 链:先建一个空链,再一段一段往上挂
chain = FunctionChain(FunctionChainStage.L2_RERANK, name="fresh_and_hot")
# 第 1 段 map:算出一列“新鲜度”,刚上架=1,7 天前=0.5,30 天前≈0.05
chain = chain.map("freshness", fn.decay(col("days_ago"), function="exp", origin=0, scale=7))
# 第 2 段 map:把相似度、新鲜度、热度按 5:3:2 合成新的 $score
chain = chain.map("$score", fn.num_combine(
    col("$score"), col("freshness"), col("popularity"),
    mode="weighted", weights=[0.5, 0.3, 0.2]))
# 第 3、4 段:按新分数排序,只留前 5
chain = chain.sort(col("$score"), desc=True).limit(5)

res = client.search(C, data=[q], anns_field="vec_v1", limit=12,
                    output_fields=["name", "days_ago", "popularity"],
                    function_chains=[chain])
show("== 加链 top5 ==", res)
== 加链 top5 ==
  苹果 AirPods Pro 2       3 天前  热度 0.90  相似度 0.890
  小米 降噪耳机 4 Pro          2 天前  热度 0.30  相似度 0.801
  漫步者 NeoBuds Pro        1 天前  热度 0.10  相似度 0.773
  华为 FreeBuds Pro 3      7 天前  热度 0.60  相似度 0.763
  索尼 WH-1000XM5         60 天前  热度 0.95  相似度 0.691

同一批候选,结果却不同:

  • 苹果 AirPods Pro 2(3 天前,热度 0.90):纯向量检索时连前五都进不去;
  • 小米 降噪耳机 4 Pro(2 天前,热度 0.30):之前第 3 ;
  • 漫步者 NeoBuds Pro(1 天前,热度只有 0.10):纯向量检索都进不了前五 → 挤到第 3;
  • 索尼 WH-1000XM5(60 天前,热度 0.95,最像):第 1 → 掉到第 5。

L2_RERANK 是什么意思。 链的第一个参数是「执行阶段」,决定这条链在结果归并的哪一层跑、能看到多少候选:L0_RERANK 在 QueryNode 逐 segment 执行;L1_RERANK 在本节点 segment 归并后、送回分片 leader 前执行(并且自 3.0.1 起,支持 map/sort/limit);L2_RERANK 在 Proxy 全局归并后执行,是唯一能看到全部候选的阶段。本文要做的是「候选都汇总回来、统一比一次总分」,所以用 L2——等全部候选在 Proxy 归并完再统一比。

想深入了解三个阶段各自在哪执行、每层候选怎么流转、L0/L1/L2 怎么选,见「7.6 深入与进阶」(编写中)。

换一套权重,排序就变一种。 产品说「新品优先」,就把权重从 5:3:2 改成 2:6:2:

python
# 换一套权重:更看重新鲜度
chain2 = (FunctionChain(FunctionChainStage.L2_RERANK, name="fresher")
          .map("freshness", fn.decay(col("days_ago"), function="exp", origin=0, scale=7))
          .map("$score", fn.num_combine(col("$score"), col("freshness"), col("popularity"),
                                        mode="weighted", weights=[0.2, 0.6, 0.2]))
          .sort(col("$score"), desc=True).limit(5))
res = client.search(C, data=[q], anns_field="vec_v1", limit=12,
                    output_fields=["name", "days_ago", "popularity"],
                    function_chains=[chain2])
show("== 权重 2:6:2 ==", res)
== 权重 2:6:2 ==
  苹果 AirPods Pro 2       3 天前  热度 0.90  相似度 0.821
  漫步者 NeoBuds Pro        1 天前  热度 0.10  相似度 0.756
  小米 降噪耳机 4 Pro          2 天前  热度 0.30  相似度 0.750
  华为 FreeBuds Pro 3      7 天前  热度 0.60  相似度 0.617
  击音 入门耳机                5 天前  热度 0.05  相似度 0.557

「击音 入门耳机」(5 天前上架,热度只有 0.05)挤进第 5——更看重新鲜度后,冷门新品也有了机会;而 60 天前的索尼 XM5 直接出局。

Function Chain 编写时的注意事项 ​

  • 先确认分数方向,再组合分数。 L2 距离与 IP、COSINE 的排序方向不同。避免把“越小越好”的距离直接当成“越大越好”的分数使用。
  • 链与其他重排方式不能同时配置。 单次搜索请求中,选择 Function Chain,或选择 ranker / functionScore 进行重排;不要同时配置。可以把它理解为两种不同的重排配置方式,单次请求要选一种:
    • 用 Function Chain:把链配置到搜索请求中,由链执行排序、分数处理等后处理。
    • 用 ranker 或 functionScore:使用对应的重排配置,不再同时传 Function Chain。

简而言之: 先选好执行阶段和分数方向,再配置 map、sort、limit;不要在同一请求中把 Function Chain 与其他 rerank 配置混用。

7.3.3 换模型不重建集合:两列向量 + 部分回填 ​

问题。 线上集合正在服务,不能停,也不能整个重建。换嵌入模型要面对三个问题:老向量按新模型重算、上线前对比新旧效果、新向量增量回填。3.0 用「两列向量 + 部分回填」一次解决——vec_v1、vec_v2 两列在 7.3.1 建表时就一起建好了(各建索引!),下面分步走一遍:

先准备: 连上集合,造一个查询向量 q。

python
from pymilvus import MilvusClient
import numpy as np

client = MilvusClient(uri="http://localhost:19530", token="root:Milvus")
C = "headphones"
q = np.random.default_rng(1).standard_normal(8).astype(np.float32)
q = q.tolist()

第一步:两列各搜一遍。 同一个查询,anns_field 分别指向 vec_v1、vec_v2,看新旧模型给出的近邻差多少。

python
for f in ["vec_v1", "vec_v2"]:
    res = client.search(C, data=[q], anns_field=f, limit=3, output_fields=["name"])
    print(f, [(h["entity"]["name"], round(h["distance"], 3)) for h in res[0]], flush=True)
vec_v1 [('索尼 WH-1000XM5', 1.0), ('苹果 AirPods Max', 0.997), ('小米 降噪耳机 4 Pro', 0.99)]
vec_v2 [('击音 入门耳机', 0.999), ('小米 Redmi Buds 5', 0.997), ('苹果 AirPods Max', 0.993)]

新旧模型近邻完全不同。 vec_v1 里第一是索尼 XM5,vec_v2 里第一是「击音 入门耳机」。

第二步:回填前查 id=5 留底。 记住它现在的样子,之后好对比。

python
row = client.query(C, filter="id == 5", output_fields=["name", "price", "days_ago"])[0]
print("before:", row["name"], row["price"], row["days_ago"], flush=True)
before: 索尼 WF-1000XM5 1899.0 120

第三步:回填一条,只带新向量。 partial_update=True 表示「只补 vec_v2 一列」,别的字段不写。

python
client.upsert(C, [{"id": 5, "vec_v2": q}], partial_update=True)

第四步: flush 落盘、load 重新加载,让新向量真正生效。

python
client.flush(C)
client.load_collection(C)

第五步:再查同一行对比。 除了向量什么都没变,after 该和 before 一字不差。

python
row = client.query(C, filter="id == 5", output_fields=["name", "price", "days_ago"])[0]
print("after:", row["name"], row["price"], row["days_ago"], flush=True)
after: 索尼 WF-1000XM5 1899.0 120

第六步:按 vec_v2 搜验证。 id=5 补上新向量后,从进不了 V2 前三,直接跳到第 1。

python
res = client.search(C, data=[q], anns_field="vec_v2", limit=3, output_fields=["name"])
print("v2 search:", [(h["entity"]["name"], round(h["distance"], 4)) for h in res[0]], flush=True)
v2 search: [('索尼 WF-1000XM5', 1.0), ('击音 入门耳机', 0.9993), ('小米 Redmi Buds 5', 0.9971)]

要点:

  • 第二列趁建表时声明并建索引。 少一列索引,load_collection 直接报 there is no vector index on field;事后补向量列官方说是支持的(add_collection_field 要 nullable=True,顺序是「先建索引、后回填」),但我们 v3.0.2 实测按「加列→回填→建索引」卡在 InProgress,所以能在建表时一起建就提前建好,最省事,不过感觉比较反人类,我怎么知道之后要换嵌入模型。事后补列怎么走这里不赘述,见「7.6 深入与进阶」(编写中)。
  • partial_update=True 是合并语义。 只覆盖给出的列,其余字段原样保留;不带这个参数,没给的字段会被写成默认值。

7.3.4 小结 ​

  • FunctionChain 是 3.0 的搜索结果后处理链:官方定义是「对一次 Search 调用的结果列,依次执行 map、sort、limit 等操作的有序、带类型的管道」,客户端声明、服务端执行,随 search(..., function_chains=[chain]) 一次发过去。
  • 链与 ranker 互斥;融合走 hybrid_search,重排走链。
  • 换模型不重建:建表时声明第二列向量并建索引;回填用 upsert(..., partial_update=True) 只给 id + 新向量;查询改 anns_field。

参考文档:C++ FunctionChain API · Java FunctionChain API · Python search() 的 function_chains 参数 · RESTful Search · 3.0.0 发布说明(Function Chain reranking)

下一章换个维度看索引:3.0 的三类新索引(SINDI 稀疏、FAISS 直通、DiskANN 磁盘)各管什么、怎么开、怎么选。

下一章:7.4 Milvus 3.0 索引与性能选择(实战)