Cognee Embedding 模型升级：从 bge-small 到 multilingual-e5-large

从 384d 到 1024d，一行配置变更的背后是向量库全量重建、容器 OOM 循环、以及一个藏得很深的 ONNX 缓存 bug。

一、为什么换

Cognee 知识图谱系统最初部署时选择了 BAAI/bge-small-en-v1.5——384 维、261MB 内存占用、纯英文模型。在当时的约束下（无 GPU、7.5GB 总内存），这是唯一能跑通的本地 embedding 方案。

但使用中发现两个问题：

1. 中文语义匹配弱 — bge-small 是纯英文模型，中文查询返回的向量质量明显下降
2. 384 维区分度不够 — 向量空间较窄，知识条目增多后检索精度下降

需要升级到更大的多语言模型。

二、三模型对比

在正式切换前，测试了三个候选模型：

选定 e5-large：jina-v3 内存需求过大（单模型超 2GB），在当前服务器容器限制下无解；bge-small-zh 精度提升有限；e5-large 在精度和资源之间取得平衡。

三、技术难点

3.1 维度不兼容 — 必须全量重建

LanceDB 不支持 in-place 修改向量维度。384d → 1024d 的迁移路径是：

删除旧 collection → 切换 embedding 模型 → 重新 cognify 全量知识

没有捷径。这也意味着切换期间全部存量知识的语义召回能力归零，直到 cognify 重新跑完。

3.2 内存翻倍 — 容器调参

bge-small 的 261MB 到 e5-large 的理论 843MB，内存翻了三倍。但实际运行中发现 e5-large 实际占用 2.1GB——远超预期的 800MB。原因：ONNX 运行时会额外分配推理缓冲区，加上 LanceDB 的索引开销。

对应调整：容器 mem_limit 从 2g 提升到 4g。

3.3 重启循环 — 一个 ONNX 缓存 bug

切换 e5-large 后容器陷入重启循环：启动 → 加载模型 → 崩溃 → Docker 自动重启。

排查发现根因是 ONNX 推理缓存文件损坏。e5-large 首次下载的 .onnx 缓存文件不完整（下载被中断），但 fastembed 没有校验完整性，每次加载到损坏处就 SIGSEGV。

修复方式：删除整个 ONNX 缓存目录，让 fastembed 重新下载完整模型文件。首次下载约 5 分钟，后续加载约 30 秒。

3.4 DeepSeek tool_choice 冲突

另一个意外发现：切换模型后 cognify 管道间歇失败，LLM 调用返回格式错误。根因是 DeepSeek v4-pro 的 tool_choice 参数与 Cognee 的内部 structured output 格式冲突。

修复：设置环境变量 LLM_INSTRUCTOR_MODE=json_mode，强制 JSON 输出模式，绕过 tool_choice 机制。

四、最终状态

模型：   intfloat/multilingual-e5-large
维度：   1024d
内存：   2.1GiB / 4GiB
容器：   健康 (HTTP 200)
cognify：PipelineRunCompleted ✅

Cognee 现在正式运行在 1024 维多语言 embedding 上，中英文语义检索精度显著提升。

五、踩坑清单

一个 embedding 模型的切换，暴露了四个看似不相关的系统耦合点。每次基础设施变更，都是在给系统做全身 CT 扫描。