Qdrant中upload_records与upsert方法的区别及适用场景问询

Qdrant里的upsert和upload_records都是用来往集合里写数据的接口，但设计初衷和适用场景有明显区别，下面具体拆解：

一、upsert 方法 #

• 核心逻辑：支持「插入新记录+更新已有记录」，根据记录的id判断——如果id已存在就更新对应内容，不存在就插入新记录，是个通用型的写入工具。
• 关键特性：
  • 单条、批量操作都能搞定，灵活性拉满
  • 可以单独指定向量、元数据（payload）等字段，不用传完整的Record结构（比如只更新某条记录的payload，不用重新上传向量）
  • 支持通过wait参数控制是否等待写入完成再返回结果
• 适用场景：
  • 处理增量数据：比如实时同步业务数据，新数据插入、旧数据更新用这一个接口就行
  • 单条/小批量数据写入：比如用户实时生成的内容，需要立刻存入向量库
  • 需要部分更新记录：比如只修改某条记录的状态标签，不用动向量部分

示例代码（Python客户端）：

from qdrant_client import QdrantClient
from qdrant_client.models import PointStruct

client = QdrantClient(host="localhost", port=6333)

# 批量upsert：插入新记录+更新已有id的记录
client.upsert(
    collection_name="my_collection",
    points=[
        PointStruct(id=1, vector=[0.1, 0.2, 0.3], payload={"name": "updated_name"}),
        PointStruct(id=2, vector=[0.4, 0.5, 0.6], payload={"name": "new_record"})
    ]
)

# 单条upsert，仅更新payload
client.upsert(
    collection_name="my_collection",
    points=[PointStruct(id=1, payload={"status": "active"})]
)

二、upload_records 方法 #

• 核心逻辑：专门针对大规模全量数据导入优化的接口，默认只支持插入新记录（如果遇到重复id会报错，手动设置upsert=True可以开启更新功能）。
• 关键特性：
  • 只支持批量操作，对大数据量的写入性能做了专门优化
  • 默认要求传入完整的Record结构（包含id、向量、payload），结构比较固定
  • 内部会自动拆分最优批次，减少网络请求开销，适合一次性导入大量数据
• 适用场景：
  • 首次初始化向量库：比如一次性导入几万甚至上百万条原始数据集
  • 批量导入无重复id的新数据：比如定期同步一批全新的业务数据，确保没有重复id
  • 追求最高批量写入性能：比手动拆分的upsert效率更高

示例代码（Python客户端）：

from qdrant_client import QdrantClient
from qdrant_client.models import Record

client = QdrantClient(host="localhost", port=6333)

# 批量导入全量新数据
records = [
    Record(id=1, vector=[0.1, 0.2, 0.3], payload={"name": "record_1"}),
    Record(id=2, vector=[0.4, 0.5, 0.6], payload={"name": "record_2"}),
    # ... 更多记录
]

client.upload_records(
    collection_name="my_collection",
    records=records
)

# 开启upsert模式，支持更新已有id的记录
client.upload_records(
    collection_name="my_collection",
    records=records,
    upsert=True
)

三、核心对比与选择建议 #

选择建议 #

• 要是你需要处理增量更新、单条数据写入、部分字段更新：直接用upsert
• 要是你在首次全量导入、大规模批量写入无重复数据：优先选upload_records
• 如果想用upload_records同时支持更新，记得加upsert=True参数，但此时性能会略低于纯插入场景

内容的提问来源于stack exchange，提问作者Mohsen Mahmoodzadeh