Skip to main content
LangChat Pro 提供多种接入方式，支持第三方系统快速集成 Agent 能力。所有接入方式的消息记录和资源消耗都会统计到对应的 Agent 应用下。

​
接入方式概览

LangChat Pro 为外部系统提供两种主要接入方式：

​
1. SDK 小组件接入

  • 适用场景：Web 前端快速集成
  • 优势：开箱即用，配置简单
  • 特点：提供完整的聊天界面组件

​
2. API 接入

  • 适用场景：后端系统集成、自定义客户端
  • 优势：灵活可控，完全自定义
  • 特点：遵循 OpenAI 接口规范
无论采用哪种接入方式，所有消息记录和资源消耗都会统计到对应的 Agent 应用下，请合理配置监控和计费策略。

​
API 密钥配置

所有接入方式都需要先在平台创建 API 密钥： image-20250923211532717

​
关键配置项

​
IP 限流

  • 功能：限制相同 IP 每分钟的最大调用次数
  • 用途：防止接口滥用，保护系统稳定性
  • 建议：根据业务需求合理设置限流阈值

​
过期时间

  • 功能：设置 API 密钥的有效期限
  • 安全：过期后密钥自动失效，需要重新生成
  • 建议：定期轮换密钥，提升安全性

​
历史对话共享

  • 默认行为：相同 API 密钥共享聊天历史和上下文
  • 关闭效果：每个会话独立，避免上下文混淆
  • 使用建议：根据业务场景选择是否开启
API 密钥是访问 Agent 服务的唯一凭证，请妥善保管，避免泄露。

​
Iframe接入

在上面创建了秘钥之后，可以点击Table右侧的按钮，可以选择多种接入方式，例如用IFRAME嵌套的方式，将整个网页嵌入到第三方的系统中。 image-20250924092340668

​
SDK 小组件接入

SDK 小组件提供开箱即用的聊天界面，适合快速集成到现有 Web 应用中。

​
快速开始

​
1. 引入资源文件

<link href="http://cdn.langchat.cn/langchat/widget/langchat-widget.css" rel="stylesheet">
<script src="http://cdn.langchat.cn/langchat/widget/langchat-widget.umd.js"></script>
注意：由于我们的CDN域可能在你们的内部网络无法访问，我们已经将 langchat-widget.css 和 langchat-widget.umd.js 放在你们自己的 CDN 上，你可以直接使用。这两个静态文件已经存放在项目根目录的 docs/widget/ 目录下，自行把这两个文件放到内部的CDN域（或者放到服务器上用nginx映射一下），然后修改前端的 langchat-ui/apps/langchat/index.html 文件的静态资源引用即可

​
2. 初始化组件

const chatWidget = new window.LangChatWidget.LangChatBot({
  baseUrl: 'https://your-domain.com/api',
  apiKey: 'your-api-key',
  header: {
    title: '智能助手',
  },
  welcome: {
    enabled: true,
    title: '您好！我是您的专属助手，有什么可以帮助您的吗？',
  },
  position: 'bottom-right',
});

​
完整示例

<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <meta content="width=device-width, initial-scale=1.0" name="viewport">
    <title>LangChat Widget 集成示例</title>
    <link href="http://cdn.langchat.cn/langchat/widget/langchat-widget.css" rel="stylesheet">
</head>
<body>
    <div style="padding: 20px; font-family: Arial, sans-serif;">
        <h1>LangChat Widget 集成示例</h1>
        <p>展示如何在网页中集成 LangChat 聊天组件。</p>
        <button onclick="openChat()">打开聊天</button>
        <button onclick="closeChat()">关闭聊天</button>
    </div>

    <script src="http://cdn.langchat.cn/langchat/widget/langchat-widget.umd.js"></script>
    <script>
    let chatWidget;

    // 初始化聊天组件
    function initChat() {
      if (!window.LangChatWidget || !window.LangChatWidget.LangChatBot) {
        console.error('LangChat Widget 未正确加载，请检查资源文件引入');
        return;
      }
      
      chatWidget = new window.LangChatWidget.LangChatBot({
        baseUrl: 'https://api.siliconflow.cn/v1',
        apiKey: 'sk-your-api-key-here',
        modelName: 'Qwen/Qwen2.5-72B-Instruct',
        header: {
          title: 'LangChat 智能助手',
        },
        welcome: {
          enabled: true,
          title: '您好！我是 LangChat 助手，有什么可以帮助您的吗？',
        },
        position: 'bottom-right',
      });
    }

    // 打开聊天窗口
    window.openChat = function() {
      if (chatWidget) {
        chatWidget.open();
      }
    };

    // 关闭聊天窗口
    window.closeChat = function() {
      if (chatWidget) {
        chatWidget.close();
      }
    };

    // 页面加载完成后初始化
    document.addEventListener('DOMContentLoaded', initChat);
    </script>
</body>
</html>

​
配置参数说明

参数类型说明默认值
baseUrlstringAPI 服务地址-
apiKeystringAPI 密钥-
modelNamestring模型名称-
header.titlestring聊天窗口标题’智能助手’
welcome.enabledboolean是否显示欢迎语true
welcome.titlestring欢迎语内容-
positionstring窗口位置’bottom-right’
SDK 组件会自动处理聊天历史、会话管理等复杂逻辑，开发者只需关注业务集成。

​
API 接入

API 接入提供最大的灵活性，适合需要自定义客户端或后端集成的场景。LangChat Pro 遵循 OpenAI 接口规范，支持流式响应。

​
接口规范

  • 协议标准：完全兼容 OpenAI API 规范
  • 响应模式：仅支持流式（Stream）响应
  • 认证方式：Bearer Token（API Key）
API 接入让企业可以完全自定义客户端界面和交互逻辑，满足不同业务场景的需求。

​
会话管理

​
默认会话行为

默认情况下，API Key 作为 conversationId，所有请求共享同一会话上下文： 
curl -X POST "https://api.your-domain.com/v1/chat/completions" \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "role": "user", "content": "你好" }
    ]
  }'

​
自定义会话 ID

如需创建独立会话，可手动指定 conversationId： 
{
  "conversationId": "custom-session-123",
  "messages": [
    { "role": "user", "content": "你好" }
  ]
}

​
请求示例

​
基础对话请求

curl -X POST "https://api.your-domain.com/v1/chat/completions" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-3.5-turbo",
    "messages": [
      { "role": "system", "content": "你是一个专业的客服助手" },
      { "role": "user", "content": "请介绍一下你们的产品" }
    ],
    "stream": true,
    "conversationId": "session-001"
  }'

​
流式响应处理

const response = await fetch('https://api.your-domain.com/v1/chat/completions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk-your-api-key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'gpt-3.5-turbo',
    messages: [{ role: 'user', content: '你好' }],
    stream: true,
    conversationId: 'session-001'
  })
});

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]') return;
      
      try {
        const parsed = JSON.parse(data);
        console.log(parsed.choices[0].delta.content);
      } catch (e) {
        // 忽略解析错误
      }
    }
  }
}

​
会话管理最佳实践

  1. 会话隔离：为不同用户或场景使用独立的 conversationId
  2. 会话持久化：在客户端维护会话 ID 的映射关系
  3. 会话清理：定期清理过期或无效的会话数据
  4. 错误处理：妥善处理网络异常和 API 错误响应
会话 ID 由调用方自行维护，请确保 ID 的唯一性和一致性，避免会话数据混乱。