# 对话与聊天API

1. 目的与范围 #

本文档涵盖了Ragflow-Plus中管理对话和聊天交互的REST API端点和服务层。对话系统为用户提供了与RAG引擎交互的主要接口，支持多种聊天模式，包括普通对话、文档编写辅助和直接知识库查询。

有关底层对话配置和提示管理的信息，请参阅对话系统。有关知识库搜索和检索功能，请参阅RAG引擎与搜索。

2. API架构概述 #

对话API通过主API应用程序实现，支持流式聊天、文件上传和知识库集成。

2.1 系统架构图 #

相关源代码文件：

• api/apps/api_app.py (45-670行)
• api/db/services/dialog_service.py (38-575行)

3. 核心聊天API端点 #

对话API提供用于聊天完成、对话管理、文件处理和知识库操作的端点，通过API令牌进行认证。

3.1 认证和令牌 #

所有API请求都需要通过Authorization头传递API令牌进行认证。令牌通过/new_token端点创建，并与特定的对话（dialog）关联。

3.1.1 令牌管理端点 #

3.1.2 认证流程 #

# 请求头格式
Authorization: Bearer <api_token>

# 令牌验证
token = request.headers.get("Authorization").split()[1]
objs = APIToken.query(token=token)
if not objs:
    return get_json_result(
        data=False, 
        message='Authentication error: API key is invalid!"', 
        code=settings.RetCode.AUTHENTICATION_ERROR
    )

3.2 对话管理 #

对话管理端点允许创建、检索和管理用户对话会话。

3.2.1 对话端点 #

3.2.2 对话数据结构 #

interface Conversation {
  id: string;
  dialog_id: string;
  name: string;
  message: Message[];
  reference: Reference[];
  create_date: number;
  update_date: number;
}

interface Message {
  role: "user" | "assistant" | "system";
  content: string;
  id?: string;
  doc_ids?: string[];  // 知识库文件ID
  temp_file_ids?: string[];  // 临时文件ID
}

3.3 文档和文件操作 #

系统支持两种文件上传模式：临时文件上传（用于聊天上下文）和知识库文件上传（用于持久化存储）。

3.3.1 文件上传端点 #

3.3.2 临时文件集成 #

系统通过ITempFileInfo接口支持临时文件上传用于聊天上下文：

interface ITempFileInfo {
  file_id: string;
  filename: string;
  size: number;
  content_type: string;
}

3.4 知识库操作 #

知识库操作端点允许直接查询和搜索知识库内容。

3.4.1 知识库端点 #

4. 流式聊天实现 #

/completion端点使用服务器发送事件（SSE）提供实时流式响应，支持完整的RAG集成和引用支持。

4.1 SSE流式流程 #

流式响应通过Server-Sent Events（SSE）实现，允许客户端实时接收LLM生成的文本块。

4.1.1 流式响应格式 #

def stream():
    nonlocal dia, msg, req, conv
    try:
        for ans in chat(dia, msg, True, **req):
            fillin_conv(ans)
            rename_field(ans)
            yield "data:" + json.dumps({
                "code": 0, 
                "message": "", 
                "data": ans
            }, ensure_ascii=False) + "\n\n"
        API4ConversationService.append_message(conv.id, conv.to_dict())
    except Exception as e:
        yield "data:" + json.dumps({
            "code": 500, 
            "message": str(e), 
            "data": {
                "answer": "**ERROR**: " + str(e), 
                "reference": []
            }
        }, ensure_ascii=False) + "\n\n"
    yield "data:" + json.dumps({
        "code": 0, 
        "message": "", 
        "data": True
    }, ensure_ascii=False) + "\n\n"

4.1.2 响应头配置 #

if req.get("stream", True):
    resp = Response(stream(), mimetype="text/event-stream")
    resp.headers.add_header("Cache-control", "no-cache")
    resp.headers.add_header("Connection", "keep-alive")
    resp.headers.add_header("X-Accel-Buffering", "no")
    resp.headers.add_header("Content-Type", "text/event-stream; charset=utf-8")
    return resp

4.2 响应装饰和引用 #

引用系统使用编号标记（##N$$）链接到特定的知识库分块。

4.2.1 引用数据结构 #

interface Reference {
  chunks: Array<{
    content: string;
    content_ltks: string;  // 带标记的内容
    docnm_kwd: string;     // 文档名称关键词
    doc_id: string;
    image_id?: string;     // MinIO图像标识符
    vector?: number[];     // 嵌入向量
  }>;
  doc_aggs: Array<{
    doc_id: string;
    doc_name: string;
    count: number;
  }>;
}

interface ConversationResponse {
  answer: string;
  reference: Reference;
  audio_binary?: string;  // TTS输出（十六进制格式）
  prompt?: string;
  created_at: number;
}

4.2.2 图像和MinIO集成 #

图像通过MinIO路径引用，并转换为可访问的URL：

// 图像URL生成
const protocol = MINIO_CONFIG.secure ? "https" : "http";
const img_url = `${protocol}://${MINIO_CONFIG.visit_point}/${img_path}`;

5. 管理和监控API #

管理系统提供用于监控用户对话和分析聊天历史的管理API。

5.1 管理端点 #

5.2 数据库查询 #

管理服务执行复杂的查询，连接dialog和conversation表以提供全面的对话分析：

-- 按用户获取对话（tenant_id）
SELECT d.id, d.name, d.create_date, d.update_date, d.tenant_id
FROM dialog d
WHERE d.tenant_id = %s
ORDER BY d.update_date DESC

-- 获取对话消息
SELECT id, message, name 
FROM conversation 
WHERE dialog_id = %s
ORDER BY create_date DESC

相关源代码文件：

• management/server/routes/conversation/routes.py (6-47行)
• management/server/services/conversation/service.py (5-201行)

6. 客户端集成模式 #

前端实现了全面的聊天功能，包括临时文件上传、流式响应和富内容渲染。

6.1 消息输入组件 #

MessageInput组件支持不同文件类型的双上传模式：

6.2 流式聊天Hooks #

前端使用专门的hooks处理不同的流式端点：

// 临时文件上传hook
const useUploadTempFile = () => {
  const mutateAsync = async (params: { file: File; conversationId?: string }) => {
    const formData = new FormData();
    formData.append('file', params.file);
    if (params.conversationId) {
      formData.append('conversation_id', params.conversationId);
    }

    const response = await chatService.uploadTempFile(formData);
    return response.data as ITempFileInfo;
  };
};

6.3 Markdown内容渲染 #

MarkdownContent组件处理引用显示和图像集成：

6.4 跨语言搜索集成 #

聊天配置支持跨语言搜索功能：

// 助手设置配置
<Form.Item
  label={t('crossLanguageSearch')}
  name={['prompt_config', 'cross_language_search']}
  valuePropName="checked"
  initialValue={false}
>
  <Switch />
</Form.Item>

6.5 认证和请求处理 #

客户端实现了带有令牌管理的全面请求拦截器：

// 带有Authorization头的请求拦截器
request.interceptors.request.use((url: string, options: any) => {
  return {
    url,
    options: {
      ...options,
      headers: {
        ...(options.skipToken 
          ? undefined 
          : { [Authorization]: getAuthorization() }),
        ...options.headers,
      },
    },
  };
});

相关源代码文件：

• web/src/components/message-input/index.tsx (104-510行)
• web/src/hooks/temp-file-hooks.ts (12-68行)
• web/src/pages/chat/markdown-content/index.tsx (55-247行)
• web/src/pages/chat/chat-configuration-modal/assistant-setting.tsx (122-129行)
• web/src/utils/request.ts (80-99行)

7. 错误处理和恢复 #

对话API实现了全面的错误处理，用于处理各种故障场景，包括LLM API故障、知识库检索错误和流式中断。

7.1 常见错误模式 #

1. LLM API密钥问题：通过检查响应中的"invalid key"来检测
2. 知识库错误：知识库使用不同的嵌入模型
3. 流式中断：客户端中止控制器管理
4. SQL查询失败：使用错误上下文自动重试

系统提供优雅降级，当高级功能失败时回退到更简单的聊天模式。

相关源代码文件：

• api/db/services/dialog_service.py (325-327行, 565-566行)
• api/apps/conversation_app.py (230-233行)

8. 总结 #

对话与聊天API为Ragflow-Plus提供了完整的对话交互功能，包括：

• 流式响应：通过SSE实现实时文本生成
• 文件管理：支持临时文件和知识库文件上传
• 引用系统：自动生成和显示知识库引用
• 错误处理：全面的错误处理和优雅降级
• 跨语言支持：支持多语言搜索和翻译

这些功能共同构成了一个强大且用户友好的对话系统，能够有效利用知识库内容提供准确的响应。