7 · 后端接口系统（Backend API System）

后端接口系统

7. 后端 API 系统

相关源文件

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

• admin/server/admin_server.py
• api/apps/__init__.py
• api/apps/backward_compat.py
• api/apps/restful_apis/chunk_api.py
• api/apps/sdk/dify_retrieval.py
• api/apps/sdk/doc.py
• api/apps/sdk/session.py
• api/db/init_data.py
• api/db/joint_services/tenant_model_service.py
• api/ragflow_server.py
• api/settings.py
• api/utils/api_utils.py
• conf/service_conf.yaml
• docker/service_conf.yaml.template
• docs/references/http_api_reference.md
• docs/references/python_api_reference.md
• docs/release_notes.md
• rag/utils/redis_conn.py
• sdk/python/ragflow_sdk/modules/__init__.py
• sdk/python/ragflow_sdk/modules/agent.py
• sdk/python/ragflow_sdk/modules/base.py
• sdk/python/ragflow_sdk/modules/chat.py
• sdk/python/ragflow_sdk/modules/chunk.py
• sdk/python/ragflow_sdk/modules/dataset.py
• sdk/python/ragflow_sdk/modules/document.py
• sdk/python/ragflow_sdk/modules/session.py
• sdk/python/ragflow_sdk/ragflow.py
• test/testcases/test_http_api/test_dataset_management/test_dify_retrieval_routes_unit.py
• test/testcases/test_http_api/test_file_management_within_dataset/test_doc_sdk_routes_unit.py
• test/testcases/test_web_api/test_chunk_app/test_chunk_routes_unit.py
• test/testcases/test_web_api/test_system_app/test_apps_init_unit.py

概述

后端 API 系统通过 RESTful HTTP 端点和 Python SDK 提供对 RAGFlow 功能的编程访问。它使开发者能够管理数据集、文档、聊天助手、智能体，并执行检索增强生成（RAG）工作流，而无需使用 Web 界面。API 遵循 REST 约定，并包含与 OpenAI 兼容的端点，以便与现有的大语言模型（LLM）工具无缝集成。

该系统基于 Quart 框架构建，该框架提供了 Flask API 的异步实现。这使得 RAGFlow 能够高效处理用于流式大语言模型（LLM）响应的长连接和并发后台任务 api/apps/__init__.py:60-73。

有关可视化工作流系统和基于画布的智能体编排的信息，请参见智能体与工作流系统。有关使用这些 API 的 Web 前端的详细信息，请参见前端应用。

范围与目的

本页面涵盖以下内容：

• 整体 API 架构和设计模式。
• 请求/响应格式和错误处理。
• 跨功能域的端点组织。
• Python SDK 结构和设计。
• OpenAI 兼容层。

具体端点类别的详细说明在子页面中提供：

• API 架构与 SDK — 记录 API 设计、请求/响应模式、SDK 结构和 OpenAPI 兼容性。
• 认证与授权 — 解释认证流程（JWT、OAuth、API 令牌）、@login_required 装饰器和 current_user 代理。
• 用户与租户管理 — 记录用户注册、OAuth 集成、基于 OTP 的密码重置流程和多租户架构。
• 数据集与知识库 API — 详细说明数据集的增删改查操作、解析器配置、元数据设置和知识库管理端点。
• 文档与文件管理 API — 解释文档上传、解析触发、文件层级结构、元数据更新以及文件与文档之间的关系。
• 聊天与会话 API — 记录聊天补全端点、会话管理、流式响应和检索增强生成（RAG）检索流程。
• 智能体与记忆 API — 详细说明智能体/画布管理端点和用于持久化智能体状态的记忆系统 API。
• 系统状态与健康监控 — 解释健康检查端点、组件状态报告、任务执行器心跳监控以及 MCP 服务器集成。

API 层架构

后端 API 的结构将路由逻辑与业务逻辑和数据库操作分离开来。

标题：API 层架构

来源： api/apps/sdk/session.py:56-57，api/apps/sdk/doc.py:172-174，api/utils/api_utils.py:153-180，rag/utils/redis_conn.py:60-115

请求处理流程

每个 API 请求都遵循标准化的处理管线，以确保安全性和一致性。

1. 认证：API 请求通常使用 @token_required 装饰器 api/apps/sdk/session.py:56。该装饰器会根据 APIToken 表校验 Authorization: Bearer <API_KEY> 请求头 api/apps/__init__.py:170-184。
2. 请求解析：辅助函数 get_request_json() api/utils/api_utils.py:92-93 会异步获取 JSON 请求体，它使用 _coerce_request_data() 来处理各种内容类型并缓存结果 api/utils/api_utils.py:62-90。
3. 校验：处理器使用 validate_request 函数确保载荷中存在必填字段 api/utils/api_utils.py:153-176。
4. 业务逻辑：处理器调用特定的服务。例如，create_agent_session 会初始化一个 Canvas 对象，并通过 API4ConversationService 保存会话 api/apps/sdk/session.py:73-88。
5. 响应格式化：成功结果通过 get_result(data=...) 返回 api/utils/api_utils.py:214-215，而错误则使用 get_data_error_result() api/utils/api_utils.py:120-132。

来源： api/apps/sdk/session.py:56-90，api/utils/api_utils.py:62-93，api/apps/__init__.py:129-188

标准响应与错误码

RAGFlow 使用统一的响应信封。成功通过 HTTP 200 和 JSON 请求体中的特定代码表示。

来源： docs/references/http_api_reference.md:14-26，api/utils/api_utils.py:120-132

Python SDK 与对象映射

ragflow-sdk 提供了面向对象的接口，该接口镜像了 REST API 的层级结构，将自然语言空间桥接到代码实体。

标题：SDK 到后端的映射

主要特性：

• 资源管理：高级方法，如 create_dataset docs/references/python_api_reference.md:126-135 和 delete_datasets docs/references/python_api_reference.md:228-232。
• 配置：允许在创建时设置 chunk_method（例如 naive、qa、paper）和 parser_config docs/references/python_api_reference.md:165-181。
• OpenAI 集成：SDK 允许通过 base_url 将标准的 OpenAI 客户端指向 RAGFlow 端点 docs/references/python_api_reference.md:73-77。

来源： docs/references/python_api_reference.md:124-212，api/apps/sdk/session.py:147-158

OpenAI 兼容层

RAGFlow 实现了一个兼容层，允许标准的大语言模型（LLM）客户端与 RAGFlow 的"聊天"和"智能体"进行交互。

• 端点路径：
  • 聊天：/api/v1/openai/{chat_id}/chat/completions docs/references/http_api_reference.md:62。
  • 为向后兼容保留了旧版别名 docs/references/http_api_reference.md:32-38。
• 扩展参数：支持 extra_body 用于 RAG 特定的功能，例如 reference（返回引用来源）和 metadata_condition（用于复杂的检索过滤）docs/references/http_api_reference.md:90-113。
• 流式传输：通过 stream: true 参数支持服务器发送事件（SSE），该功能使用 Quart 的 Response 并设置 mimetype="text/event-stream" 实现 docs/references/http_api_reference.md:127-130。

来源： docs/references/http_api_reference.md:30-114，api/apps/sdk/session.py:147-158

部署与配置

API 服务器通过 service_conf.yaml 配置，并在 ragflow_server.py 中初始化。

• 端口：主 API 服务器默认监听端口 9380 conf/service_conf.yaml:3。
• 管理服务器：一个独立的管理 API 运行在端口 9381 上 conf/service_conf.yaml:6。
• 初始化：服务器通过 init_database_tables() 初始化数据库表，并根据需要通过 init_superuser() 设置默认超级用户 api/ragflow_server.py:105-126。
• 存储：根据配置文件建立与 MySQL/OceanBase、Redis 以及文档存储（ES/Infinity）的连接 conf/service_conf.yaml:7-46。
• 进度跟踪：后台线程 update_progress 会定期运行，以同步数据库中文档解析的状态 api/ragflow_server.py:53-69。

来源： conf/service_conf.yaml:1-46，api/ragflow_server.py:53-154，api/db/init_data.py:27-50