Python SDK

相关源文件

• api/apps/sdk/agent.py
• api/apps/sdk/chat.py
• api/apps/sdk/dataset.py
• api/apps/sdk/session.py
• api/utils/api_utils.py
• api/utils/validation_utils.py
• docs/references/http_api_reference.md
• docs/references/python_api_reference.md
• sdk/python/ragflow_sdk/ragflow.py
• sdk/python/test/test_http_api/test_dataset_mangement/conftest.py
• sdk/python/test/test_http_api/test_dataset_mangement/test_create_dataset.py
• sdk/python/test/test_http_api/test_dataset_mangement/test_update_dataset.py

Python SDK 通过客户端库提供了一个用于与 RAGFlow 核心功能交互的程序化接口。本文档涵盖了 SDK 的架构、核心类以及与后端 HTTP API 的集成模式。

有关底层 HTTP API 端点的信息，请参阅HTTP API。有关通用 API 参考文档，请参阅API 参考。

SDK 架构概述

Python SDK 遵循客户端-服务器架构，其中 RAGFlow 类充当所有操作的主要入口点，通过 HTTP 请求与后端服务进行通信。

客户端-服务器通信流程

来源： sdk/python/ragflow_sdk/ragflow.py26-284 api/apps/sdk/dataset.py53-501 api/apps/sdk/chat.py30-323 api/apps/sdk/agent.py28-129 api/apps/sdk/session.py39-690

SDK 模块结构

来源： sdk/python/ragflow_sdk/ragflow.py51-284 docs/references/python_api_reference.md89-1185

核心类和认证

RAGFlow 客户端类

RAGFlow 类是主要入口点，通过 API 密钥和基本 URL 配置处理认证。

方法	目的	返回值
__init__(api_key, base_url, version)	使用凭据初始化客户端	RAGFlow 实例
post(path, json, stream, files)	HTTP POST 请求	响应对象
get(path, params, json)	HTTP GET 请求	响应对象
put(path, json)	HTTP PUT 请求	响应对象
delete(path, json)	HTTP DELETE 请求	响应对象

身份验证流程

来源： sdk/python/ragflow_sdk/ragflow.py27-49 api/utils/api_utils.py284-301 api/apps/sdk/session.py39-41

数据集管理

SDK 通过 DataSet 类和 RAGFlow 客户端方法提供全面的数据集操作。

数据集操作架构

来源： sdk/python/ragflow_sdk/ragflow.py51-110 api/apps/sdk/dataset.py53-501

数据集类结构

DataSet 类封装了数据集特有的操作和文档管理。

方法	目的	后端端点
upload_documents(document_list)	上传文档到数据集	POST /datasets/{id}/documents
list_documents(...)	列出数据集中的文档	GET /datasets/{id}/documents
delete_documents(ids)	按 ID 删除文档	DELETE /datasets/{id}/documents
async_parse_documents(document_ids)	异步解析文档	POST /datasets/{id}/chunks
async_cancel_parse_documents(document_ids)	取消文档解析	DELETE /datasets/{id}/chunks

来源： docs/references/python_api_reference.md369-719

聊天和会话管理

聊天创建和管理

来源： sdk/python/ragflow_sdk/ragflow.py112-188 api/apps/sdk/chat.py30-323 api/apps/sdk/session.py39-690

会话管理流程

来源： api/apps/sdk/chat.py32-144 api/apps/sdk/session.py39-175

Agent 系统集成

Agent 操作

SDK 通过对后端 Agent 服务的直接 API 调用提供 Agent 管理功能

来源： sdk/python/ragflow_sdk/ragflow.py248-284 api/apps/sdk/agent.py48-129

检索和搜索操作

检索系统架构

来源： sdk/python/ragflow_sdk/ragflow.py190-226 docs/references/python_api_reference.md902-985

分块管理

SDK 通过 Document 类提供分块级别的操作。

操作	SDK 方法	目的
添加	Document.add_chunk(content, keywords)	向文档添加新分块
列表	Document.list_chunks(keywords, page, page_size)	检索带过滤的分块
更新	Chunk.update(update_message)	修改分块内容/关键词
删除	Document.delete_chunks(chunk_ids)	按 ID 删除分块

来源： docs/references/python_api_reference.md727-897

错误处理与验证

SDK 错误处理

来源： sdk/python/ragflow_sdk/ragflow.py74-78 api/utils/validation_utils.py30-102 api/utils/api_utils.py284-301

当后端操作失败时，SDK 会持续引发 Python 异常，错误消息从 HTTP 响应的 message 字段中提取。这为所有 SDK 操作提供了统一的错误处理接口。

来源： sdk/python/ragflow_sdk/ragflow.py78 sdk/python/ragflow_sdk/ragflow.py84 sdk/python/ragflow_sdk/ragflow.py110 sdk/python/ragflow_sdk/ragflow.py168