当前位置： 首页 > news >正文

【RAGFlow代码详解-25】HTTP 接口

news 2025/8/27 13:01:39

认证

所有 HTTP API 端点都需要使用 API 密钥进行持有者令牌身份验证。身份验证机制在
api/utils/api_utils.py 290-306 中
通过 token_required 装饰器实现，该装饰器根据存储在数据库中的 APIToken 模型验证令牌。

@token_required
def endpoint_function(tenant_id):# tenant_id is automatically injected after successful authentication
API 密钥在 Authorization 标头中传递：Authorization: Bearer <YOUR_API_KEY>

API 架构概述

HTTP API 是使用具有模块化蓝图结构的 Flask 构建的。每个主要功能区域都作为 api/apps/sdk/ 下的单独应用程序模块实现。

基于蓝图的 Flask 架构
在这里插入图片描述

核心 API 类别

数据集管理

数据集终结点处理知识库生命周期作，包括创建、更新和删除。主要实现位于
api/apps/sdk/dataset.py

关键端点：

  • POST /api/v1/datasets - 创建数据集（ dataset.py 56 ）
  • GET /api/v1/datasets - 列出数据集 （ dataset.py 381 ）
  • PUT /api/v1/datasets/{dataset_id} - 更新数据集 （ dataset.py 254 ）
  • DELETE /api/v1/datasets - 删除数据集 （ dataset.py 158 ）
    GET /api/v1/datasets/{dataset_id}/knowledge_graph - 获取数据集的知识图谱 （ dataset.py 476 ）
    DELETE /api/v1/datasets/{dataset_id}/knowledge_graph - 删除数据集的知识图谱 （ dataset.py 516 ）

数据集创建过程通过
api/utils/api_utils.py 479-529 验证
verify_embedding_availability() 嵌入模型，并通过 get_parser_config（） api/utils/api_utils.py 352-394 应用默认解析器配置

文档管理

文档端点管理数据集中的文件上传、处理和检索。实现跨度
api/apps/sdk/doc.py 69-680

关键端点：

  • POST /api/v1/datasets/{dataset_id}/documents - 上传文件 （ doc.py 69 ）
  • GET /api/v1/datasets/{dataset_id}/documents - 列出文件 （ doc.py 415 ）
  • PUT /api/v1/datasets/{dataset_id}/documents/{document_id} - 更新文件 （ doc.py 175 ）
  • GET /api/v1/datasets/{dataset_id}/documents/{document_id} - 下载文档 （ doc.py 355 ）
  • DELETE /api/v1/datasets/{dataset_id}/documents - 删除文档 （ doc.py 572 ）

文档处理是通过块端点启动的：

POST /api/v1/datasets/{dataset_id}/chunks - 开始解析文档 （ doc.py 682 ）
DELETE /api/v1/datasets/{dataset_id}/chunks - 停止解析文档 （ doc.py 765 ）

块管理

块终结点提供对文档段及其元数据的细粒度控制。主要业务包括：

  • GET /api/v1/datasets/{dataset_id}/documents/{document_id}/chunks - 列表块 （ doc.py 836 ）
  • POST /api/v1/datasets/{dataset_id}/documents/{document_id}/chunks - 添加块 （ doc.py 1048 ）
  • PUT /api/v1/datasets/{dataset_id}/documents/{document_id}/chunks/{chunk_id} - 更新块 （ doc.py 1171 ）
  • DELETE /api/v1/datasets/{dataset_id}/documents/{document_id}/chunks - 删除块 （ doc.py 1276 ）

聊天助手管理

聊天端点通过
api/apps/sdk/chat.py 处理对话式 AI 助手配置

关键端点：

  • POST /api/v1/chats - 创建聊天助手（ chat.py 30 ）
  • GET /api/v1/chats - 列出聊天助手 （ chat.py 271 ）
  • PUT /api/v1/chats/{chat_id} - 更新聊天助手 （ chat.py 147 ）
  • DELETE /api/v1/chats - 删除聊天助手 （ chat.py 228 ）

会话管理

会话端点处理聊天助手和代理的对话会话。实现在
api/apps/sdk/session.py

聊天会话：
  • POST /api/v1/chats/{chat_id}/sessions - 使用聊天助手创建会话（ session.py 37 ）
  • GET /api/v1/chats/{chat_id}/sessions - 列出聊天助手的会话 （ session.py 480 ）
  • PUT /api/v1/chats/{chat_id}/sessions/{session_id} - 更新会话 （ session.py 97 ）
  • DELETE /api/v1/chats/{chat_id}/sessions - 删除会话 （ session.py 595 ）
代理会话：
  • POST /api/v1/agents/{agent_id}/sessions - 创建与代理的会话 （ session.py 66 ）
  • GET /api/v1/agents/{agent_id}/sessions - 列出代理会话 （ session.py 534 ）
  • DELETE /api/v1/agents/{agent_id}/sessions - 删除代理会话 （ session.py 643 ）
对话终结点：
  • POST /api/v1/chats/{chat_id}/completions - 与聊天助手交谈 （ session.py 119 ）
  • POST /api/v1/agents/{agent_id}/completions - 与代理人交谈 （ session.py 442 ）
  • POST /api/v1/sessions/ask - 询问数据集 （ session.py 695 ）
OpenAI 兼容 API

RAGFlow 提供与 OpenAI 兼容的聊天完成端点，遵循与 OpenAI 的 API 相同的请求/响应格式，从而可以直接替代现有的 OpenAI 集成。这两个端点都在
api/apps/sdk/session.py 中实现

端点：

  • POST /api/v1/chats_openai/{chat_id}/chat/completions - 聊天完成 （ session.py 148 ）
  • POST /api/v1/agents_openai/{agent_id}/chat/completions - 代理完成 （ session.py 381 ）

这两个端点都支持与 OpenAI API 格式相同的流式处理和非流式处理响应，包括使用情况统计数据和通过 tiktoken 进行令牌计数。

请求/响应流

完整的 API 请求处理管道

在这里插入图片描述
OpenAI 兼容流式传输

在这里插入图片描述

错误处理

API 使用通过 api/utils/api_utils.py 中的实用程序函数实现的标准化错误响应格式：

功能目的HTTP 状态重新编码
get_result()成功响应 200 0
get_error_argument_result()参数无效400101
get_error_data_result()数据验证错误400102
get_error_permission_result()授权失败403403
server_error_response()内部错误500500

完整的错误代码参考

法典消息描述
0成功成功完成
101参数错误请求参数无效
102数据错误数据验证或业务逻辑错误
109身份验证错误API 密钥或令牌无效
403禁止访问被拒绝
500内部服务器错误服务器内部错误
1001块 ID 无效块 ID 无效
1002块更新失败块更新失败

所有回复均遵循标准化格式：

{"code": 0,"message": "success", "data": {...}
}

错误响应包括特定的错误消息：

{"code": 102,"message": "Dataset name 'example' already exists"
}

Python SDK 集成

sdk/python/ragflow_sdk/ 中的 Python SDK 提供了一个直接映射到 HTTP API 端点的高级接口。RAGFlow 类 ragflow.py 26 封装了 HTTP 客户端功能：

class RAGFlow:def __init__(self, api_key, base_url, version="v1"):self.api_url = f"{base_url}/api/{version}"self.authorization_header = {"Authorization": f"Bearer {api_key}"}

SDK 模块直接对应于 API 端点类别：

  • DataSet 类→ /datasets 终结点
  • 文档类→ /documents 端点
  • 聊天类→ /chats 终结点
  • 块类 → /chunks 端点

SDK 自动处理身份验证、请求序列化、错误处理和响应反序列化，提供比直接 HTTP API 使用更用户友好的界面。

http://www.dtcms.com/a/352466.html

相关文章：

  • VGG改进（5）：基于Multi-Scale Attention的PyTorch实战
  • 解析xml文件并录入数据库
  • 给高斯DB写一个函数实现oracle中GROUPING_ID函数的功能
  • 分布式锁；Redlock
  • 【世纪龙科技】职业院校汽车职业体验中心建设方案
  • imx6ull-驱动开发篇43——I.MX6U 的 I2C 驱动分析
  • 如何在ubuntu下制作linux镜像
  • 深度学习之卷积神经网络原理（cnn）
  • AT_abc401_f [ABC401F] Add One Edge 3
  • Rocky9配置完VMware桥接模式后没有自动获取IP
  • 系统架构设计师-【2025上半年论文题目分享】
  • 六足机器人系统设计与实现cad＋设计说明书＋电路原图模式＋装配图＋电路图
  • Java设计模式之《状态模式》
  • 从根源解决 VMware 每次重启 Windows 系统后无法进行复制文件等操作的问题
  • 矩阵的秩几何含义
  • openssh 版本回退
  • Spring Ai （Function Calling / Tool Calling） 工具调用
  • 78-dify案例分享-零基础上手 Dify TTS 插件！从开发到部署免费文本转语音，测试 + 打包教程全有
  • 使用【阿里云百炼】搭建自己的大模型
  • Linux网络设备分析
  • 构建绿色园区新方案：能源监测+用电安全的综合能源管理系统
  • LeetCode - 227. 基本计算器 II
  • C++ `std::map` 解析：`find`, `end`, `insert` 和 `operator[]`
  • redis 在 nodejs 中如何应用？
  • 常用 Kubernetes (K8s) 命令指南
  • DevSecOps 集成 CI/CD Pipeline：实用指南
  • 【RAGFlow代码详解-30】构建系统和 CI/CD
  • 【智能化解决方案】大模型智能推荐选型系统方案设计
  • 简明 | ResNet特点、残差模块、残差映射理解摘要
  • VGVLP思路探索和讨论