Ragflow0.24升级到0.25/0.26出现的“Instance default not found for model”问题解决方法

AI 智能摘要

一、问题现象

RAGFlow 升级或重新配置模型后，知识库解析、检索或使用模型时可能出现类似报错：

ERROR: Instance default not found for model qwen3-vl-plus@default@Tongyi-Qianwen

从报错可以看出，RAGFlow 正在查找的模型是：

qwen3-vl-plus@default@Tongyi-Qianwen

这个模型标识可以拆成三部分：

模型名：qwen3-vl-plus
实例名：default
服务商：Tongyi-Qianwen

也就是说，RAGFlow 想在 Tongyi-Qianwen 这个模型服务商下面，找到一个名为 default 的模型实例，然后使用 qwen3-vl-plus 模型。

但是当前数据库中，Tongyi-Qianwen 服务商下面实际存在的实例名可能不是 default，而是其他名称，例如：

qwen3-vl-plus@<当前实例名>@Tongyi-Qianwen

因此系统找不到 default 实例，就会报：

Instance default not found

二、问题原因

RAGFlow 新版本的模型引用格式通常是：

模型名@实例名@服务商

例如：

qwen3-vl-plus@<当前实例名>@Tongyi-Qianwen
text-embedding-v4@<当前实例名>@Tongyi-Qianwen

其中 <当前实例名> 是你在 RAGFlow 后台 Model providers 中配置的模型实例名称。

但是旧知识库或旧配置中，可能还保存着旧的模型引用：

qwen3-vl-plus@default@Tongyi-Qianwen
text-embedding-v4@default@Tongyi-Qianwen

如果当前 Tongyi-Qianwen 服务商下面没有 default 实例，就会出现模型实例找不到的问题。

本质原因是：

旧模型引用仍然指向 default 实例
但当前模型服务商下实际实例名不是 default

三、修复思路

方式：修改旧模型引用

把数据库中旧的：

@default@Tongyi-Qianwen

统一替换成当前真实存在的实例名：

@<当前实例名>@Tongyi-Qianwen

例如：

text-embedding-v4@default@Tongyi-Qianwen

替换成：

text-embedding-v4@<当前实例名>@Tongyi-Qianwen

四、修复前备份数据库

执行任何 UPDATE 前，建议先备份数据库。

docker exec ragflow-mysql mysqldump -uroot -pinfini_rag_flow rag_flow > rag_flow_bak_$(date +%F_%H%M%S).sql

确认备份文件是否生成：

ls -lh rag_flow_bak_*.sql

如果你的 MySQL 容器名不是 ragflow-mysql，可以先查看容器名：

docker ps | grep mysql

五、确认当前模型实例名

先查询 Tongyi-Qianwen 服务商下面实际有哪些模型实例。

USE rag_flow;

SELECT 
  i.id,
  i.instance_name,
  i.provider_id,
  i.status,
  i.extra,
  p.provider_name,
  p.tenant_id
FROM tenant_model_instance i
LEFT JOIN tenant_model_provider p ON p.id = i.provider_id
WHERE p.provider_name = 'Tongyi-Qianwen';

如果查询结果中只有类似：

instance_name = <当前实例名>

没有：

instance_name = default

那么旧配置中的：

qwen3-vl-plus@default@Tongyi-Qianwen

就会找不到模型实例。

后续 SQL 中的 <当前实例名>，都需要替换为这里实际查到的 instance_name。

六、检查系统默认模型配置：tenant 表

tenant 表保存系统默认模型配置，包括聊天模型、Embedding 模型、图片转文本模型、ASR 模型、Rerank 模型等。

查询是否存在旧引用

SELECT id, name, llm_id, embd_id, img2txt_id, asr_id, rerank_id
FROM tenant
WHERE llm_id LIKE '%@default@Tongyi-Qianwen%'
   OR embd_id LIKE '%@default@Tongyi-Qianwen%'
   OR img2txt_id LIKE '%@default@Tongyi-Qianwen%'
   OR asr_id LIKE '%@default@Tongyi-Qianwen%'
   OR rerank_id LIKE '%@default@Tongyi-Qianwen%';

替换旧实例名

UPDATE tenant
SET llm_id = REPLACE(llm_id, '@default@Tongyi-Qianwen', '@<当前实例名>@Tongyi-Qianwen'),
    embd_id = REPLACE(embd_id, '@default@Tongyi-Qianwen', '@<当前实例名>@Tongyi-Qianwen'),
    img2txt_id = REPLACE(img2txt_id, '@default@Tongyi-Qianwen', '@<当前实例名>@Tongyi-Qianwen'),
    asr_id = REPLACE(asr_id, '@default@Tongyi-Qianwen', '@<当前实例名>@Tongyi-Qianwen'),
    rerank_id = REPLACE(rerank_id, '@default@Tongyi-Qianwen', '@<当前实例名>@Tongyi-Qianwen')
WHERE llm_id LIKE '%@default@Tongyi-Qianwen%'
   OR embd_id LIKE '%@default@Tongyi-Qianwen%'
   OR img2txt_id LIKE '%@default@Tongyi-Qianwen%'
   OR asr_id LIKE '%@default@Tongyi-Qianwen%'
   OR rerank_id LIKE '%@default@Tongyi-Qianwen%';

如果查询结果为空，说明系统默认模型配置中没有旧引用，可以跳过此表。

七、重点修复知识库模型配置：knowledgebase 表

knowledgebase 表是本次问题最关键的表。

知识库可能保存了自己的 Embedding 模型和解析配置，不一定完全使用 tenant 表中的系统默认模型。

查询旧引用

SELECT id, name, tenant_id, embd_id, parser_config
FROM knowledgebase
WHERE embd_id LIKE '%@default@Tongyi-Qianwen%'
   OR parser_config LIKE '%@default@Tongyi-Qianwen%';

修改 embd_id

如果 embd_id 中存在旧引用，例如：

text-embedding-v4@default@Tongyi-Qianwen

需要替换成：

text-embedding-v4@<当前实例名>@Tongyi-Qianwen

执行 SQL：

UPDATE knowledgebase
SET embd_id = REPLACE(
  embd_id,
  '@default@Tongyi-Qianwen',
  '@<当前实例名>@Tongyi-Qianwen'
)
WHERE embd_id LIKE '%@default@Tongyi-Qianwen%';

修改 parser_config

parser_config 中也可能保存模型配置，例如图片转文本模型、RAPTOR、GraphRAG、自动关键词、自动问题生成等模型引用。

如果 parser_config 中包含旧实例名，也需要替换：

UPDATE knowledgebase
SET parser_config = REPLACE(
  parser_config,
  '@default@Tongyi-Qianwen',
  '@<当前实例名>@Tongyi-Qianwen'
)
WHERE parser_config LIKE '%@default@Tongyi-Qianwen%';

八、检查文档级模型配置：document 表

部分文档可能保存了自己的解析配置，里面也可能包含旧模型引用。

查询旧引用

SELECT id, kb_id, name, parser_config
FROM document
WHERE parser_config LIKE '%@default@Tongyi-Qianwen%';

替换旧实例名

UPDATE document
SET parser_config = REPLACE(
  parser_config,
  '@default@Tongyi-Qianwen',
  '@<当前实例名>@Tongyi-Qianwen'
)
WHERE parser_config LIKE '%@default@Tongyi-Qianwen%';

如果查询结果为空，则无需修改 document 表。

九、全库搜索旧模型引用

如果不确定旧引用还存在于哪些地方，可以使用 mysqldump + grep 全库搜索。

搜索服务商下的 default 实例引用

docker exec ragflow-mysql mysqldump -uroot -pinfini_rag_flow rag_flow \
| grep -n -C 2 "@default@Tongyi-Qianwen"

搜索具体图片转文本模型

docker exec ragflow-mysql mysqldump -uroot -pinfini_rag_flow rag_flow \
| grep -n -C 2 "qwen3-vl-plus@default@Tongyi-Qianwen"

搜索具体 Embedding 模型

docker exec ragflow-mysql mysqldump -uroot -pinfini_rag_flow rag_flow \
| grep -n -C 2 "text-embedding-v4@default@Tongyi-Qianwen"

如果没有输出，说明旧模型引用基本已经清理干净。

十、可选方案：给服务商补一个 default 实例

如果不想修改历史模型引用，也可以给 Tongyi-Qianwen 补一个 default 实例。

查询 Tongyi-Qianwen 的 provider_id

SELECT id, provider_name, tenant_id, status
FROM tenant_model_provider
WHERE provider_name = 'Tongyi-Qianwen';

假设查出来的 provider_id 是：

这里替换成实际 provider_id

确认当前可用实例

SELECT *
FROM tenant_model_instance
WHERE provider_id = '这里替换成实际 provider_id'
  AND instance_name = '<当前实例名>';

复制当前实例为 default 实例

INSERT INTO tenant_model_instance
(
  id,
  create_time,
  create_date,
  update_time,
  update_date,
  instance_name,
  provider_id,
  api_key,
  status,
  extra
)
SELECT
  REPLACE(UUID(), '-', ''),
  UNIX_TIMESTAMP(NOW(3)) * 1000,
  NOW(),
  UNIX_TIMESTAMP(NOW(3)) * 1000,
  NOW(),
  'default',
  provider_id,
  api_key,
  status,
  extra
FROM tenant_model_instance i
WHERE i.instance_name = '<当前实例名>'
  AND i.provider_id = '这里替换成实际 provider_id'
  AND NOT EXISTS (
    SELECT 1
    FROM tenant_model_instance x
    WHERE x.provider_id = i.provider_id
      AND x.instance_name = 'default'
  );

确认 default 实例是否创建成功

SELECT 
  i.id,
  i.instance_name,
  i.provider_id,
  i.status,
  p.provider_name
FROM tenant_model_instance i
LEFT JOIN tenant_model_provider p ON p.id = i.provider_id
WHERE p.provider_name = 'Tongyi-Qianwen';

如果同时看到：

<当前实例名>
default

说明已经补齐了 default 实例。

不过从长期维护角度看，更推荐统一修改旧模型引用，而不是长期保留多个实例名。

十一、重启 RAGFlow

修改完成后，重启 RAGFlow。

cd /home/ragflow-main/docker
docker compose restart

如果你的 compose 文件在其他路径，可以使用：

cd /home/ragflow-main
docker compose -f docker/docker-compose.yml restart

十二、最终检查

修改完成后，再次检查是否还有旧引用。

docker exec ragflow-mysql mysqldump -uroot -pinfini_rag_flow rag_flow \
| grep -n -C 2 "@default@Tongyi-Qianwen"

如果没有输出，说明旧引用已经清理完成。

也可以再次检查知识库表：

SELECT id, name, tenant_id, embd_id, parser_config
FROM knowledgebase
WHERE embd_id LIKE '%@default@Tongyi-Qianwen%'
   OR parser_config LIKE '%@default@Tongyi-Qianwen%';

十三、总结

本次问题的根因是：

旧配置中保存了 @default@Tongyi-Qianwen
但当前 Tongyi-Qianwen 服务商下实际存在的实例名不是 default
导致 RAGFlow 查找 default 实例失败

建议优先采用以下修复方式：

将 @default@Tongyi-Qianwen 替换为 @<当前实例名>@Tongyi-Qianwen

重点检查和修改以下表：

表名 字段 说明
tenant llm_id、embd_id、img2txt_id、asr_id、rerank_id 系统默认模型配置
knowledgebase embd_id 知识库 Embedding 模型
knowledgebase parser_config 知识库解析模型配置
document parser_config 文档级解析模型配置
tenant_model_instance instance_name 模型实例名称

最关键的修复 SQL 是：

UPDATE knowledgebase
SET embd_id = REPLACE(
  embd_id,
  '@default@Tongyi-Qianwen',
  '@<当前实例名>@Tongyi-Qianwen'
)
WHERE embd_id LIKE '%@default@Tongyi-Qianwen%';

如果 parser_config 中也有旧引用：

UPDATE knowledgebase
SET parser_config = REPLACE(
  parser_config,
  '@default@Tongyi-Qianwen',
  '@<当前实例名>@Tongyi-Qianwen'
)
WHERE parser_config LIKE '%@default@Tongyi-Qianwen%';

如果 document.parser_config 中也有旧引用：

UPDATE document
SET parser_config = REPLACE(
  parser_config,
  '@default@Tongyi-Qianwen',
  '@<当前实例名>@Tongyi-Qianwen'
)
WHERE parser_config LIKE '%@default@Tongyi-Qianwen%';

最后执行全库检查：

docker exec ragflow-mysql mysqldump -uroot -pinfini_rag_flow rag_flow \
| grep -n -C 2 "@default@Tongyi-Qianwen"

没有输出后，说明模型旧引用基本已经清理完成。