[Bug]: vllm instance already exist, while trying to add models with different host ports

问题场景

用户在 RAGFlow 的模型管理界面中，先添加了一个 vLLM 聊天模型，其 base URL 为 http://vllm:8000。随后尝试添加第二个 vLLM reranker 模型，其 base URL 为 http://vllm:8002（不同端口），但添加失败并抛出报错。

报错原文

instance already exist: vllm

原因分析

RAGFlow 的 TenantModelInstance 数据库表中存在一个旧版唯一键约束，作用于 (api_key, provider_id) 组合字段。当两个 vLLM 实例使用了相同的 API key（例如都为空或同一默认值）且 provider_id 相同时，数据库会拒绝第二条记录的插入，即使它们的 base URL / 端口不同。这已被确认为已知 Bug。

环境排查

• 确认 RAGFlow 版本是否为 0.26.0（或更早版本）。
• 检查两个 vLLM 实例配置的 API key 是否相同或均为空。
• 检查数据库 TenantModelInstance 表中是否有唯一索引 uk_api_key_provider_id 或其他类似约束。

解决步骤

1. 优先方案：升级 RAGFlow – 升级到包含 PR #15879 的版本（如 v0.27.0 或更高）。升级后执行数据库迁移，自动删除造成冲突的唯一索引。
2. 备选方案（升级前临时绕过） – 为 reranker 模型配置一个不同的 API key（例如填入任意非空字符串），从而避免唯一键冲突。运行该方案后仍建议尽快升级。

验证方法

升级或修改 API key 后，在 RAGFlow 模型管理页面中重新添加第二个 vLLM 实例，确认不再弹出 “instance already exist: vllm” 错误，且该模型能正常启用。

参考来源

infiniflow/ragflow #16126

AI 工具推荐

想把多个 AI 模型放在一个入口？

GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型，适合写作、绘图、视频和日常 AI 工作流。

了解 GamsGo AI

推广链接：通过此链接购买，我可能获得佣金，不影响你的价格。