5.4 · 租户配置与模型管理（Tenant Configuration and Model Management）

复杂文档理解与引用检索 · 聚焦本章的模块关系、源码依据与实现要点。

项目RAGFlow 章节5.4 状态全文译文模块系统架构、接口与服务契约、文档对象与元数据、检索、召回与索引

项目要点页2.5 参考项目项目章节目录RAGFlow DeepWiki 原始章节Tenant Configuration and Model Management 上一章5.3 下一章5.5

源码线索

api/apps/llm_app.py
api/db/services/tenant_llm_service.py
conf/llm_factories.json
rag/llm/__init__.py
rag/llm/chat_model.py
rag/llm/cv_model.py
rag/llm/embedding_model.py
rag/llm/ocr_model.py
rag/llm/rerank_model.py
rag/llm/sequence2txt_model.py

模块标签

系统架构
接口与服务契约
文档对象与元数据
检索、召回与索引
模型调用与提供方适配

章节正文

租户配置与模型管理

原始 DeepWiki 页面https://deepwiki.com/infiniflow/ragflow/5.4-tenant-configuration-and-model-management

租户配置与模型管理

目的与范围

本文档介绍 RAGFlow 如何通过多租户大语言模型（LLM）管理系统，让租户配置和管理自己的模型。内容涵盖存储在 tenant_llm 表中的租户特定模型配置、系统级与工厂级默认值之间的关系，以及从模型选择到初始化的完整生命周期。同时说明 API 密钥的验证方式，以及如何实现按租户进行使用量追踪。

架构总览

RAGFlow 的租户模型管理系统封装了配置管理、服务逻辑、模型工厂注册和初始化。下图展示了关键组件及数据流。

RAGFlow · 架构总览 · 图 1

说明：

租户模型配置存储在 tenant_llm 表中；默认配置位于 tenant 表中。
TenantLLMService 处理增删改查操作，并选择正确的模型配置。
LLM4Tenant 通过合并租户设置、服务默认值和工厂信息来解析配置。
LLMBundle 包装基于提供商的模型类（来自 ChatModel、EmbeddingModel、RerankModel 注册表），并添加使用量追踪功能。
JSON 文件 conf/llm_factories.json 定义了系统范围内有效的模型及其属性。
在创建租户时，get_init_tenant_llm() 使用 service_conf.yaml 填充默认的 tenant_llm 行。
使用量追踪由 TenantLLMService 管理，在模型调用期间更新 Token 使用量计数器。

来源： api/db/services/llm_service.py:85-91 api/db/services/tenant_llm_service.py:23-23 api/apps/llm_app.py:79-156

数据库模式

tenant_llm 表

tenant_llm 表维护每个租户的大语言模型（LLM）配置，使租户能够灵活设置不同的 API 密钥、模型名称和其他参数。

字段	类型	说明
`id`	字符串	唯一配置 ID
`tenant_id`	字符串	租户标识符（引用 `tenant.id`）
`llm_factory`	字符串	提供商名称（例如 "OpenAI"、"Anthropic"）
`llm_name`	字符串	工厂内的模型名称（例如 "gpt-4o"）
`model_type`	字符串	模型用途类型：chat、embedding、rerank、TTS 等
`api_key`	字符串	API 密钥字符串或 JSON 编码的认证对象
`api_base`	字符串	可选的自定义 API 端点基础 URL
`max_tokens`	整数	LLM 请求的最大 Token 限制
`used_tokens`	大整数	累计 Token 使用量计数器

说明：

api_key 字段很灵活。有些提供商期望简单的字符串，另一些则期望包含多个凭证或参数的 JSON 字符串。
used_tokens 用于追踪计费或配额管理目的的 Token 总消耗量。
此模式允许租户独立管理凭证和模型选择。

来源： api/db/db_models.py:27-27 api/db/services/tenant_llm_service.py:23-23

API 密钥验证流程

在持久化租户 API 密钥之前，RAGFlow 会通过尝试对所选模型进行实际 API 调用来验证密钥。这可以减少配置错误，改善租户体验。

验证步骤

查询正在配置的 llm_factory 的所有模型。
对于每种模型类型（embedding、chat、rerank），尝试进行示例调用：
- 嵌入向量（Embedding）： 编码一个测试字符串，确保返回有效的嵌入向量。
- 聊天（Chat）： 发起一个简单的聊天请求，流式输出 "Hi"，以确认响应能力。
- 重排序（Rerank）： 运行一个相似性查询，将示例文本与候选文本进行比较。
如果任意一次调用成功，则将密钥标记为有效并继续保存。否则，返回详细的错误信息。

RAGFlow · 验证步骤 · 图 2

此过程异步执行并带有超时，如果验证失败则返回详细的错误消息。该验证逻辑在 /set_api_key 端点中实现 api/apps/llm_app.py:79-156。

特殊认证格式

某些工厂在模型实例化时需要 JSON 格式的凭证：

工厂	JSON 键字段	详情
Azure-OpenAI	`api_key`、`api_version`	嵌入在 API 密钥 JSON 中，用于 SDK 初始化
Fish Audio	`fish_audio_ak`、`fish_audio_refid`	提取 API 密钥部分用于 TTS 客户端设置
腾讯云	`tencent_cloud_sid`、`tencent_cloud_sk`	在 sequence2txt 模型中用于认证

这些在各自工厂的模型类中处理 rag/llm/embedding_model.py:153-159、rag/llm/tts_model.py:148-157 和 rag/llm/sequence2txt_model.py:212-214。

来源： api/apps/llm_app.py:79-156 rag/llm/embedding_model.py:153-159 rag/llm/tts_model.py:148-157 rag/llm/sequence2txt_model.py:212-214

模型选择与初始化

LLMBundle 包装器类

LLMBundle 是一个关键类，它包装租户的底层 LLM 实例，并在调用时增加使用量追踪功能。它继承自 LLM4Tenant，后者负责处理租户特定的配置解析。

RAGFlow · LLMBundle 包装器类 · 图 3

行为：

LLM4Tenant 根据租户配置初始化 LLM 提供商类，并合并默认值。
LLMBundle 覆盖关键的 LLM 调用：在将调用转发给模型（mdl）后，通过 TenantLLMService.increase_usage_by_id() 更新使用量计数。
这种设计确保所有租户 API 调用都能透明地增加使用量计数器。

来源： api/db/services/llm_service.py:85-364 api/db/services/tenant_llm_service.py:27-27

Token 使用量追踪

RAGFlow 通过 tenant_llm 表中的 used_tokens 字段，按租户和模型追踪 LLM 的 Token 使用量。

Token 计数实现

不同的模型类型通过库特定的属性或辅助函数报告 Token 使用量：

模型类型	Token 计数方法	代码位置
聊天（Chat）	`total_token_count_from_response(response)`	`rag/llm/chat_model.py:34-34`
嵌入向量（Embedding）	`total_token_count_from_response(res)`	`rag/llm/embedding_model.py:107-107`
重排序（Rerank）	`total_token_count_from_response(res)`	`rag/llm/rerank_model.py:75-75`
视觉（Vision）	`response.usage.total_tokens`	`rag/llm/cv_model.py:148-148`

所有使用量增量都通过 TenantLLMService.increase_usage_by_id() 异步且原子性地完成。

来源： rag/llm/chat_model.py:34-34 rag/llm/embedding_model.py:107-107 rag/llm/rerank_model.py:75-75 rag/llm/cv_model.py:148-148

租户 LLM 配置的 API 端点

RAGFlow 通过 llm_app.py 蓝图暴露 HTTP API 端点，用于管理租户 LLM 配置和 API 密钥：

GET /factories

返回支持的 LLM 工厂及其模型类型，并按租户使用情况进行过滤 api/apps/llm_app.py:49-71。

POST /set_api_key

通过模拟调用核心模型类型来验证租户的 API 密钥；成功后将密钥和配置保存到 tenant_llm 中 api/apps/llm_app.py:76-156。

POST /add_llm

添加单个自定义 LLM 配置，并与租户关联 api/apps/llm_app.py:159-162。

GET /my_llms

列出租户设置的所有 LLM 配置 api/apps/llm_app.py:388-390。

这些端点支持租户自助管理模型。

来源： api/apps/llm_app.py:49-471

配置文件格式：conf/llm_factories.json

此 JSON 文件枚举了工厂注册表使用的所有模型和元数据。它为每个提供商定义了可用的模型、其能力、最大 Token 限制以及相关标签。

示例片段：

{
  "factory_llm_infos": [
    {
      "name": "OpenAI",
      "llm": [
        {
          "llm_name": "gpt-5.2-pro",
          "tags": "LLM,CHAT,400k,IMAGE2TEXT",
          "max_tokens": 400000,
          "model_type": "chat",
          "is_tools": true
        }
      ]
    }
  ]
}

这里的模型属性会影响选择和初始化，并会被加载到服务层访问的数据库表中。

来源： conf/llm_factories.json:1-110

总结

RAGFlow 的租户配置与模型管理系统使每个租户能够自定义使用哪些 LLM 模型、独立管理 API 密钥，并追踪使用量。这是通过分层配置合并实现的——从服务级默认值，到租户默认选择，再到 tenant_llm 表中租户特定的详细 LLM 配置。模型通过结合租户配置与工厂元数据进行实例化。在接受模型配置之前，API 密钥会通过实际调用其分配的模型进行验证。使用统计信息会在每次 LLM 调用期间透明地更新。整个工作流由 HTTP API 端点支持，用于租户自助服务和系统化配置管理。

这种详细的配置设计使 RAGFlow 能够支持多租户场景，实现隔离的 LLM 凭证、灵活的模型选择以及可靠的使用量核算。

来源：

api/db/services/llm_service.py:85-364
api/db/services/tenant_llm_service.py:23-27
api/apps/llm_app.py:49-471
rag/llm/chat_model.py:1-181、rag/llm/embedding_model.py:1-154、rag/llm/rerank_model.py:1-179、rag/llm/cv_model.py:1-175
conf/llm_factories.json:1-110
web/src/pages/user-setting/setting-model/index.tsx:1-241