infiniflow
[Question]: user_default_llm Not effective
Self Checks
- [x] I have searched for existing issues search for existing issues, including closed ones.
- [x] I confirm that I am using English to submit this report (Language Policy).
- [x] Non-english title submitions will be closed directly ( 非英文标题的提交将会被直接关闭 ) (Language Policy).
- [x] Please do not modify this template :) and fill in all the required fields.
Describe your problem
By modifying the service_conf.yaml.template file and adding the user_default_llm: section, the service_conf.yaml file inside the container loads normally. Ragflow also loads and outputs user_default_llm: {'factory': 'OpenAI-API-Compatible', 'api_key':...... }. However, why do new users still need to manually add models at the model provider's location after logging in?
The most common reason new users still need to manually add models after configuring user_default_llm is that the config only sets global defaults—it does not automatically provision models for new users unless everything is correctly set up and registered. For the default models to appear for new users, you need to:
- Make sure your
user_default_llmsection is fully uncommented, correctly indented, and matches the expected YAML structure. Each model (chat, embedding, etc.) should be underdefault_models, and both the model and factory must exist in yourllm_factories.jsonwith all required fields (including a non-empty API key or placeholder) [details & example]. - Restart the backend/container after making changes. The config only affects new users created after the restart; existing users/tenants are not updated retroactively [source].
- If the model does not appear in the UI or is not available, check that the model is registered in
llm_factories.json, the API key is not blank, and the config file is correctly mounted inside the container [troubleshooting]. - If you see "Model not authorized" or "no such model" errors, it means the model is not registered for the tenant in the backend database, even if present in the config files. You must either manually add the model to the tenant's records or create a new user after updating the config [workflow explanation].
Some versions only support one factory for all default models, so you can't mix providers for chat and embeddings unless you're on a recent release that supports this [feature request].
For more details and config examples, see the support thread and config template.
To reply, just mention @dosu.
How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other
![dosubot[bot] avatar](https://avatars.githubusercontent.com/in/324583?v=4 "Published by a pub.dev verified publisher"){kind=small}
@
新用户配置完成后仍需手动添加模型的最常见原因
user_default_llm是，配置仅设置全局默认值，除非所有内容都已正确设置和注册，否则不会自动为新用户配置模型。要使默认模型对新用户可见，您需要：
- 请确保您的
user_default_llm部分已完全取消注释、正确缩进，并符合预期的 YAML 结构。每个模型（聊天、嵌入等）都应位于下 default_models，并且模型和工厂都必须存在于您的中 llm_factories.json，并包含所有必需字段（包括非空的 API 密钥或占位符）[详情和示例]。- 修改后请重启后端/容器。该配置仅影响重启后创建的新用户；现有用户/租户不会追溯更新[来源]。
- 如果模型未出现在 UI 中或不可用，请检查模型是否已注册
llm_factories.json，API 密钥是否为空，以及配置文件是否已正确挂载到容器内 [故障排除]。- 如果您看到“模型未授权”或“没有此模型”错误，则表示即使配置文件中存在该模型，后端数据库中也未向租户注册该模型。您必须手动将该模型添加到租户记录中，或者在更新配置后创建一个新用户[工作流程说明]。
有些版本仅支持一个工厂用于所有默认模型，因此除非您使用的是支持此功能的最新版本，否则您无法混合使用聊天和嵌入的提供商 [功能请求]。
回复时只需提及@dosu即可。
Didn't the correct configuration information already load during startup? There were no errors, and YAML parsing was normal. The user was created after the startup.
配置在启动时正常加载并不保证新用户会自动获得默认模型。RAGFlow 的实际分配流程依赖于两个关键点：
-
模型注册：你在
service_conf.yaml里设置的user_default_llm只是全局默认值，只有当模型和工厂都已在llm_factories.json注册，并且字段（如 API key、base_url）完整时，系统才会在新用户注册时自动分配这些模型。否则，用户登录后还是需要手动添加模型。详细说明 -
配置生效时机：配置变更后，必须重启后端/容器，只有重启后新创建的用户才会自动获得默认模型，已有用户不会自动更新。官方说明
-
常见问题：如果模型未出现在 UI 或不可用，通常是因为模型未注册到
llm_factories.json、API key 为空、配置文件未正确挂载到容器内，或 YAML 结构有误（如缩进、注释未去除）。排查建议 -
版本限制与 bug：部分版本（如 v0.19.x）存在 OpenAI-API-Compatible 工厂无法通过配置自动注册模型的 bug，需手动在
llm_factories.json添加模型并重启。相关问题；近期修复（如 PR #11263）解决了同工厂不同 base_url 的模型分配问题。修复说明 -
多工厂限制：部分版本只支持一个工厂用于所有默认模型，不能混用不同提供商，除非你用的是最新支持多工厂的版本。功能说明
建议排查流程：
- 检查
user_default_llm是否完全取消注释、缩进正确、结构符合模板。 - 检查
llm_factories.json是否已注册所有需要的模型和工厂，字段完整。 - 确认配置文件已正确挂载到容器内，重启后再新建用户测试。
- 如遇“模型未授权”或“无此模型”错误，需手动将模型添加到租户数据库或新建用户。
- 如用 OpenAI-API-Compatible 工厂，优先升级到最新版本或手动注册模型。
To reply, just mention @dosu.
How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other
The llm_factories.json file is typically located at conf/llm_factories.json inside your RAGFlow project directory. In Docker or Kubernetes deployments, it should be mounted into the container at /ragflow/conf/llm_factories.json (as set in your docker-compose.yml or Helm chart) for RAGFlow to recognize it. Both the model and factory must be defined in this file for user_default_llm to work as expected. After editing llm_factories.json, restart the backend or container for changes to take effect—hot-reload is not supported. If the file is missing or not correctly mounted, default models will not be provisioned for new users, even if your config loads without errors.
Reference 1 | Reference 2 | Reference 3
To reply, just mention @dosu.
How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other
llm_factories.json
I need to manually edit the llm_factories.json file in the directory mounted to the ragflow container before it works.
llm_factories.json 文件通常位于 RAGFlow 项目目录下的 conf/llm_factories.json 目录中。在 Docker 或 Kubernetes 部署中，应将其挂载到容器的 /ragflow/conf/llm_factories.json 目录（如 docker-compose.yml 或 Helm chart 中所述），以便 RAGFlow 能够识别它。模型和工厂都必须在此文件中定义，user_default_llm 才能正常工作。编辑 llm_factories.json 文件后，请重启后端或容器以使更改生效——不支持热重载。如果该文件缺失或未正确挂载，即使配置加载无误，也不会为新用户配置默认模型。 参考 1 |参考 2 |参考 3
回复时只需提及@dosu即可。
{
"name": "OpenAI-API-Compatible",
"logo": "",
"tags": "LLM,TEXT EMBEDDING,TEXT RE-RANK,TTS,SPEECH2TEXT,MODERATION",
"status": "1",
"rank": "650",
"llm": [
{
"llm_name": "qwen3-235b-a22b",
"tags": "LLM,CHAT,256k",
"max_tokens": 8192,
"model_type": "chat",
"is_tools": true
},
{
"llm_name": "qwen3-embedding-4b",
"tags": "TEXT EMBEDDING,8K",
"max_tokens": 40960,
"model_type": "embedding"
},
{
"llm_name": "qwen3-reranker-4b",
"tags": "RE-RANK,8k",
"max_tokens": 40960,
"model_type": "rerank"
}
]
}, Why didn't it take effect?
你的配置没有生效，最常见的原因是 OpenAI-API-Compatible 工厂在 llm_factories.json 里的 "llm" 数组为空或没有正确注册模型。RAGFlow 启动时会把 llm_factories.json 里的模型同步到数据库，只有这些模型才会被自动分配给新用户。即使 service_conf.yaml 里的 user_default_llm 配置正确，如果 llm_factories.json 里没有把你的模型（如 qwen3-235b-a22b、qwen3-embedding-4b、qwen3-reranker-4b）加到 OpenAI-API-Compatible 的 "llm" 数组，新用户也不会自动获得这些模型 参考。
正确做法是：
- 手动把你的模型完整添加到 llm_factories.json 里 OpenAI-API-Compatible 的 "llm" 数组。
- 保存后，重启后端或容器（热重载无效）。
- 之后新建用户，应该会自动分配这些模型。
每个模型至少要有 llm_name、model_type，建议加上 max_tokens、is_tools 等字段。只要 llm_factories.json 里有这些模型，且配置挂载路径正确，重启后新用户就能自动获得，无需手动添加 源码分析。
如果还有问题，建议检查 llm_factories.json 是否挂载到 /ragflow/conf/llm_factories.json，且内容和格式无误，重启后再新建用户测试。
To reply, just mention @dosu.
How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other
你的配置没有生效，最常见的原因是 OpenAI-API-Compatible 工厂在 llm_factories.json 里的 "llm" 数组为空或没有正确注册模型。RAGFlow 启动时会把 llm_factories.json 里的模型同步到数据库，只有这些模型才会被自动分配给新用户。即使 service_conf.yaml 里的 user_default_llm 配置正确，如果 llm_factories.json 里没有把你的模型（如 qwen3-235b-a22b、qwen3-embedding-4b、qwen3-reranker-4b）加到 OpenAI-API-Compatible 的 "llm" 数组，新用户也不会自动获得这些模型 参考。
正确做法是：
- 手动把你的模型完整添加到 llm_factories.json 里 OpenAI-API-Compatible 的 "llm" 数组。
- 保存后，重启后端或容器（热重载无效）。
- 之后新建用户，应该会自动分配这些模型。
每个模型至少要有 llm_name、model_type，建议加上 max_tokens、is_tools 等字段。只要 llm_factories.json 里有这些模型，且配置挂载路径正确，重启后新用户就能自动获得，无需手动添加 源码分析。
如果还有问题，建议检查 llm_factories.json 是否挂载到 /ragflow/conf/llm_factories.json，且内容和格式无误，重启后再新建用户测试。
To reply, just mention @dosu.
How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other
{ "name": "OpenAI-API-Compatible", "logo": "", "tags": "LLM,TEXT EMBEDDING,TEXT RE-RANK,TTS,SPEECH2TEXT,MODERATION", "status": "1", "rank": "650", "llm": [ { "llm_name": "qwen3-235b-a22b", "tags": "LLM,CHAT,256k", "max_tokens": 8192, "model_type": "chat", "is_tools": true }, { "llm_name": "qwen3-embedding-4b", "tags": "TEXT EMBEDDING,8K", "max_tokens": 40960, "model_type": "embedding" }, { "llm_name": "qwen3-reranker-4b", "tags": "RE-RANK,8k", "max_tokens": 40960, "model_type": "rerank" } ] } This has already been added to the LLM group and is also attached to the container; I can see this content within the container as well.
你的 llm_factories.json 配置和挂载都没问题，但新用户还是没有自动分配模型，通常有以下几个原因：
-
模型注册到数据库：RAGFlow 启动时会把 llm_factories.json 里的模型同步到数据库，只有这些模型才会被新用户自动分配。你已经把 qwen3-235b-a22b、qwen3-embedding-4b、qwen3-reranker-4b 加到 OpenAI-API-Compatible 的 "llm" 数组，这一步是对的。必须重启后端或容器，热重载无效，只有重启后新建用户才会生效。源码分析
-
YAML 格式和模型名：service_conf.yaml 的 user_default_llm 部分必须完全取消注释、缩进正确，并且 default_models 下的模型名要和 llm_factories.json 里的 llm_name 完全一致。如果有 factory 字段，建议用 "模型名@工厂名" 格式。配置细节
-
base_url 问题：如果你用的是 2025-11-17 之前的版本，OpenAI-API-Compatible 工厂下多个模型（chat、embedding、rerank）会被错误地分配同一个 base_url（chat 的 base_url），导致 embedding/rerank 不能用。这个 bug 已在 PR #11263 修复，建议升级到最新版本。
-
local.service_conf.yaml 覆盖：如果 conf/local.service_conf.yaml 存在且 user_default_llm 配置为空或冲突，会导致主配置被覆盖，模型不会自动分配。建议检查容器内是否有 local.service_conf.yaml 并确认内容无误。配置说明
-
API key 必填：每个模型都需要 api_key，哪怕是占位符（如 "no-key-need"），否则模型不会出现在 UI 或被分配。API key 说明
排查建议：
- 检查 service_conf.yaml 和 llm_factories.json 的模型名、工厂名是否完全一致。
- 检查 base_url 是否分别配置，且版本已包含 PR #11263 修复。
- 检查 local.service_conf.yaml 是否有冲突。
- 重启容器后新建用户测试。
如果以上都确认无误，建议升级到最新 RAGFlow 版本，并用最简配置测试（只留一个 chat 模型），确认能否自动分配。
To reply, just mention @dosu.
How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other
Since there has been no further activity for over three weeks, we will proceed to close this issue. If the problem persists or you have additional questions, please feel free to reopen the issue or create a new one. We’re happy to assist anytime.