【Milvus 实战】使用 upsert 接口高效更新向量数据库中的数据
在基于 Milvus 向量数据库的开发中，数据更新是高频操作场景。本文将通过完整的代码示例，详细讲解如何使用 PyMilvus 客户端的
upsert接口实现 Milvus 集合（Collection）中数据的精准更新，并验证更新结果，同时解决开发中常见的版本兼容警告问题。一、场景背景
Milvus 作为主流的向量数据库，提供了
upsert（插入 / 更新）接口 —— 当数据 ID 已存在时执行更新操作，ID 不存在时执行插入操作，这一特性非常适合需要对已有向量数据进行字段更新的场景。本文以更新向量数据的color字段为例，演示完整的更新流程。二、完整代码实现
代码主要分为以下几个核心步骤：
- 连接 Milvus 服务端
- 验证集合加载状态
- 查询更新前的数据（基准对比）
- 执行数据更新操作
- 查询更新后的数据（验证更新结果）
三、核心操作详解：数据更新（upsert）
upsert 接口的核心特性
upsert是 Milvus 的核心数据操作接口，其行为由数据的id字段决定：- 若
id在集合中已存在：更新该 ID 对应的所有指定字段（如本文中的vector和color）； - 若
id在集合中不存在：插入这条新数据。
四、注意事项
- 数据落盘延迟：Milvus 写入数据存在毫秒级延迟，若更新后立即查询未看到结果，可通过
time.sleep(1)短暂休眠后再查询； - ID 的唯一性：
id是 Milvus 集合的主键（主键字段不可修改），必须通过id定位待更新的记录； - 字段兼容性：更新的字段需与集合的 Schema 定义一致（如
vector维度、color字段类型），否则会报错；
五、总结
本文通过完整的实战代码，演示了 Milvus 向量数据库中基于
upsert接口的数据更新操作，核心要点如下：upsert接口是 Milvus 实现数据更新的核心方式，通过 ID 匹配实现 “存在即更新，不存在即插入”；- 更新操作需先定义包含目标 ID 和新字段值的数据列表，再调用
upsert接口执行； - 执行更新后，需重新查询数据验证更新结果，必要时可添加短暂休眠确保数据落盘。
该方法适用于所有需要更新 Milvus 向量数据的场景，如商品向量属性更新、用户特征向量刷新等，是 Milvus 开发中必备的核心技能。
代码如下：
# 过滤 pymilvus 依赖的 pkg_resources 废弃警告（setuptools≥81 版本触发）
# 目的是消除版本兼容带来的无关警告，让控制台输出更整洁
import warnings
warnings.filterwarnings("ignore", message=".*pkg_resources is deprecated as an API.*")
from pymilvus import MilvusClient
import timeclient = MilvusClient(uri="http://192.168.211.128:19530",token="root:Milvus"
)
#集合名称
collection_name = "insert_collection"# 验证加载状态
load_state = client.get_load_state(collection_name=collection_name)
print("----查看加载状态----")
print(load_state)# 10. 查询数据
all_data = client.query(collection_name=collection_name,filter="id >= 0",output_fields=["id", "vector", "color"],limit=1 # 使用实际数据量作为limit
)# 11. 打印查询结果
print(f"\n集合 {collection_name} 中共有 {len(all_data)} 条数据：")
for idx, data in enumerate(all_data):print(f"\n第{idx+1}条：")print(f"ID: {data['id']}")print(f"向量: {data['vector']}")print(f"颜色: {data['color']}")#修改数据
data=[{"id": 0, "vector": [-0.619954382375778, 0.4479436794798608, -0.17493894838751745, -0.4248030059917294, -0.8648452746018911], "color": "black_2"}]res = client.upsert(collection_name='insert_collection',data=data
)print(res)# 短暂休眠（Milvus数据写入有延迟，确保数据落盘后再查询）
#time.sleep(1)all_data = client.query(collection_name=collection_name,filter="id >= 0",output_fields=["id", "vector", "color"],limit=1 # 使用实际数据量作为limit
)print(f"\n集合 {collection_name} 中共有 {len(all_data)} 条数据：")
for idx, data in enumerate(all_data):print(f"\n第{idx+1}条：")print(f"ID: {data['id']}")print(f"向量: {data['vector']}")print(f"颜色: {data['color']}")
输出如下：
----查看加载状态----
{'state': <LoadState: Loaded>}
集合 insert_collection 中共有 1 条数据：
第1条：
ID: 0
向量: [-0.6199544, 0.4479437, -0.17493895, -0.42480302, -0.8648453]
颜色: black_1
{'upsert_count': 1}
集合 insert_collection 中共有 1 条数据：
第1条：
ID: 0
向量: [-0.6199544, 0.4479437, -0.17493895, -0.42480302, -0.8648453]
颜色: black_2