Azure部署CrewAI遇DuplicateIDError：文档ID重复致Upsert失败

问题核心 #

本地运行正常的CrewAI多智能体系统，在Azure环境初始化Crew时触发知识源相关报错：

crewai Failed to upsert documents: "Expected IDs to be unique, found 28 Duplicate IDs"

解决步骤 #

• 修正文档ID生成逻辑
  本地正常但Azure出错，通常是ID生成依赖本地唯一标识（如相对文件路径哈希）导致全局重复。将Document对象的id改为全局唯一生成方式，示例代码：

  from uuid import uuid4
  from langchain_core.documents import Document
  
  # 替换原有ID生成逻辑
  doc = Document(
      page_content="文档内容",
      metadata={"source": "知识源路径"},
      id=str(uuid4())  # 生成全局唯一UUID
  )
  

• 清理Azure向量库重复条目
  根据报错给出的UUID列表，删除向量数据库中已存在的重复文档。若使用CrewAI集成的向量存储，执行以下操作：

  # 假设vector_store为已初始化的向量存储实例
  duplicate_ids = ["UUID1", "UUID2", ...]  # 报错中的重复UUID列表
  vector_store.delete(ids=duplicate_ids)
  

• 确保知识源加载幂等性
  检查Azure环境中是否存在重复触发初始化逻辑的情况，添加加载前校验：

  • 将知识源文件的哈希值存入文档metadata；
  • 加载前查询向量库，若已存在对应哈希的文档则跳过加载。

• 对齐本地与Azure依赖版本
  对比两边环境的crewai、langchain及Azure相关依赖版本，避免版本差异导致逻辑异常。检查命令：

  pip list | grep -E "crewai|langchain|azure"
  

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