agentic_huge_data_base / wiki
页面 RAGFlow · 7.1 接口架构与 SDK·DeepWiki 中文全文译文
DeepWiki 中文译文 / RAGFlow / 7.1

7.1 · 接口架构与 SDK（API Architecture and SDK）

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

项目RAGFlow 章节7.1 状态全文译文 模块接口与服务契约、认证、权限与安全、系统架构、界面与交互
项目要点页2.5 参考项目 项目章节目录RAGFlow DeepWiki 原始章节API Architecture and SDK 上一章7 下一章7.2
源码线索
  • 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/constants.py
  • api/db/init_data.py
  • api/db/joint_services/tenant_model_service.py
模块标签
  • 接口与服务契约
  • 认证、权限与安全
  • 系统架构
  • 界面与交互
  • 测试、发布与运维

章节正文

接口架构与 SDK

原始 DeepWiki 页面https://deepwiki.com/infiniflow/ragflow/7.1-api-architecture-and-sdk

API 架构与 SDK

相关源文件

本章引用的主要源码文件：

  • 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/constants.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
  • api/utils/configs.py
  • common/data_source/jira/connector.py
  • common/http_client.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/opendal_conn.py
  • 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
  • sdk/python/test/conftest.py
  • sdk/python/test/test_frontend_api/common.py
  • sdk/python/test/test_frontend_api/test_chunk.py
  • sdk/python/test/test_frontend_api/test_dataset.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

目的与范围

本文档介绍 RAGFlow 的 RESTful HTTP API 架构和 Python SDK 实现。内容涵盖 API 服务器结构、认证机制（JWT 令牌和 API 密钥）、请求/响应模式、错误处理，以及 Python SDK（ragflow-sdk）如何封装 HTTP 端点以支持程序化访问。

如需了解特定 API 端点及其参数，请参阅 HTTP API 参考文档 docs/references/http_api_reference.md:8-183 和 Python API 参考文档 docs/references/python_api_reference.md:8-245。

API 服务器架构

基于 Quart 的应用框架

RAGFlow 的 API 服务器基于 Quart 构建，这是一个与 Flask API 兼容但支持 async/await 模式的异步 Python Web 框架。应用在 api/apps/__init__.py 中初始化。

应用初始化流程

RAGFlow · 基于 Quart 的应用框架 · 图 1
RAGFlow · 基于 Quart 的应用框架 · 图 1

来源：api/apps/__init__.py:60-85, api/utils/api_utils.py:135-150, api/apps/sdk/session.py:147, api/apps/sdk/doc.py:54

服务器支持以下特性：

  • 异步请求处理：用于非阻塞 I/O 操作，对长时间运行的 RAG 任务尤为关键。
  • 扩展超时：默认超时时间延长至 600 秒，以适应大语言模型（LLM）的慢响应或大型文档处理 api/apps/__init__.py:70-73。
  • CORS：全局启用跨域资源共享 api/apps/__init__.py:61。
  • OpenAPI/Swagger：通过 QuartSchema 自动生成和校验模式 api/apps/__init__.py:64。
  • 全局错误处理：未处理的异常由 server_error_response 捕获，该函数会对 Unauthorized（401）或 index_not_found_exception（提示需要解析）等错误进行分类 api/utils/api_utils.py:135-150。

认证系统

双认证机制

RAGFlow 在 _load_user 代理中实现了两种并行的认证方法，以同时支持 Web 会话和程序化 API 访问。

认证流程示意图

RAGFlow · 双认证机制 · 图 2
RAGFlow · 双认证机制 · 图 2

来源：api/apps/__init__.py:96-191, api/utils/api_utils.py:41-45, api/db/db_models.py:25-26

JWT 令牌认证（Web 界面）

用于 Web 前端。_load_user 函数尝试使用基于系统 SECRET_KEY 的 Serializer 从 Authorization 请求头中解码令牌 api/apps/__init__.py:130-149。

API 密钥认证（程序化访问）

用于 SDK 客户端和第三方集成。如果 JWT 解码失败，系统会将请求头视为 API 密钥，并查询 APIToken 表 api/apps/__init__.py:171-174。此方法会设置 g.auth_via_api_token = True api/apps/__init__.py:179。

HTTP API 结构

请求与响应标准化

RAGFlow 遵循 RESTful 约定，在重构旧端点时确保向后兼容 docs/release_notes.md:45-47, 85-86。

  • 请求解析：_coerce_request_data 工具函数使用合理的默认值获取 JSON 请求体，必要时回退到表单数据 api/utils/api_utils.py:62-90。
  • 响应格式：响应通常通过 get_json_result api/utils/api_utils.py:141 或 get_result api/apps/sdk/session.py:90 进行封装。
  • OpenAI 兼容性：RAGFlow 在 /api/v1/openai/{chat_id}/chat/completions 提供 OpenAI 兼容接口 docs/references/http_api_reference.md:62。标准 OpenAI 客户端只需更改 base_url 即可与 RAGFlow 交互 docs/references/python_api_reference.md:77。
已废弃的 API 别名

为确保平滑过渡到统一的 RESTful API，RAGFlow 为多个 v0.24.0 路径维护了向后兼容层 docs/references/http_api_reference.md:30-52。

Python SDK 架构

SDK 结构与模块

ragflow-sdk 是 REST API 的面向对象封装，按功能组织为特定模块。

SDK 到代码实体的映射

RAGFlow · SDK 结构与模块 · 图 3
RAGFlow · SDK 结构与模块 · 图 3

来源：sdk/python/ragflow_sdk/ragflow.py:27, sdk/python/ragflow_sdk/modules/session.py:21, api/apps/sdk/session.py:24-31, api/apps/sdk/doc.py:25

关键 SDK 操作
  • 会话与聊天：SDK 区分标准 RAG 聊天和可视化工作流代理。create_agent_session 初始化基于代理的对话 api/apps/sdk/session.py:57-90。
  • 文档与数据集：DataSet 模块管理知识库，包括设置片段切分方法（例如 naive、qa、manual）和解析器配置 docs/references/python_api_reference.md:127-181。
  • 流式支持：SDK 支持标准和代理补全的流式响应，遵循服务器发送事件（SSE）模式 docs/references/http_api_reference.md:143-168。

汇总表：SDK 到 API 的映射

功能SDK 方法HTTP 端点
创建数据集RAGFlow.create_dataset()POST /api/v1/datasets docs/references/python_api_reference.md:127
下载文档Document.download()GET /api/v1/datasets/{dataset_id}/documents/{document_id} api/apps/sdk/doc.py:54
创建代理会话RAGFlow.create_agent_session()POST /api/v1/agents/{agent_id}/sessions api/apps/sdk/session.py:57
删除会话RAGFlow.delete_datasets()DELETE /api/v1/agents/{agent_id}/sessions api/apps/sdk/session.py:93
开始解析DataSet.parse()POST /api/v1/datasets/{dataset_id}/chunks api/apps/sdk/doc.py:174
聊天补全client.chat.completions.create()POST /api/v1/openai/{chat_id}/chat/completions docs/references/http_api_reference.md:62

来源：api/apps/sdk/session.py:57-93, api/apps/sdk/doc.py:54-174, docs/references/http_api_reference.md:62, docs/references/python_api_reference.md:127