5 · LLM 集成系统（LLM Integration System）

LLM 集成系统

大语言模型（LLM）集成系统

相关源文件

以下文件为本维基页面的生成提供了上下文：

• api/apps/llm_app.py
• conf/llm_factories.json
• internal/entity/models/aliyun.go
• internal/entity/models/deepseek.go
• internal/entity/models/dummy.go
• internal/entity/models/gitee.go
• internal/entity/models/google.go
• internal/entity/models/lmstudio.go
• internal/entity/models/minimax.go
• internal/entity/models/moonshot.go
• internal/entity/models/ollama.go
• internal/entity/models/siliconflow.go
• internal/entity/models/types.go
• internal/entity/models/vllm.go
• internal/entity/models/volcengine.go
• internal/entity/models/zhipu-ai.go
• internal/handler/providers.go
• internal/service/model_service.go
• rag/llm/__init__.py
• rag/llm/chat_model.py
• rag/llm/cv_model.py
• rag/llm/embedding_model.py
• rag/llm/rerank_model.py
• rag/llm/sequence2txt_model.py
• rag/llm/tts_model.py
• web/src/components/svg-icon.tsx
• web/src/constants/llm.ts
• web/src/pages/user-setting/setting-model/constant.ts
• web/src/utils/common-util.ts

大语言模型（LLM）集成系统提供了一个统一的抽象层，用于与多个商业和开源AI提供商进行交互。该系统管理租户特定的配置、模型选择，并实现横切关注点，包括错误处理、重试逻辑、使用跟踪以及模型特定的行为策略。系统支持七种模型类型：对话、嵌入向量、重排序、视觉（图像到文本）、文本到语音（TTS）、语音到文本（ASR）和OCR。

有关该系统具体组件的详细信息，请参阅子页面：

• LLMBundle 和模型类型 —— 记录 LLMBundle 抽象、模型类型系统（CHAT、EMBEDDING、RERANK、TTS 等）以及工厂模式的实现。
• 提供商实现 —— 详细介绍具体的提供商实现（OpenAI、Anthropic、DeepSeek、本地模型）以及它们如何向工厂注册。
• 错误处理和重试逻辑 —— 解释复杂的错误分类系统、带有指数退避的重试策略以及错误分类。
• 租户配置和模型管理 —— 记录租户如何配置自己的模型、tenant_llm 表与模型选择之间的关系以及初始化过程。
• 工具调用和函数使用 —— 解释工具绑定机制、函数模式生成以及大语言模型（LLM）在对话补全过程中如何调用外部工具。

架构总览

大语言模型（LLM）集成系统采用分层架构，将高层的租户请求桥接到低层的提供商API。

系统架构：大语言模型（LLM）集成层

架构描述：配置源自 conf/llm_factories.json，该文件列出了可用的工厂、模型和能力。api/apps/llm_app.py 中的API层处理租户特定的请求，例如设置API密钥和获取可用工厂，并通过尝试对相应模型进行示例调用来实时验证API密钥的有效性。服务层（LLMBundle、LLMService、TenantLLMService）根据租户的配置和请求的模型类型，编排模型实例化并将请求路由到正确的模型类。系统通过在运行时检查提供商模块，将模型动态注册到 ChatModel、EmbeddingModel 和 RerankModel 等注册表中。提供商实现通过继承基础模型类来实现其特定的API客户端和行为。

来源：api/apps/llm_app.py:49-130、rag/llm/__init__.py:141-158、rag/llm/chat_model.py:113-150、rag/llm/embedding_model.py:36-183、rag/llm/rerank_model.py:29-147、conf/llm_factories.json:1-180

模型类型系统

RAGFlow 将AI能力分类为特定的模型类型，每种类型都由一个基础接口类定义，并注册到专用的模型注册表中：

每个基础类都定义了其模型类型的抽象接口和通用逻辑。具体的提供商实现会继承这些基础类，并在其工厂名称下注册到相应的注册表字典中。这种设计使得可以按类型和提供商轻松查找和实例化模型。

有关详细的抽象、模型类型定义和工厂模式，请参阅 LLMBundle 和模型类型。

来源：rag/llm/__init__.py:141-158、rag/llm/chat_model.py:113-150、rag/llm/embedding_model.py:36-183、rag/llm/rerank_model.py:29-147、rag/llm/cv_model.py:42-176、rag/llm/tts_model.py:68-187、rag/llm/sequence2txt_model.py:32-167

提供商实现

RAGFlow 支持多种提供商，从而能够扩展多个商业API和本地部署。提供商实现作为基础模型类的子类实现模型驱动程序，并通过 _FACTORY_NAME 属性向工厂系统注册。

一些主要的提供商包括：

• OpenAI：支持大多数模型类型，包括对话、嵌入向量、重排序、TTS 等。
• Anthropic：基于对话的模型。
• DeepSeek：视觉和对话服务。
• Siliconflow：一个专门支持多种模型类型的提供商。
• VolcEngine：另一个支持对话的提供商。
• 本地模型：Ollama、Xinference、LM Studio 等，支持本地或私有部署。

在模块导入时（在 rag/llm/__init__.py 中），通过导入其实现模块并扫描具有 _FACTORY_NAME 属性的类来动态发现提供商。然后，这些类以工厂名称为键，注册到相应的模型注册表（ChatModel、EmbeddingModel 等）中 rag/llm/__init__.py:162-181。

有关具体提供商实现和注册的全面描述，请参阅 提供商实现。

提供商注册序列图

来源：rag/llm/__init__.py:25-65、rag/llm/__init__.py:162-181、rag/llm/embedding_model.py:89-189、rag/llm/rerank_model.py:29-147

错误处理和重试逻辑

由于网络问题、速率限制或API提供商错误，容错对于可靠的大语言模型（LLM）集成至关重要。

• 错误分类：Base 对话模型类实现了 _classify_error 方法，该方法从异常消息中检测错误类别。它将关键字映射到枚举，例如：
  • ERROR_RATE_LIMIT
  • ERROR_AUTHENTICATION
  • ERROR_INVALID_REQUEST
  • ERROR_SERVER
  • ERROR_TIMEOUT
  • ERROR_CONNECTION
  • ERROR_CONTENT_FILTER
  • ERROR_MODEL
  • ERROR_QUOTA
  • 以及其他 rag/llm/chat_model.py:130-150。

• 重试策略：重试逻辑使用从环境变量配置的参数，如 max_retries 和 base_delay，并通过 _get_delay() 实现指数或随机退避 rag/llm/chat_model.py:120-129。

• 模型特定策略：某些模型在 _apply_model_family_policies 中透明地应用特殊的配置调整。例如，对于 Qwen3 系列模型，在非流式请求上禁用"思考"功能；对于 Kimi-k2.5 系列，调整温度或推理标志 rag/llm/chat_model.py:64-110。

这种分层错误处理确保临时故障会触发重试，而永久性或配额问题会立即引发异常。

有关错误类型、重试逻辑及其实现的深入讨论，请参阅 错误处理和重试逻辑。

来源：rag/llm/chat_model.py:39-51、rag/llm/chat_model.py:120-129、rag/llm/chat_model.py:130-150、rag/llm/chat_model.py:64-110

租户配置和模型管理

RAGFlow 中的每个租户都管理自己存储于 TenantLLM 数据库表中的大语言模型（LLM）配置 api/db/db_models.py:27。

• API 密钥管理：租户通过 /set_api_key API 端点添加或更新API密钥和基础URL api/apps/llm_app.py:76-160。该端点：
  • 通过对嵌入向量、对话和重排序模型执行测试调用来验证提供的API密钥。
  • 在保存之前验证实时连接性和访问权限。
  • 更新数据库中的租户配置，以供后续模型使用。

• 模型初始化：系统在初始设置期间（api/db/init_data.py 中的 init_superuser 方法）为超级用户预填充默认模型和配置，以确保开箱即用的工作环境。

• 模型查找：模型的命名约定支持复合名称，例如 model@instance@provider。Go 服务层（internal/service/model_service.go）包含解析和管理此命名方案的功能，以便为租户请求定位正确的模型实例。

这种设计允许每个租户无缝地自定义其可用模型、API密钥并选择首选提供商。

有关租户模型管理、数据库关系和初始化的全面详细信息，请参阅 租户配置和模型管理。

来源：api/apps/llm_app.py:76-156、api/db/db_models.py:27、api/db/init_data.py:50-95、internal/service/model_service.go:32-210

工具调用和函数使用

某些对话模型能够在对话生成过程中调用外部工具或函数。

• 对话基础模型维护一个 is_tools 标志和一个 tools 列表，用于保存工具定义和关联的可调用函数 rag/llm/chat_model.py:123-126。
• 活跃的工具调用会话在 toolcall_sessions 中跟踪，用于管理多轮工具交互 rag/llm/chat_model.py:125。
• 系统通过查询租户大语言模型（LLM）配置或全局工厂信息来确定模型是否支持工具 api/apps/llm_app.py:32-46。
• 工具调用使大语言模型（LLM）能够在对话补全中请求执行特定领域的操作（例如，数据库查询、API调用），从而促进更丰富的交互模式。

有关工具绑定机制、函数模式生成以及在对话期间执行的完整详细信息，请参阅 工具调用和函数使用。

来源：conf/llm_factories.json:16、rag/llm/chat_model.py:124-126、api/apps/llm_app.py:32-46

本概述总结了 RAGFlow 中大语言模型（LLM）集成系统的核心概念和架构，展示了复杂的模型交互如何被模块化并按租户进行配置，同时支持多样化和可扩展的提供商和模型类型集合。

有关实现细节、深入的技术解释和高级使用模式，请查阅与每个子主题关联的链接子页面。