背景
RAGFlow 0.22.0 版本开始，默认不再提供内置 embedding 模型的完整版 Docker 镜像。
此前，部分用户依赖该镜像中自带的 embedding 模型构建知识库。
升级到 0.22.0 后，这些模型将不再可用，导致以下问题：
- 原本知识库所依赖的 embedding 模型缺失
- 无法继续新增文档
- 知识库无法正常处理 Retrieval
- 无法切换到新的 embedding 模型（因为旧逻辑限制）
为解决用户在升级后遇到的兼容性问题，我们在 0.22.1 版本中进行了重要优化。
0.22.1 中的新能力
从 0.22.1 开始允许有数据的知识库更换 embedding 模型
从 RAGFlow 0.22.1 开始，我们引入了更安全、自动化的 embedding 兼容检查机制，由此用户可以在有数据的知识库上更换 embedding 模型。
为确保新的 embedding 模型不会破坏原有知识库的向量空间结构，RAGFlow 将执行以下检查流程：
-
-
1. 样本抽取 从当前知识库中随机抽取若干 chunk（如 5～10 条）作为代表性样本。 -
-
2. 重新编码 使用用户所选的新 embedding 模型，为抽样 chunk 生成对应的新向量。 -
-
3. 相似度计算 针对每个 chunk，系统将计算新旧向量之间的余弦相似度： cosine_similarity(new_vector, old_vector) -
-
4. 切换判定 - 若样本平均相似度 ≥ 0.9，则认为新旧模型在向量空间中具备足够一致性，允许切换。
- 若平均相似度未达到 0.9 阈值，则拒绝本次模型更换请求。
为什么设定阈值 0.9？
之所以将阈值设定为 0.9，主要是因为不同供应商的同名模型可能存在小版本差异，而 RAGFlow 生成 embedding 时也会受到多种策略与参数影响，新模型无法完全复现旧模型的编码环境。
这类“轻微差异”通常仍能保持 0.9 以上的平均相似度，因此 0.9 能有效识别“可安全替换”的情况。同时，完全不同家族的模型（如 MiniLM → BGE-M3）相似度通常只有 0.3–0.6，无法达到该阈值，从而被正确拦截，避免向量空间混乱。
如何更换embedding模型
1、在模型配置界面配置新的模型，更换不可以使用的默认模型。
2、进入知识库配置界面，选择新模型供应商的相同名字的模型，等待模型更换成功。
如果，切换 embedding 模型失败，则会出现错误提示。
3、进入检索测试，自测新embedding模型。
4、在聊天等涉及知识库检索的功能，现在也可以正常使用。
后续版本中，我们将持续强化产品的升级体验。团队已在规划后续版本中提供更完善的升级工具与自动化脚本，旨在进一步简化从老版本迁移的流程，最大限度地减少用户的维护负担。
-
欢迎大家持续关注和 Star RAGFlow
https://github.com/infiniflow/ragflow
