[Question]: Fail to load the LLM via vllm

快速结论：该报错通常出现在 RAGFlow 的“Model providers”中添加 vLLM 模型并点击 Ok 校验连接时，优先排查 API Key 留空、Base URL 填写方式以及模型名是否与 vLLM 的 served-model-name 完全一致。

适用环境：RAGFlow v0.20.4；vLLM API server 0.10.1.1，CUDA 平台（日志显示 Automatically detected platform cuda），tensor-parallel-size 2；模型 Qwen3-30B-A3B-Thinking-2507-FP8，served-model-name 为 qwen3-30b。操作系统、Python、PyTorch 版本在 Issue 中未明确。

最快修复方案：暂无确认的一步修复方案。评论建议填写 no-key-need，但该用户在填写后问题仍然存在，因此不能视为已验证的修复方法。

注意事项：Issue 中并未确认最终解决方式；上述配置建议属于可优先尝试的排查方向。若 vLLM 运行在容器或另一台主机上，RAGFlow 中的 localhost 不一定指向 vLLM 服务。

问题场景

用户在本地通过 vLLM 启动 Qwen3-30B-A3B-Thinking-2507-FP8，命令中指定 --served-model-name qwen3-30b，vLLM 日志显示 API server 正常启动。随后在 RAGFlow v0.20.4 的“Model providers”中选择 vLLM，填写 Model type 为 chat、Model name 为 qwen3-30b、Base url 为 http://localhost:8000/v1/models（后改为 http://localhost:8000/v1）、API-Key 为空（后改为 no-key-need）、Max Tokens 为 262144，点击 Ok 时连接校验失败。

报错原文

hint : 102 Fail to access model(VLLM/qwen3-30b).**ERROR**: CONNECTION_ERROR - Connection error.

原因分析

可能是 RAGFlow 无法实际连通所填写的 vLLM OpenAI 兼容端点。评论推测 API Key 留空会导致该连接错误，并建议填入 no-key-need；但用户反馈填入后报错依旧，说明该推测未覆盖本次全部原因。

另一可能原因是 Base URL 的写法。RAGFlow 对 OpenAI 兼容服务通常使用形如 http://localhost:8000/v1 的基础地址，而不是以 /v1/models 结尾的完整模型列表地址；用户后一次配置已改为 /v1，但问题仍未解决。

还需考虑 RAGFlow 与 vLLM 不在同一网络命名空间的情况：vLLM 若运行在容器、虚拟机或另一台主机上，RAGFlow 内部的 localhost 指向自身，无法访问该端口。此外，模型名与 served-model-name 大小写或拼写不一致、vLLM 尚未完成模型加载、端口未对外开放，也可能导致连接失败。

环境排查

确认 RAGFlow 版本为 v0.20.4，vLLM API server 版本为 0.10.1.1。
确认 vLLM 日志中模型已加载完成、API server 在 8000 端口处于监听状态。
确认 RAGFlow 所在环境能否访问 http://localhost:8000/v1；若 vLLM 在容器或另一主机，应使用 RAGFlow 可路由到的 IP 或容器网络地址。
确认 Model name 与 --served-model-name qwen3-30b 完全一致。
确认 Max Tokens 不超过 vLLM 实际支持的上下文长度（日志显示 Using max model len 262144）。
确认 API Key 字段的填写方式；Issue 中 no-key-need 未解决该用户问题，仍需结合网络连通性继续排查。

解决步骤

保留 vLLM 启动命令中的 --served-model-name qwen3-30b，并在 RAGFlow 中将 Model name 填写为完全一致的 qwen3-30b。
可优先尝试将 Base url 写为 http://localhost:8000/v1，不要带 /models 后缀；这是评论中建议的 OpenAI 兼容端点写法。
可优先尝试在 API Key 中填入 no-key-need，即使本地 vLLM 不校验密钥；若仍报连接错误，继续下一步网络排查。
确认 vLLM 与 RAGFlow 是否在同一主机/容器网络。若 vLLM 在容器或另一主机上，把 localhost 替换为 RAGFlow 能访问到的实际地址，并确保 8000 端口允许 RAGFlow 所在网络访问。
修改配置后重启 RAGFlow，再重新点击 Ok 校验连接。
如仍失败，查看 RAGFlow 后端日志中的具体连接目标与异常信息，确认请求是否到达 vLLM。

验证方法

在 RAGFlow 所在环境中访问 vLLM 的 /v1/models 接口，确认可返回模型列表且包含 qwen3-30b；随后在 RAGFlow“Model providers”中重新保存并测试 vLLM 模型，若不再出现 CONNECTION_ERROR - Connection error，并能正常发起对话，则说明连接问题已解决。