RAGFlow API开发：构建自定义RAG应用的完整指南-优快云博客

RAGFlow API开发：构建自定义RAG应用的完整指南

【免费下载链接】ragflow RAGFlow是一个基于深度文档理解的开源RAG（检索增强生成）引擎。项目地址: https://gitcode.com/GitHub_Trending/ra/ragflow

本文全面介绍了RAGFlow的RESTful API接口体系，涵盖了从知识库管理、文档处理到智能对话的完整RAG工作流。RAGFlow采用分层架构设计，遵循RESTful最佳实践，提供了知识库管理、文档处理、智能对话、文件管理等核心API端点。文章详细解析了API的认证授权机制、错误处理规范以及高级功能如知识图谱和检索测试API，为开发者构建基于RAGFlow的智能应用提供了完整指南。

RESTful API接口全面解析

RAGFlow提供了一套完整且强大的RESTful API接口，让开发者能够轻松集成RAG能力到自己的应用中。这些API覆盖了从知识库管理、文档处理到智能对话的完整RAG工作流。

API架构设计

RAGFlow的API采用分层架构设计，遵循RESTful最佳实践：

mermaid

核心API端点分类

RAGFlow的API端点按照功能模块进行组织，主要分为以下几大类：

1. 知识库管理API

知识库是RAGFlow的核心概念，相关API提供了完整的知识库生命周期管理：

端点	方法	功能描述	参数示例
`/api/v1/datasets`	POST	创建知识库	`{"name": "技术文档", "description": "公司技术文档库"}`
`/api/v1/datasets/{dataset_id}`	PUT	更新知识库	`{"name": "更新后的名称"}`
`/api/v1/datasets`	GET	列出知识库	`page=1&page_size=20`
`/api/v1/datasets/{dataset_id}`	DELETE	删除知识库	-

示例代码：创建知识库

import requests

def create_dataset(api_key, base_url, name, description):
    headers = {
        'Authorization': f'Bearer {api_key}',
        'Content-Type': 'application/json'
    }
    payload = {
        'name': name,
        'description': description
    }
    response = requests.post(
        f'{base_url}/api/v1/datasets',
        headers=headers,
        json=payload
    )
    return response.json()

# 使用示例
api_key = 'your_api_key_here'
base_url = 'http://localhost:80'
result = create_dataset(api_key, base_url, '产品文档', '公司产品相关文档集合')
print(result)

2. 文档处理API

文档处理API负责将各种格式的文档转换为RAG可用的知识片段：

端点	方法	功能描述	支持格式
`/api/v1/datasets/{dataset_id}/documents`	POST	上传文档	PDF, DOCX, TXT, PPTX
`/api/v1/datasets/{dataset_id}/documents/{document_id}`	GET	获取文档详情	-
`/api/v1/datasets/{dataset_id}/documents`	GET	列出文档	`status=parsed`
`/api/v1/datasets/{dataset_id}/documents/{document_id}/parse`	POST	触发文档解析	-

文档处理流程： mermaid

3. 智能对话API

智能对话API提供基于知识库的问答能力，支持流式和非流式响应：

兼容接口：

def chat_completion(api_key, base_url, dataset_id, message, stream=False):
    headers = {
        'Authorization': f'Bearer {api_key}',
        'Content-Type': 'application/json'
    }
    payload = {
        'model': 'ragflow-model',
        'messages': [{'role': 'user', 'content': message}],
        'stream': stream
    }
    
    response = requests.post(
        f'{base_url}/api/v1/chats_openai/{dataset_id}/chat/completions',
        headers=headers,
        json=payload,
        stream=stream
    )
    
    if stream:
        return handle_stream_response(response)
    else:
        return response.json()

# 流式响应处理
def handle_stream_response(response):
    for line in response.iter_lines():
        if line:
            decoded_line = line.decode('utf-8')
            if decoded_line.startswith('data:'):
                data = decoded_line[5:].strip()
                if data == '[DONE]':
                    break
                yield json.loads(data)

4. 文件管理API

文件管理API提供统一的文件上传、下载和管理功能：

端点	方法	功能描述	使用场景
`/api/v1/files`	POST	上传文件	批量文档上传
`/api/v1/files/{file_id}`	GET	下载文件	文档检索
`/api/v1/files`	GET	列出文件	文件管理
`/api/v1/files/{file_id}`	DELETE	删除文件	清理无用文件

认证与授权

RAGFlow使用Bearer Token进行API认证，所有请求都需要在Header中包含有效的API密钥：

Authorization: Bearer your_api_key_here
Content-Type: application/json

API密钥管理端点：

POST /api/v1/tokens - 创建新的API密钥
GET /api/v1/tokens - 列出所有API密钥
DELETE /api/v1/tokens/{token} - 删除API密钥

错误处理与状态码

RAGFlow遵循标准的HTTP状态码规范，并提供详细的错误信息：

状态码	错误代码	描述	解决方案
400	1001	无效的块ID	检查chunk_id参数
401	-	未授权访问	检查API密钥有效性
403	-	访问被拒绝	检查权限设置
404	-	资源不存在	检查资源ID
500	-	服务器内部错误	查看服务器日志

错误响应示例：

{
    "code": 1001,
    "message": "Invalid Chunk ID",
    "details": "The provided chunk ID does not exist in the database"
}

高级功能API

知识图谱API

def get_knowledge_graph(api_key, base_url, dataset_id):
    headers = {'Authorization': f'Bearer {api_key}'}
    response = requests.get(
        f'{base_url}/api/v1/datasets/{dataset_id}/knowledge_graph',
        headers=headers
    )
    return response.json()

检索测试API

def retrieval_test(api_key, base_url, dataset_id, query):
    headers = {
        'Authorization': f'Bearer {api_key}',
        'Content-Type': 'application/json'
    }
    payload = {'query': query}
    response = requests.post(
        f'{base_url}/api/v1/datasets/{dataset_id}/retrieval_test',
        headers=headers,
        json=payload
    )
    return response.json()

性能优化建议

批量操作：使用批量API减少请求次数
流式响应：对于长文本生成使用流式API
缓存策略：合理缓存频繁访问的数据
连接池：使用HTTP连接池提高性能

客户端集成示例

Python SDK风格封装：

class RAGFlowClient:
    def __init__(self, base_url, api_key):
        self.base_url = base_url.rstrip('/')
        self.api_key = api_key
        self.session = requests.Session()
        self.session.headers.update({
            'Authorization': f'Bearer {api_key}',
            'Content-Type': 'application/json'
        })
    
    def create_dataset(self, name, description):
        payload = {'name': name, 'description': description}
        response = self.session.post(
            f'{self.base_url}/api/v1/datasets',
            json=payload
        )
        return response.json()
    
    def upload_document(self, dataset_id, file_path):
        with open(file_path, 'rb') as f:
            files = {'file': f}
            response = self.session.post(
                f'{self.base_url}/api/v1/datasets/{dataset_id}/documents',
                files=files
            )
        return response.json()
    
    def chat(self, dataset_id, message, stream=False):
        payload = {
            'model': 'ragflow',
            'messages': [{'role': 'user', 'content': message}],
            'stream': stream
        }
        response = self.session.post(
            f'{base_url}/api/v1/chats_openai/{dataset_id}/chat/completions',
            json=payload,
            stream=stream
        )
        return response

通过这套完整的RESTful API，开发者可以轻松构建基于RAGFlow的智能应用，实现文档管理、知识检索和智能对话等核心功能。API设计遵循行业标准，提供了良好的扩展性和易用性。

Python SDK集成与使用示例

RAGFlow提供了功能强大的Python SDK，让开发者能够轻松地将RAG能力集成到自己的应用中。本节将详细介绍如何安装、配置和使用RAGFlow Python SDK，并通过丰富的代码示例展示其核心功能。

安装与配置

首先，通过pip安装RAGFlow Python SDK：

pip install ragflow-sdk

SDK的主要依赖包括：

requests>=2.30.0,<3.0.0 - 用于HTTP请求处理
beartype>=0.18.5,<0.19.0 - 提供类型检查和运行时验证

初始化客户端

要使用RAGFlow SDK，首先需要初始化客户端实例：

from ragflow_sdk import RAGFlow

# 初始化RAGFlow客户端
api_key = "your_api_key_here"  # 从RAGFlow管理界面获取
base_url = "http://localhost:80"  # RAGFlow服务器地址

rag = RAGFlow(api_key=api_key, base_url=base_url)

数据集管理

数据集是RAGFlow的核心概念，用于存储和管理文档数据。以下是数据集操作的完整示例：

# 创建数据集
dataset = rag.create_dataset(
    name="技术文档库",
    description="存储公司技术文档和API参考",
    chunk_method="manual",  # 支持多种分块方法
    permission="team"  # 权限控制
)

print(f"数据集创建成功，ID: {dataset.id}")

# 上传文档到数据集
documents = []
with open("technical_guide.pdf", "rb") as file:
    documents.append({
        "display_name": "技术指南.pdf",
        "blob": file.read()
    })

uploaded_docs = dataset.upload_documents(documents)
print(f"成功上传 {len(uploaded_docs)} 个文档")

# 列出数据集中的文档
docs_list = dataset.list_documents(
    page=1, 
    page_size=20,
    orderby="create_time",
    desc=True
)

for doc in docs_list:
    print(f"文档: {doc.name}, 创建时间: {doc.create_time}")

智能对话配置

RAGFlow支持创建智能对话助手，以下是如何配置和使用的示例：

from ragflow_sdk.modules.chat import Chat

# 配置LLM参数
llm_config = Chat.LLM(
    rag,
    {
        "model_name": "glm-4-flash@ZHIPU-AI",
        "temperature": 0.1,
        "top_p": 0.3,
        "presence_penalty": 0.4,
        "frequency_penalty": 0.7,
        "max_tokens": 512,
    }
)

# 创建对话助手
chat_assistant = rag.create_chat(
    name="技术支持助手",
    dataset_ids=[dataset.id],
    llm=llm_config
)

print(f"对话助手创建成功，ID: {chat_assistant.id}")

文档检索与问答

RAGFlow的核心功能是智能检索和问答，以下是如何使用的示例：

# 直接检索文档内容
retrieved_chunks = rag.retrieve(
    dataset_ids=[dataset.id],
    question="如何配置API认证？",
    similarity_threshold=0.2,
    top_k=10
)

print("检索到的相关内容：")
for chunk in retrieved_chunks:
    print(f"- {chunk.content[:100]}...")

# 完整的问答流程
session = rag.create_session(chat_assistant.id)
response = session.chat("请解释一下OAuth2.0的工作原理")

print(f"助手回复: {response.message}")
if response.references:
    print("引用文档:")
    for ref in response.references:
        print(f"- {ref.document_name}: {ref.content[:50]}...")

高级功能：智能代理

RAGFlow还支持创建智能代理来处理复杂任务：

# 创建智能代理
agent_dsl = {
    "name": "文档分析代理",
    "description": "自动分析文档结构并提取关键信息",
    "workflow": [
        {
            "type": "document_analysis",
            "parameters": {
                "extract_headings": True,
                "extract_keywords": True,
                "generate_summary": True
            }
        }
    ]
}

rag.create_agent(
    title="文档分析专家",
    dsl=agent_dsl,
    description="专门用于文档结构分析和内容提取的智能代理"
)

# 列出所有可用代理
agents = rag.list_agents()
for agent in agents:
    print(f"代理: {agent.title} - {agent.description}")

错误处理与最佳实践

在使用SDK时，建议采用以下错误处理模式：

try:
    # 尝试创建数据集
    dataset = rag.create_dataset("重要文档库")
    
    # 批量操作时的错误处理
    documents_to_upload = [...]  # 文档列表
    for doc_info in documents_to_upload:
        try:
            dataset.upload_documents([doc_info])
        except Exception as e:
            print(f"文档上传失败: {doc_info['display_name']}, 错误: {e}")
            continue
            
except Exception as e:
    print(f"操作失败: {e}")
    # 可以根据错误类型进行特定处理
    if "already exists" in str(e):
        print("数据集已存在，尝试获取现有数据集")
        dataset = rag.get_dataset("重要文档库")

性能优化建议

对于大规模应用，考虑以下性能优化策略：

# 使用分页处理大量数据
page_size = 100
page = 1
all_datasets = []

while True:
    datasets = rag.list_datasets(page=page, page_size=page_size)
    if not datasets:
        break
    all_datasets.extend(datasets)
    page += 1

# 批量操作优化
def batch_upload_documents(dataset, document_paths, batch_size=10):
    for i in range(0, len(document_paths), batch_size):
        batch = document_paths[i:i+batch_size]
        documents = []
        for path in batch:
            with open(path, "rb") as f:
                documents.append({
                    "display_name": os.path.basename(path),
                    "blob": f.read()
                })
        dataset.upload_documents(documents)

完整的集成示例

下面是一个完整的应用集成示例，展示了如何构建一个基于RAGFlow的文档问答系统：

import os
from ragflow_sdk import RAGFlow
from ragflow_sdk.modules.chat import Chat

class DocumentQASystem:
    def __init__(self, api_key, base_url):
        self.rag = RAGFlow(api_key=api_key, base_url=base_url)
        self.dataset = None
        self.chat_assistant = None
        
    def setup_knowledge_base(self, dataset_name, document_folder):
        """设置知识库"""
        try:
            self.dataset = self.rag.create_dataset(
                name=dataset_name,
                description="企业知识文档库",
                chunk_method="manual"
            )
            
            # 上传所有文档
            document_paths = [
                os.path.join(document_folder, f) 
                for f in os.listdir(document_folder) 
                if f.endswith(('.pdf', '.docx', '.txt'))
            ]
            
            for path in document_paths:
                with open(path, "rb") as f:
                    self.dataset.upload_documents([{
                        "display_name": os.path.basename(path),
                        "blob": f.read()
                    }])
                    
        except Exception as e:
            print(f"知识库设置失败: {e}")
            raise
            
    def create_assistant(self, assistant_name):
        """创建对话助手"""
        llm_config = Chat.LLM(
            self.rag,
            {
                "model_name": "glm-4-flash@ZHIPU-AI",
                "temperature": 0.1,
                "max_tokens": 1024
            }
        )
        
        self.chat_assistant = self.rag.create_chat(
            name=assistant_name,
            dataset_ids=[self.dataset.id],
            llm=llm_config
        )
        
    def ask_question(self, question):
        """提问并获取答案"""
        if not self.chat_assistant:
            raise ValueError("请先创建对话

【免费下载链接】ragflow RAGFlow是一个基于深度文档理解的开源RAG（检索增强生成）引擎。项目地址: https://gitcode.com/GitHub_Trending/ra/ragflow

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考