Milvus BM25 全文检索配置与迁移

背景

FastGPT 的全文检索默认走 MongoDB $text。当使用 Milvus 作为向量库时，全文检索自动切换到 Milvus BM25（modeldata_v2 单表，向量 + 全文同表），不再写 MongoDB 全文表。这要求 Milvus 版本 ≥ 2.5.16；低于 2.5.16 时 FastGPT 启动会直接报错退出，不会降级运行。

全文后端跟随实际向量库：向量库是 Milvus 时用 BM25；其他向量库（PG/OceanBase/SeekDB/openGauss）全文仍走 MongoDB $text。无需配置独立的全文本引擎开关。

配置与迁移流程

1. 备份

升级前先备份，便于回滚：

Milvus 数据卷（standalone 的 milvus 数据目录，含向量数据）
Milvus 配套的 etcd / MinIO 数据卷
MongoDB（dataset_datas、dataset_collections、datasets 等业务数据）

2. 停写

建议在低写入时段执行，或先停止 FastGPT 应用写入。迁移期间如需保持服务，请勿同时写数据集数据（详见第 5 步"迁移期间新数据"）。

3. 升级 Milvus 到 2.5.16+

升级必须保留原有 Milvus 数据卷和旧集合 modeldata。直接替换镜像 tag 后重启：

yaml

# docker-compose 中 Milvus 服务
image: milvusdb/milvus:v2.5.16

旧 modeldata 是后续迁移的向量数据源。升级后应先确认该集合存在且非空；如果集合缺失或为空，请停止迁移并从备份恢复 Milvus 数据。

4. 验证版本

启动 FastGPT，Milvus 初始化时会调用 getVersion() 校验版本；低于 2.5.16、无法获取或无法解析版本会终止启动。也可以手动验证：

bash

# 通过 milvus-cli / attu / SDK getVersion 确认服务端版本 >= v2.5.16

5. 迁移

确认旧 Milvus modeldata 集合存在且有向量后，调用迁移接口（纯拷贝，不重嵌入）：

bash

# 1. dry-run 先看统计
curl 'http://host/api/admin/4162/milvus?dryRun=1' \
  -H 'rootkey: 你的ROOT_KEY'

# 2. 正式迁移
curl 'http://host/api/admin/4162/milvus?batchSize=500' \
  -H 'rootkey: 你的ROOT_KEY'

# 3. 若请求被网关超时中断,用返回的 migrationId 续跑
curl 'http://host/api/admin/4162/milvus?resumeMigrationId=<uuid>' \
  -H 'rootkey: 你的ROOT_KEY'

迁移遍历 Milvus modeldata 向量行并反查 MongoDB dataset_datas.indexes 原文，写入 modeldata_v2。imageEmbedding 索引只拷贝向量、BM25 文本置空。迁移支持断点续跑、失败行落库并自愈重试、完成时实际校验 modeldata_v2 目标行数，并使用幂等 upsert，可安全重复执行。

6. 验证迁移结果

接口返回 status: done、targetCount >= processedCount。
在知识库中做一次全文检索 / 混合检索冒烟，确认命中正常。

7. 主动删除旧表 `modeldata`

迁移完成后旧表 modeldata 不会自动删除。管理员确认迁移无误后，主动删除：

通过迁移接口显式删除（校验通过后 drop + 清空 MongoDB 旧全文表）：
bash
```
curl 'http://host/api/admin/4162/milvus?removeOld=1' \
  -H 'rootkey: 你的ROOT_KEY'
```
或使用 milvus-cli / SDK 手动 drop modeldata。

删除后 FastGPT 重启不会重新创建或访问旧表：正常初始化只创建/加载 modeldata_v2，modeldata 仅由迁移脚本探测/加载。

8. 回滚

未执行 removeOld（旧表仍在）：降级 FastGPT 镜像并恢复备份即可，旧全文数据仍在 MongoDB。
已执行 removeOld（旧表已删）：需从备份恢复 Milvus 数据卷后再降级。
迁移可重复执行（幂等 upsert），迁移失败后用 resumeMigrationId 续跑。

常见问题

启动报 Milvus version ... is not supported：Milvus 版本低于 2.5.16，升级到 2.5.16+。
迁移报旧 modeldata 缺失或为空：停止迁移并检查是否连接了错误的 Milvus 实例、数据卷是否正确挂载；确认数据丢失时从备份恢复。
迁移一直 failed 且 targetCount < processedCount：目标表实际写入行数不足，检查 Milvus 状态（是否 OOM / 已释放集合），用 resumeMigrationId 续跑。
迁移后全文检索为空：确认已跑完迁移且 status: done；modeldata_v2 为空时全文无命中。

背景