RAGFlow 的无缝升级 - 从 0.21 到 0.22 及更高版本

2025年11月19日阅读时长 3 分钟

背景

从 0.22.0 版本开始，RAGFlow 不再提供内置 Embedding 模型的完整 Docker 镜像。此前，部分用户依赖该镜像中捆绑的 Embedding 模型来构建数据集。

升级到 0.22.0 后，这些模型不再可用，导致了几个问题：数据集原先使用的 Embedding 模型丢失；无法添加新文档；数据集中的检索功能无法正常工作；并且由于旧的逻辑限制，无法切换到新的 Embedding 模型。为了解决升级后的这些兼容性问题，我们在 0.22.1 版本中引入了重要的改进。

0.22.1 版本功能

包含已解析数据的知识库现支持更换嵌入模型

从 RAGFlow 0.22.1 开始，引入了更安全、自动化的 Embedding 兼容性检查，允许用户在已有数据的数据集上切换 Embedding 模型。为确保新的 Embedding 模型不会破坏原有的向量空间结构，RAGFlow 会执行以下检查：

样本提取：从当前数据集中随机选择几个（例如 5-10 个）chunk 作为代表性样本。
重新编码：使用用户选择的新 Embedding 模型为抽样的 chunk 生成新向量。
相似度计算：对每个 chunk，计算新旧向量之间的余弦相似度。
切换决策：如果平均相似度达到 0.9 或以上，则认为新旧模型在向量空间上足够一致，允许切换。如果低于 0.9，则拒绝模型切换请求。

为何使用 0.9 阈值？

阈值设为 0.9，是因为来自不同模型提供商的同名模型可能存在微小的版本差异，并且 RAGFlow 的 Embedding 也会因策略和参数而异，因此新模型无法完美复现旧的 Embedding 环境。这些“微小差异”通常仍能得到 0.9 以上的平均相似度，所以 0.9 可以很好地作为“可安全替换”模型的临界值。相比之下，来自完全不同模型家族的 Embedding（例如，从 MiniLM 到 BGE-M3）的相似度往往在 0.3–0.6 之间，因此它们会低于此阈值并被正确阻止，从而防止向量空间被打乱。