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

复杂文档理解与引用检索 · 本章是 RAGFlow DeepWiki 中文译文的独立章节页，保留原始链接、源码锚点、模块标签和章节层级。

项目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

翻译时间：2026-05-27T08:44:37.152Z

翻译模型：deepseek-chat

原文字符数：17064

项目：RAGFlow (ragflow)

---

租户配置与模型管理

目的与范围

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

---

架构总览

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

flowchart TB
    subgraph "租户管理层"
        User["用户/租户<br/>(tenant_id)"]
        TenantLLMTable["TenantLLM 表<br/>每个租户的模型配置"]
        TenantTable["Tenant 表<br/>默认模型选择"]
    end

    subgraph "服务层"
        TenantLLMService["TenantLLMService<br/>增删改查与模型选择"]
        LLM4Tenant["LLM4Tenant<br/>配置解析器"]
        LLMBundle["LLMBundle<br/>带使用量追踪的模型包装器"]
    end

    subgraph "模型工厂注册表"
        LLMTable["LLM 表<br/>来自 conf/llm_factories.json 的已配置模型"]
        LLMFactoriesTable["LLMFactories 表<br/>提供商元数据"]
        ChatModelRegistry["ChatModel 注册表"]
        EmbeddingModelRegistry["EmbeddingModel 注册表"]
        RerankModelRegistry["RerankModel 注册表"]
    end

    subgraph "配置来源"
        ServiceConf["service_conf.yaml<br/>默认 LLM 设置"]
        LLMFactoriesJSON["conf/llm_factories.json<br/>模型与工厂定义"]
    end

    subgraph "模型初始化"
        GetInitTenantLLM["get_init_tenant_llm()<br/>创建默认租户配置"]
        ModelSelection["模型选择逻辑"]
    end

    User -->|"配置模型"| TenantLLMTable
    User -->|"拥有默认模型"| TenantTable
    TenantLLMTable -->|"被查询"| TenantLLMService
    TenantTable --> TenantLLMService

    TenantLLMService -->|"实例化"| LLM4Tenant
    LLM4Tenant -->|"包装"| LLMBundle

    LLMBundle -->|"使用"| ChatModelRegistry
    LLMBundle -->|"使用"| EmbeddingModelRegistry
    LLMBundle -->|"使用"| RerankModelRegistry

    LLMFactoriesJSON -->|"填充"| LLMTable
    LLMFactoriesJSON -->|"填充"| LLMFactoriesTable

    ServiceConf --> GetInitTenantLLM
    GetInitTenantLLM --> TenantLLMTable

    LLMTable -.-> TenantLLMService
    LLMFactoriesTable -.-> TenantLLMService

    ModelSelection -.-> LLM4Tenant

说明：

租户模型配置存储在 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）： 运行一个相似性查询，将示例文本与候选文本进行比较。

如果任意一次调用成功，则将密钥标记为有效并继续保存。否则，返回详细的错误信息。

flowchart TD
    A["调用 set_api_key()"] --> B["按工厂查询模型"]
    B --> C{嵌入向量模型可用？}
    C -- 是 --> D["调用 embedding.encode(['测试...'])"]
    D --> E{成功？}
    E -- 是 --> M["使用 TenantLLMService.filter_update() 保存配置"]
    E -- 否 --> F{聊天模型可用？}
    C -- 否 --> F
    F -- 是 --> G["调用 chat.async_chat_streamly('Hi')"]
    G --> H{成功？}
    H -- 是 --> M
    H -- 否 --> I{重排序模型可用？}
    F -- 否 --> I
    I -- 是 --> J["调用 rerank.similarity(...)"]
    J --> K{成功？}
    K -- 是 --> M
    K -- 否 --> L["返回错误：无效的 API 密钥"]
    I -- 否 --> L
    M --> N["返回成功"]

此过程异步执行并带有超时，如果验证失败则返回详细的错误消息。该验证逻辑在 /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，后者负责处理租户特定的配置解析。

classDiagram
    class LLM4Tenant {
        +tenant_id: 字符串
        +model_config: 字典
        +mdl: 基础模型实例
        +__init__(tenant_id, model_config, lang)
    }

    class LLMBundle {
        +bind_tools(session, tools)
        +encode(texts)
        +encode_queries(query)
        +similarity(query, texts)
        +describe(image)
        +async_chat(system, history, gen_conf)
        +async_chat_streamly(system, history, gen_conf)
    }

    class Base_ChatModel {
        <<接口>>
        +async_chat()
        +async_chat_streamly()
    }

    LLM4Tenant <|-- LLMBundle
    LLMBundle --> Base_ChatModel: 包装实例
    LLMBundle ..> TenantLLMService: 调用 increase_usage_by_id()

行为：

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