From 6be019082e2ca2f2d23a2fa987d9355035b4b9b8 Mon Sep 17 00:00:00 2001 From: wanghanlin <1533525126@qq.com> Date: Tue, 18 Aug 2026 09:57:49 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=90=8C=E6=AD=A5=E5=AF=B9=E8=AF=9D?= =?UTF-8?q?=E6=8E=A5=E5=8F=A3=E8=BF=81=E7=A7=BB=E4=B8=8E=20OpenAI=20SSE=20?= =?UTF-8?q?=E6=A0=BC=E5=BC=8F=E8=AF=B4=E6=98=8E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - README.md、SDK-INTEGRATION.md、client/README.md、client/CLAUDE.md 四处接口表更新为新路径 /ai/chat、/ai/chat/stream、/ai/chat/sources - 补充流式接口 OpenAI Chat Completions SSE 格式说明（data: JSON chunk + data: [DONE]） - 删除废弃的 /ai/assistant_app/* 路径与 rag/sync 描述 --- README.md | 10 +++++----- SDK-INTEGRATION.md | 9 ++++----- client/CLAUDE.md | 4 ++-- client/README.md | 24 ++++++++++++------------ 4 files changed, 23 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index f3dc0f9..a5eb006 100644 --- a/README.md +++ b/README.md @@ -114,13 +114,13 @@ CREATE TABLE knowledge_document ( | 方法 | 路径 | 说明 | |------|------|------| -| GET | `/ai/assistant_app/chat/sync` | 同步对话 | -| GET | `/ai/assistant_app/chat/sse` | SSE 流式对话 (Flux) | -| GET | `/ai/assistant_app/chat/server_sent_event` | SSE 流式对话 (ServerSentEvent) | -| GET | `/ai/assistant_app/chat/sse_emitter` | SSE 流式对话 (SseEmitter) | -| GET | `/ai/assistant_app/chat/rag/sync` | RAG 知识库对话（支持查询重写策略） | +| GET | `/ai/chat` | 同步对话（`enableRag=true` 时走 RAG 增强） | +| GET | `/ai/chat/stream` | SSE 流式对话（OpenAI Chat Completions 兼容格式，输出 `data: {"choices":[{"delta":{"content":"..."}}]}` 分片，结束 `data: [DONE]`） | +| GET | `/ai/chat/sources` | RAG 引用来源 | | GET | `/ai/product_info_app/chat/sync` | 商品信息结构化提取 | +> **已废弃（向后兼容保留）**：`/ai/assistant_app/chat/sync`、`/ai/assistant_app/chat/sse`、`/ai/assistant_app/chat/rag/sync`、`/ai/assistant_app/chat/rag/sse`、`/ai/assistant_app/rag/sources` 仍可用，请统一迁移到 `/ai/chat`、`/ai/chat/stream`、`/ai/chat/sources`。`/ai/assistant_app/chat/server_sent_event` 与 `/ai/assistant_app/chat/sse_emitter` 已移除。 + ### 知识库管理接口 | 方法 | 路径 | 说明 | diff --git a/SDK-INTEGRATION.md b/SDK-INTEGRATION.md index 5403664..9990ca8 100644 --- a/SDK-INTEGRATION.md +++ b/SDK-INTEGRATION.md @@ -276,10 +276,9 @@ POST /open-api/auth/token | 接口 | 方法 | 说明 | |---|---|---| -| `/ai/assistant_app/chat/sync` | GET | 同步对话（已统一为 ChatPipeline，支持普通/RAG 自动判断） | -| `/ai/assistant_app/chat/sse` | GET | SSE 流式对话（已统一为 ChatPipeline） | -| `/ai/assistant_app/chat/rag/sse` | GET | RAG 增强流式对话（已统一为 ChatPipeline） | -| `/ai/assistant_app/rag/sources` | GET | 获取 RAG 引用来源 | +| `/ai/chat` | GET | 同步对话（已统一为 ChatPipeline，支持普通/RAG 自动判断） | +| `/ai/chat/stream` | GET | SSE 流式对话（OpenAI Chat Completions 兼容格式，已统一为 ChatPipeline） | +| `/ai/chat/sources` | GET | 获取 RAG 引用来源 | | `/ai/sdk/conversation/list` | GET | 会话列表 | | `/ai/sdk/conversation/{id}/messages` | GET | 会话消息 | | `/ai/sdk/conversation/{id}` | DELETE | 删除会话 | @@ -287,7 +286,7 @@ POST /open-api/auth/token | `/category/tree` | GET | 知识库分类树 | | `/feedback` | POST | 消息反馈 | -> **已废弃**：`/ai/assistant_app/chat/server_sent_event` 和 `/ai/assistant_app/chat/sse_emitter` 已移除，请统一使用 `/ai/assistant_app/chat/sse`。 +> **已废弃**：`/ai/assistant_app/chat/server_sent_event` 和 `/ai/assistant_app/chat/sse_emitter` 已移除。旧路径 `/ai/assistant_app/chat/sync`、`/ai/assistant_app/chat/sse`、`/ai/assistant_app/chat/rag/sse`、`/ai/assistant_app/rag/sources` 仍保留（向后兼容）但已废弃，请统一使用 `/ai/chat`、`/ai/chat/stream`、`/ai/chat/sources`。 ### 6.3 Open API 对话接口（第三方系统直接调用） diff --git a/client/CLAUDE.md b/client/CLAUDE.md index 1c0f243..eb91c47 100644 --- a/client/CLAUDE.md +++ b/client/CLAUDE.md @@ -32,8 +32,8 @@ npm run dev SDK 本身不独立运行，需要后端在 `requestDomain`（通常 `http://localhost:9090`）提供以下接口： -- 基础对话：`GET /ai/assistant_app/chat/sync`、`GET /ai/assistant_app/chat/sse` -- RAG：`GET /ai/assistant_app/chat/rag/sse`、`GET /ai/assistant_app/rag/sources` +- 基础对话：`GET /ai/chat`、`GET /ai/chat/stream` +- RAG：`GET /ai/chat/stream`（`enableRag=true`）、`GET /ai/chat/sources` - 分类：`GET /category/tree`、`GET /category/list` - 会话：`GET /conversation/list`、`GET /conversation/{id}/messages`、`DELETE /conversation/{id}`、`GET /conversation/{id}/export` diff --git a/client/README.md b/client/README.md index 1867169..db05c6e 100644 --- a/client/README.md +++ b/client/README.md @@ -35,7 +35,7 @@ roleId: 1, // RAG 知识库检索 - enableRag: true, // 启用 RAG 增强对话（自动走 /chat/rag/sse） + enableRag: true, // 启用 RAG 增强对话（自动走 /ai/chat/stream，enableRag=true） categoryId: 5, // 默认知识库分类 showCategorySwitch: true, // 显示知识库分类下拉 @@ -78,7 +78,7 @@ SDK 产物位于 `client/dist/` 目录： | `requestDomain` | `string` | ✅ | — | P0 | 后端 API 域名 | | `userId` | `string` | ❌ | — | P0 | 宿主用户标识 → 后端 `accountId` | | `roleId` | `number` | ❌ | — | P0 | 客服角色 ID | -| `enableRag` | `boolean` | ❌ | `false` | P1 | 启用 RAG 知识库检索对话（自动走 `/chat/rag/sse` 接口） | +| `enableRag` | `boolean` | ❌ | `false` | P1 | 启用 RAG 知识库检索对话（走 `/ai/chat/stream` 接口，`enableRag=true`） | | `categoryId` | `number` | ❌ | — | P1 | 默认知识库分类 | | `showCategorySwitch` | `boolean` | ❌ | `false` | P1 | 是否显示知识库下拉切换 | | `title` | `string` | ❌ | `"AI 智能助手"` | P0 | 弹窗标题 | @@ -161,9 +161,9 @@ ChatbotSDK.init({ }); ``` -- `enableRag: true` 时，所有对话自动走 RAG 增强接口（`/ai/assistant_app/chat/rag/sse`） -- 选择分类后，后续对话也走 RAG 增强接口 -- 选择「全部分类」则走普通流式接口 +- `enableRag: true` 时，所有对话自动走 RAG 增强（`/ai/chat/stream` 接口，`enableRag=true`） +- 选择分类后，后续对话也走 RAG 增强 +- 选择「全部分类」则走普通流式（`enableRag=false`） - 分类数据从 `/category/tree` 接口动态加载，支持树形缩进显示 ### 4.4 RAG 引用来源展示 @@ -186,7 +186,7 @@ ChatbotSDK.init({ - 默认折叠，只显示标题行，点击展开/折叠 - 显示文档名称、摘要、来源文件、分块编号、相关度 -- 来源数据从 `/ai/assistant_app/rag/sources` 接口获取 +- 来源数据从 `/ai/chat/sources` 接口获取 --- @@ -246,16 +246,16 @@ SDK 全流程结构化日志，带 `[ChatbotSDK]` 前缀： ### P0 — 基础对话 ``` -GET /ai/assistant_app/chat/sync -GET /ai/assistant_app/chat/sse +GET /ai/chat # 同步对话 +GET /ai/chat/stream # SSE 流式对话 ``` ### P1 — 知识库联动 ``` -GET /ai/assistant_app/chat/rag/sse # RAG 增强流式对话 -GET /ai/assistant_app/rag/sources # RAG 引用来源 -GET /category/tree # 分类树（下拉框数据源） -GET /category/list # 分类列表 +GET /ai/chat/stream # RAG 增强流式对话（enableRag=true） +GET /ai/chat/sources # RAG 引用来源 +GET /category/tree # 分类树（下拉框数据源） +GET /category/list # 分类列表 ``` ### P2 — 会话管理