Qdrant 如何安全追加图像数据不覆盖

Qdrant 支持对已有集合动态追加向量与元数据，关键在于避免使用 `recreate_collection`（会清空旧数据），而应首次创建时调用 `create_collection`，后续新增图像则直接调用 `upsert` 或 `upload_records`。同时需确保每条记录 ID 全局唯一。

在您当前的代码中，问题根源明确：qclient.recreate_collection(...) 每次执行都会强制删除已有同名集合，并新建一个空集合——这正是旧图像丢失的根本原因。Qdrant 的设计哲学是「集合即长期存储单元」，一旦创建完成，就应持续复用，而非反复重建。

✅ 正确做法：分离「建库」与「入库」逻辑

• 首次初始化集合：仅在系统首次运行或需要重置时调用 create_collection（推荐配合 collection_exists() 判断）；
• 日常新增图像：直接使用 upload_records（批量）或 upsert（单条/小批量），无需重建集合；
• ID 管理至关重要：所有新记录的 id 必须与历史记录不冲突（建议使用 UUID、时间戳+哈希、或自增全局计数器）。

以下是重构后的核心逻辑示例（仅展示关键修改部分）：

# ✅ 安全创建集合：仅当不存在时才创建
if not qclient.collection_exists(collection_name=collection_name):
    qclient.create_collection(
        collection_name=collection_name,
        vectors_config=VectorParams(
            size=embedding_length,
            distance=Distance.COSINE
        )
    )
    print(f"✅ Collection '{collection_name}' created.")
else:
    print(f"ℹ️  Collection '{collection_name}' already exists. Skipping creation.")

# ✅ 生成唯一 ID（避免覆盖！）
import uuid
records = [
    models.Record(
        id=str(uuid.uuid4()),  # 强烈推荐：UUID 保证全局唯一性
        payload=payload_dicts[idx],
        vector=embeddings[idx].tolist()  # 注意：Qdrant 接受 list[float]，非 torch.Tensor
    )
    for idx in range(len(payload_dicts))
]

# ✅ 追加写入（不会影响已有数据）
qclient.upload_records(
    collection_name=collection_name,
    records=records,
    batch_size=64  # 可选：提升大批量插入性能
)
print(f"✅ Successfully added {len(records)} new images.")

⚠️ 注意事项与最佳实践

• 向量类型转换：embeddings[idx] 是 PyTorch 张量，Qdrant 要求 list[float]，务必调用 .tolist()；
• ID 冲突风险：若沿用 idx 作为 ID（如 id=idx），新批次的索引将从 0 开始，必然覆盖旧数据 —— 这是比 recreate_collection 更隐蔽的丢失原因；
• 幂等性保障：生产环境建议结合 payload 中的 image_url 字段构建唯一键（如通过 scroll + filter 预查重复），或使用 upsert 配合自定义 points ID 实现精准更新；
• 性能优化：单次上传超 1000 条记录时，启用 batch_size 参数可显著减少网络往返开销；
• 错误处理：实际部署中应包裹 try/except 捕获 UnexpectedResponse 或 ResponseHandlingException，并记录失败详情。

总结而言，Qdrant 天然支持增量索引构建——您完全可以在模型迭代、图像库扩容、用户上传等场景中，安全、高效、无损地向现有集合追加任意数量的新图像。只需牢记两个原则：一次建库，多次追加；ID 唯一，绝不覆盖。