Web 客户端

Web 客户端提供独立的聊天界面，支持嵌入网站或作为独立访问链接，可通过 HTTP API 集成到任何应用中。

应用场景

官网接入：在公司网站嵌入智能客服
内部系统：企业内部知识问答助手
独立聊天：提供独立的 Web 聊天链接
第三方集成：通过 API 对接其他系统

创建 Web 客户端应用

1. 进入应用管理

Agent System → 应用管理 → 创建应用

2. 填写基础信息

应用名称：web_chat_client（系统标识符）
显示名称：在线客服（用户可见名称）
描述：功能说明

3. 选择平台类型

选择：Web客户端 🌐

4. 选择 Orchestrator

从下拉列表选择已创建的 Orchestrator。

5. 配置参数

字段	说明	示例
访问Token	用于访问认证	自动生成或自定义
允许的来源 (可选)	CORS 白名单	`https://example.com, https://app.example.com`

Token 安全

Token 用于访问控制，请妥善保管。如泄露，可在编辑页面重新生成。

6. 保存应用

点击创建，系统自动生成 API 地址。

使用方式

方式一：独立访问

创建成功后，点击应用卡片上的测试按钮，直接打开聊天界面。

访问链接格式：

https://your-domain.com/app-chat/{token}

分享链接：

可将此链接分享给用户
用户无需登录即可使用
支持手机和 PC 浏览器

方式二：嵌入网站

快速嵌入

点击应用卡片上的嵌入代码按钮，复制代码并粘贴到网页的 </body> 标签前：

html

<!-- Sira AI 聊天组件 -->
<script src="https://your-domain.com/embed/app-chat-widget.js"></script>
<script>
  SiraChat.init({
    apiUrl: 'https://your-domain.com',
    applicationId: 'your-app-id',
    title: '智能客服',
    welcomeMessage: '您好！有什么可以帮助您的吗？',
    position: 'bottom-right',  // 位置：bottom-right, bottom-left
    theme: 'light',            // 主题：light, dark, auto
    primaryColor: '#3b82f6',   // 主题色
    autoOpen: false,           // 是否自动打开
    onReady: function() {
      console.log('AI 助手已就绪');
    }
  });
</script>

配置选项

参数	说明	默认值
apiUrl	Sira AI 服务地址	必填
applicationId	应用ID	必填
title	聊天窗口标题	'智能助手'
welcomeMessage	欢迎语	'您好！'
position	窗口位置	'bottom-right'
theme	主题	'light'
primaryColor	主题色	'#3b82f6'
autoOpen	自动打开	false

方式三：HTTP API 调用

点击应用卡片上的调用示例按钮（文件图标），查看详细的 API 调用示例。

API 端点

POST https://your-domain.com/api/agent-system/applications/{application_id}/message

请求示例（cURL）

流式响应：

bash

curl -X POST 'https://your-domain.com/api/agent-system/applications/YOUR_APP_ID/message' \
  -H 'Content-Type: application/json' \
  -H 'Accept: text/event-stream' \
  -d '{
    "user_message": "你好",
    "session_id": "user_123",
    "stream": true
  }'

非流式响应：

bash

curl -X POST 'https://your-domain.com/api/agent-system/applications/YOUR_APP_ID/message' \
  -H 'Content-Type: application/json' \
  -d '{
    "user_message": "你好",
    "session_id": "user_123",
    "stream": false
  }'

请求参数

参数	类型	说明	必填
user_message	string	用户消息内容	✅
session_id	string	会话ID（保持上下文）	❌
stream	boolean	是否流式响应	❌ (默认false)
自定义字段	any	模板变量（见下文）	❌

响应格式

流式（SSE）：

data: {"type": "content", "content": "你"}
data: {"type": "content", "content": "好"}
data: {"type": "content", "content": "！"}
data: {"type": "done"}
data: [DONE]

非流式（JSON）：

json

{
  "response": "你好！有什么可以帮助您的吗？",
  "session_id": "user_123",
  "stream": false
}

流式架构（直接 yield，无 Redis 中转）

Web 客户端的 SSE 端点走 execute_streaming_direct() 直接 yield 模式——编排器产出的 chunk 直接通过 SSE 推到浏览器，不经过 Redis 中转，相比早期 Redis Stream 模式延迟约降低 50%。

平台同时保留了 Redis Stream 模式，专供企业微信 AI Bot（受 5 秒回调超时约束需要"刷新拉取"）和遗留 WeChat 集成使用。两条路径在同一引擎里共存，按调用方自动选择。

模板变量功能

Web API 支持传递自定义字段作为模板变量，实现动态上下文注入。

使用场景

传递用户身份信息
注入业务上下文
个性化回复

示例

请求中传递变量：

json

{
  "user_message": "我的订单状态如何？",
  "session_id": "user_123",
  "stream": false,
  "user_id": "U001",
  "user_name": "张三",
  "user_level": "VIP",
  "order_id": "ORD123456"
}

在系统提示词中使用：

markdown

你是客服助手。

当前用户：
- 姓名：{{user_name}}
- ID：{{user_id}}
- 等级：{{user_level}}

用户询问订单{{order_id}}的状态，请查询并回复。

变量规则

保留字段：user_message、session_id、stream 不能作为模板变量
使用 {{变量名}} 在系统提示词中引用
支持默认值：{{变量名|默认值}}
未传递的变量自动替换为空字符串

多模态支持

Web 客户端支持图片消息：

图片传递方式：

文本中的图片链接：自动检测 https://example.com/image.jpg
Base64 图片：直接在消息中传递 Base64 编码的图片（未来支持）

示例：

json

{
  "user_message": "请分析这张图片：https://example.com/chart.png",
  "session_id": "user_123",
  "stream": true
}

系统会自动检测图片链接并使用 Vision 模型处理。

要求：

Agent 使用支持 Vision 的模型（如 GPT-4o、Claude 3）
图片链接必须可公网访问
查看多模态文档

代码示例

JavaScript (Fetch API)

流式：

javascript

const response = await fetch('YOUR_API_URL', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'text/event-stream',
  },
  body: JSON.stringify({
    user_message: '你好',
    session_id: 'user_123',
    stream: true,
  }),
});

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  const chunk = decoder.decode(value);
  const lines = chunk.split('\n');

  for (const line of lines) {
    if (line.startsWith('data: ')) {
      const data = line.slice(6);
      if (data === '[DONE]') break;

      const json = JSON.parse(data);
      console.log(json.content); // 流式内容
    }
  }
}

非流式：

javascript

const response = await fetch('YOUR_API_URL', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    user_message: '你好',
    session_id: 'user_123',
    stream: false,
  }),
});

const data = await response.json();
console.log(data.response); // 完整响应

Python (requests)

流式：

python

import requests
import json

response = requests.post(
    'YOUR_API_URL',
    headers={
        'Content-Type': 'application/json',
        'Accept': 'text/event-stream',
    },
    json={
        'user_message': '你好',
        'session_id': 'user_123',
        'stream': True,
    },
    stream=True
)

for line in response.iter_lines():
    if line:
        line_str = line.decode('utf-8')
        if line_str.startswith('data: '):
            data = line_str[6:]
            if data == '[DONE]':
                break
            json_data = json.loads(data)
            print(json_data.get('content', ''))

非流式：

python

import requests

response = requests.post(
    'YOUR_API_URL',
    headers={'Content-Type': 'application/json'},
    json={
        'user_message': '你好',
        'session_id': 'user_123',
        'stream': False,
    }
)

data = response.json()
print(data['response'])

常见问题

跨域（CORS）错误

现象：浏览器控制台提示 CORS 错误

解决：

在 Application 配置中添加 允许的来源
填写完整域名：https://example.com
多个域名用逗号分隔
保存并刷新页面

Token 泄露怎么办

解决：

编辑 Application
重新生成 Token
更新前端代码中的 Token
旧 Token 立即失效

会话保持问题

说明：

使用相同的 session_id 可保持对话上下文
不同 session_id 是独立的对话
Session 默认保留 30 分钟

图片消息无法识别

排查：

图片链接是否可公网访问
Agent 是否使用支持 Vision 的模型
查看多模态文档

安全建议

Token 管理：
- 不要在前端代码中硬编码 Token
- 定期更换 Token
- 通过后端代理调用 API
访问控制：
- 配置 CORS 白名单
- 限制单个 Session 的请求频率
- 监控异常访问
数据安全：
- 使用 HTTPS
- 不在消息中传递敏感信息
- 对用户输入进行验证

下一步

API Service - OpenAI 兼容 API
模板变量 - 动态上下文注入
多模态支持 - 处理图片消息
Orchestrator 配置 - 优化业务逻辑

相关资源：

Web 客户端 ​

应用场景 ​

创建 Web 客户端应用 ​

1. 进入应用管理 ​

2. 填写基础信息 ​

3. 选择平台类型 ​

4. 选择 Orchestrator ​

5. 配置参数 ​

6. 保存应用 ​

使用方式 ​

方式一：独立访问 ​

方式二：嵌入网站 ​

快速嵌入 ​

配置选项 ​

方式三：HTTP API 调用 ​

API 端点 ​

请求示例（cURL） ​

请求参数 ​

响应格式 ​

模板变量功能 ​

使用场景 ​

示例 ​

多模态支持 ​

代码示例 ​

JavaScript (Fetch API) ​

Python (requests) ​

常见问题 ​

跨域（CORS）错误 ​

Token 泄露怎么办 ​

会话保持问题 ​

图片消息无法识别 ​

安全建议 ​

下一步 ​

Web 客户端

应用场景

创建 Web 客户端应用

1. 进入应用管理

2. 填写基础信息

3. 选择平台类型

4. 选择 Orchestrator

5. 配置参数

6. 保存应用

使用方式

方式一：独立访问

方式二：嵌入网站

快速嵌入

配置选项

方式三：HTTP API 调用

API 端点

请求示例（cURL）

请求参数

响应格式

模板变量功能

使用场景

示例

多模态支持

代码示例

JavaScript (Fetch API)

Python (requests)

常见问题

跨域（CORS）错误

Token 泄露怎么办

会话保持问题

图片消息无法识别

安全建议

下一步