本地 RAG 知识库

16 KiB

Raw Permalink Blame History

Chat SDK 第三方系统集成指南

本文档说明第三方系统如何接入 AI 智能客服的 Chat SDK，完成从创建 API Key 到嵌入对话组件的全流程。

1. 集成架构总览

┌─────────────────┐     ┌──────────────────┐     ┌──────────────────┐
│  第三方前端      │     │  第三方后端       │     │  AI 客服后端      │
│  (嵌入 SDK)     │     │  (你的服务)       │     │  (本系统)         │
│                 │     │                  │     │                  │
│  Chat SDK ──────┼─────┼──────────────────┼─────┼─► /ai/** 对话    │
│   ↑ token       │     │                  │     │                  │
│                 │     │  ① 携带 API Key   │     │  ② 返回 JWT Token│
│                 │     │  POST /open-api/  │─────┼─► /auth/token    │
│                 │     │  auth/token       │     │                  │
└─────────────────┘     └──────────────────┘     └──────────────────┘

两段式鉴权流程：

管理后台：管理员创建 API Key，可选绑定客服角色
第三方后端：用 API Key 换取短期 JWT Token + 可用角色列表
第三方前端：Chat SDK 携带 JWT Token 请求 /ai/** 接口进行对话

2. 第一步：创建 API Key

在管理后台「系统设置 → API Key 管理」页面创建。

管理后台操作

登录管理后台 http://localhost:9090/index.html
进入「系统设置 → API Key 管理」
点击「＋新建 API Key」
填写名称、描述、频率限制等参数
（可选） 在创建弹窗中勾选需要绑定的客服角色
创建后立即复制保存 Key，关闭后无法再次查看

API Key 格式

sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx（sk_ 前缀 + 32 位 UUID）

3. 第二步：绑定客服角色（可选）

客服角色决定 AI 的人设、知识库范围和 MCP 工具权限。

角色绑定规则

role_ids 状态	Token 换取行为
空数组 `[]`（默认）	返回所有启用的客服角色（向后兼容）
非空 `[1, 2, 3]`	仅返回绑定的角色

通过管理后台绑定

在 API Key 列表中点击「绑定角色」按钮，勾选需要的角色后保存。

通过 API 绑定

PUT /api-key/{keyId}/roles
Content-Type: application/json
Authorization: Bearer {管理后台 JWT Token}

{
  "roleIds": [1, 2, 3]
}

响应：

{
  "success": true,
  "message": "角色绑定更新成功"
}

4. 第三步：后端换取 SDK Token

⚠️ 重要：Token 换取必须在第三方后端完成，不可在前端暴露 API Key。

请求

POST /open-api/auth/token
Content-Type: application/json
X-API-Key: sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

{
  "ttl": 7200
}

参数	类型	必填	说明
`X-API-Key`	Header	是	创建的 API Key
`ttl`	Body	否	Token 有效期（秒），默认 7200（2 小时），范围 [300, 86400]

成功响应

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiJ9...",
  "expiresIn": 7200,
  "roles": [
    { "id": "1", "key": "general", "name": "通用客服" },
    { "id": "2", "key": "finance", "name": "财务顾问" }
  ]
}

字段	说明
`token`	SDK JWT Token，传给前端使用
`expiresIn`	过期时间（秒）
`roles`	可用客服角色列表，前端用于展示角色选择器

错误响应

HTTP 状态码	说明
401	API Key 无效或已禁用
403	无可用客服角色

5. 第四步：前端嵌入 Chat SDK

使用测试面板快速验证

访问 http://localhost:9090/sdk/test.html 打开测试面板：

在「🔐 SDK Token 鉴权」区域输入 API Key
点击「获取 Token」按钮自动换取（或手动粘贴已有的 Token）
Token 获取成功后，integrateId 会自动填充为第一个可用角色
点击「🚀 初始化 SDK」即可测试对话功能

测试面板支持所有 P0/P1/P2 测试用例的自动化运行，包括 API 连通性验证。

5.1 引入 SDK

<script src="https://your-domain.com/sdk/chatbot-sdk.js"></script>

5.2 初始化

const chatbot = ChatbotSDK.init({
  // ========== 必填参数 ==========
  integrateId: '1',                              // 客服角色 ID（从 Token 换取接口的 roles 中选择）
  requestDomain: 'https://your-domain.com',       // AI 客服后端域名

  // ========== 鉴权参数（推荐） ==========
  token: 'eyJhbGciOiJIUzI1NiJ9...',               // 后端换取的 SDK Token
  roles: [                                        // 可用角色列表（传多个时 SDK header 显示角色切换下拉框）
    { id: '1', key: 'general', name: '通用客服' },
    { id: '2', key: 'finance', name: '财务顾问' }
  ],

  // ========== 可选参数 ==========
  userId: 'user_12345',                           // 用户标识（用于会话隔离）
  title: 'AI 智能助手',                            // 对话窗口标题
  theme: 'light',                                 // 主题：light / dark
  primaryColor: '#4F46E5',                         // 主题色（十六进制）
  streaming: true,                                // 启用流式回复（默认 true）
  enableRag: true,                                 // 启用 RAG 知识库检索（默认 true）
  quickReplies: ['如何退款？', '联系人工客服'],       // 快捷问题
  position: 'right-bottom',                        // 悬浮按钮位置：right-bottom / left-bottom
  width: 380,                                      // 窗口宽度（px）
  height: 520,                                     // 窗口高度（px）
  debug: true,                                     // 控制台调试日志

  // ========== 回调函数 ==========
  onReady: function() { console.log('SDK 就绪'); },
  onMessage: function(msg) { console.log('收到消息', msg); },
  onError: function(err) { console.error('SDK 错误', err); }
});

5.3 SDK 方法

// 销毁实例（移除 DOM 和事件监听）
chatbot.destroy();

5.4 不使用 Token 的兼容模式

如果暂时不接入后端 Token 换取，可直接使用兼容模式（不推荐用于生产环境）：

ChatbotSDK.init({
  integrateId: '1',                    // 直接指定角色 ID
  requestDomain: 'https://your-domain.com'
  // 不传 token 和 roles
});

兼容模式下，integrateId 直接作为 roleId 传递给后端，无需 Token 换取步骤。由于不传 roles，SDK 不会显示角色选择器，用户只能使用初始指定的单一角色。

5.5 角色切换

当 roles 数组长度 > 1 时，SDK 会在聊天窗口头部自动显示角色选择下拉框，用户可随时切换当前使用的客服角色。

触发条件：

ChatbotSDK.init() 时传入的 roles 数组包含 2 个及以上角色

切换行为：

自动保存当前对话到 localStorage（与旧角色关联）
清空当前消息列表
生成新的 chatId（与新角色关联）
尝试从 localStorage 恢复新角色的缓存消息
异步从后端加载新角色的历史会话

示例：

// 1. 后端换取 Token，获取可用角色列表
const data = await fetch('/api/chatbot/token').then(r => r.json());

// 2. 初始化 SDK，传入角色列表
ChatbotSDK.init({
  integrateId: data.roles[0].id,        // 默认使用第一个角色
  requestDomain: 'https://your-domain.com',
  token: data.token,
  roles: data.roles,                     // 传入多个角色 → header 显示角色选择器
  userId: 'current_user_id'
});

安全说明：

角色切换由 SDK 前端发起，后端 SdkAuthFilter 会校验 JWT Token 中的 rids claim，确保用户只能切换到被授权的角色
切换角色不需要重新换取 Token，JWT 中已包含允许的角色 ID 列表

6. API 接口参考

6.1 Token 换取

POST /open-api/auth/token

详见第三步：后端换取 SDK Token。

6.2 对话接口（SDK 内部调用，无需手动对接）

接口	方法	说明
`/ai/assistant_app/chat/sync`	GET	同步对话（返回完整文本）
`/ai/assistant_app/chat/sse`	GET	SSE 流式对话
`/ai/assistant_app/chat/rag/sse`	GET	RAG 增强流式对话
`/ai/assistant_app/rag/sources`	GET	获取 RAG 引用来源
`/ai/sdk/conversation/list`	GET	会话列表
`/ai/sdk/conversation/{id}/messages`	GET	会话消息
`/ai/sdk/conversation/{id}`	DELETE	删除会话
`/ai/sdk/conversation/{id}/export`	GET	导出会话
`/category/tree`	GET	知识库分类树
`/feedback`	POST	消息反馈

通用请求参数（对话接口）：

参数	类型	必填	说明
`message`	Query	是	用户消息
`chatId`	Query	是	会话 ID（SDK 自动管理）
`roleId`	Query	否	客服角色 ID
`accountId`	Query	否	用户标识
`categoryId`	Query	否	知识库分类 ID
`rewriteStrategy`	Query	否	RAG 查询重写策略：REWRITE / TRANSLATION / COMPRESSION / MULTI_QUERY

认证方式： 所有 /ai/** 请求自动在 Header 中携带 Authorization: Bearer {token}。

6.3 管理接口（需要管理后台 JWT）

接口	方法	说明
`/api-key/list`	GET	API Key 列表（admin）
`/api-key`	POST	创建 API Key（admin）
`/api-key/{id}/revoke`	PUT	吊销 API Key（admin）
`/api-key/{id}/enable`	PUT	启用 API Key（admin）
`/api-key/{id}`	DELETE	删除 API Key（admin）
`/api-key/{id}/roles`	PUT	更新角色绑定（admin）
`/role/list`	GET	客服角色列表（admin）
`/role/all`	GET	全部角色含停用（admin）

7. SDK 配置参数参考

参数	类型	默认值	说明
`integrateId`	String/Number	必填	客服角色 ID
`requestDomain`	String	必填	后端域名
`token`	String	-	SDK JWT Token（推荐）
`roles`	Array	-	角色列表 `[{id, key, name}]`，长度 > 1 时 header 显示切换下拉框
`userId`	String	-	用户标识（会话隔离）
`categoryId`	String	-	默认知识库分类 ID
`showCategorySwitch`	Boolean	false	显示分类切换器
`title`	String	'AI 智能助手'	窗口标题
`width`	Number	380	窗口宽度（px）
`height`	Number	520	窗口高度（px，最小 300）
`position`	String	'right-bottom'	悬浮按钮位置
`primaryColor`	String	'#4F46E5'	主题色
`launcherTheme`	String	-	按钮主题：dream-purple / mint-tech / coral-peach / sky-blue
`launcherIcon`	String	(内置)	自定义悬浮按钮 SVG
`theme`	String	'light'	界面主题：light / dark
`streaming`	Boolean	true	流式回复
`enableRag`	Boolean	true	RAG 知识库检索
`rewriteStrategy`	String	'REWRITE'	查询重写策略
`quickReplies`	String[]	[]	快捷问题列表
`showClear`	Boolean	true	显示清空按钮
`showAdminPanel`	Boolean	false	显示管理入口
`showTeaser`	Boolean	true	显示提示气泡
`teaserText`	String	''	提示气泡文本
`sound`	Boolean	false	消息提示音
`notification`	Boolean	false	浏览器通知
`locale`	String	'zh-CN'	语言：zh-CN / en
`debug`	Boolean	true	调试日志
`onReady`	Function	-	SDK 就绪回调
`onMessage`	Function	-	消息回调
`onError`	Function	-	错误回调

8. 错误码与排查

Token 换取阶段

错误	原因	解决方案
401 `API Key 鉴权失败`	X-API-Key 无效或缺失	检查 Header 是否正确携带
401 `API Key 已被禁用`	Key 被吊销	在管理后台重新启用或创建新 Key
401 `API Key 已过期`	Key 超过有效期	创建新的 API Key
403 `无可用客服角色`	未绑定角色且系统无启用角色	在管理后台创建并启用客服角色

SDK 对话阶段

HTTP 状态码	SDK 提示	原因
401	鉴权失败	Token 过期或无效，需重新换取
403	无访问权限	roleId 不在 Token 允许范围内
429	请求过于频繁	超过 API Key 频率限制
500	服务器异常	后端错误，查看服务端日志
502/503	服务暂不可用	后端未启动或正在部署

常见问题

Q: Token 过期后怎么办？ A: Token 默认 2 小时过期。建议在第三方后端实现 Token 缓存和自动刷新逻辑：检测到 401 时重新调用 /open-api/auth/token 换取新 Token。

Q: 如何让用户只能使用特定角色？ A: 在 API Key 上绑定角色（PUT /api-key/{id}/roles），SDK 初始化时只传入绑定的角色 ID。

Q: 多个第三方系统可以用同一个 API Key 吗？ A: 可以，但建议每个系统使用独立的 API Key，便于独立管控频率限制和角色权限。

9. 安全建议

API Key 仅在后端使用：永远不要将 API Key 暴露到前端代码中
Token 短有效期：生产环境建议 TTL 设为 1-2 小时，配合自动刷新
角色最小权限：只绑定必要的客服角色，避免授予过多权限
频率限制：根据业务量设置合理的 rateLimit（默认 60 次/分钟）
HTTPS：生产环境必须使用 HTTPS，防止 Token 被中间人截获
定期轮换 Key：定期吊销旧 Key 并创建新 Key

附录：完整对接示例（Node.js）

// ==================== 第三方后端示例 ====================
const express = require('express');
const app = express();

const AI_DOMAIN = 'https://your-ai-domain.com';
const API_KEY = 'sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx';

// Token 缓存
let cachedToken = null;
let tokenExpireAt = 0;

// 换取 Token（带缓存）
async function getSdkToken() {
  if (cachedToken && Date.now() < tokenExpireAt) {
    return cachedToken;
  }

  const res = await fetch(`${AI_DOMAIN}/open-api/auth/token`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': API_KEY
    },
    body: JSON.stringify({ ttl: 7200 })
  });

  const data = await res.json();
  if (!data.success) throw new Error(data.message);

  cachedToken = data.token;
  tokenExpireAt = Date.now() + (data.expiresIn - 300) * 1000; // 提前 5 分钟刷新
  return { token: data.token, roles: data.roles };
}

// 给前端提供 Token
app.get('/api/chatbot/token', async (req, res) => {
  try {
    const data = await getSdkToken();
    res.json({ success: true, ...data });
  } catch (e) {
    res.status(500).json({ success: false, message: e.message });
  }
});

app.listen(3000);

<!-- ==================== 第三方前端示例 ==================== -->
<script src="https://your-ai-domain.com/sdk/chatbot-sdk.js"></script>
<script>
  // 从自己后端获取 Token
  fetch('/api/chatbot/token')
    .then(r => r.json())
    .then(data => {
      if (data.success) {
        ChatbotSDK.init({
          integrateId: data.roles[0].id,    // 默认使用第一个角色
          requestDomain: 'https://your-ai-domain.com',
          token: data.token,
          roles: data.roles,                // 传入多个角色时自动显示角色选择器
          userId: 'current_user_id',
          title: '在线客服',
          theme: 'light',
          quickReplies: ['如何退款？', '查看订单', '联系人工']
        });
      }
    });
</script>

16 KiB Raw Permalink Blame History