灵枢AI - 企业级AI对话API接口 | 3分钟接入智能客服

快速开始

按照以下步骤，在您的项目中集成 AI 对话功能。整个过程只需几分钟。

获取 API Key 和项目 ID

在开始集成之前，您需要从控制台获取以下凭证：

API Key

进入控制台 → API Keys，点击"创建 API Key"

项目 ID (appId)

进入控制台 → 项目，复制项目的 ID

重要：请妥善保管您的 API Key，不要将其暴露在前端代码中或提交到代码仓库。建议通过环境变量管理。

选择集成方式

根据您的项目类型选择合适的集成方案

方式一：使用预制组件（推荐）

开箱即用的聊天组件，适合快速集成。包含完整的 UI 和交互逻辑。

安装bash

1npm install @lingshuai/chat-react
2# 或使用 pnpm / yarn
3pnpm add @lingshuai/chat-react

在 App 中使用tsx

1// App.tsx
2import { ChatProvider, ChatWidget } from '@lingshuai/chat-react';
3
4function App() {
5  return (
6    <ChatProvider
7      apiKey={process.env.REACT_APP_LINGSHUAI_API_KEY}
8      appId={process.env.REACT_APP_LINGSHUAI_APP_ID}
9    >
10      {/* 您的应用内容 */}
11      <YourApp />
12
13      {/* 聊天悬浮球组件 - 会显示在页面右下角 */}
14      <ChatWidget
15        title="智能客服"
16        welcomeMessage="您好！有什么可以帮助您的？"
17        position="bottom-right"
18      />
19    </ChatProvider>
20  );
21}
22
23export default App;

环境变量配置 (.env)bash

1REACT_APP_LINGSHUAI_API_KEY=your-api-key-here
2REACT_APP_LINGSHUAI_APP_ID=your-project-id-here

方式二：使用 Hooks 自定义 UI

使用 useChat Hook 获取完整控制权，搭配您自己的 UI 组件。

完整示例tsx

1// ChatPage.tsx
2import { useChat } from '@lingshuai/chat-react';
3import { useState } from 'react';
4
5function ChatPage() {
6  const [inputValue, setInputValue] = useState('');
7
8  const {
9    messages,        // 消息列表
10    sendMessage,     // 发送消息方法
11    isLoading,       // 是否正在发送/接收
12    isStreaming,     // 是否正在流式接收
13    error,           // 错误信息
14    clearMessages,   // 清空消息
15  } = useChat({
16    apiKey: process.env.REACT_APP_LINGSHUAI_API_KEY,
17    appId: process.env.REACT_APP_LINGSHUAI_APP_ID,
18    // 可选：监听流式响应
19    onStreamChunk: (chunk, fullContent) => {
20      console.log('收到数据块:', chunk);
21    },
22    onMessage: (message) => {
23      console.log('收到完整消息:', message);
24    },
25    onError: (error) => {
26      console.error('发生错误:', error);
27    },
28  });
29
30  const handleSend = () => {
31    if (!inputValue.trim() || isLoading) return;
32    sendMessage(inputValue);
33    setInputValue('');
34  };
35
36  return (
37    <div className="flex flex-col h-screen">
38      {/* 消息列表 */}
39      <div className="flex-1 overflow-y-auto p-4 space-y-4">
40        {messages.map((msg) => (
41          <div
42            key={msg.id}
43            className={`flex ${msg.role === 'user' ? 'justify-end' : 'justify-start'}`}
44          >
45            <div
46              className={`max-w-[70%] px-4 py-2 rounded-2xl ${
47                msg.role === 'user'
48                  ? 'bg-blue-600 text-white'
49                  : 'bg-gray-100 text-gray-900'
50              }`}
51            >
52              {msg.content}
53              {msg.status === 'streaming' && (
54                <span className="inline-block w-2 h-4 ml-1 bg-current animate-pulse" />
55              )}
56            </div>
57          </div>
58        ))}
59
60        {isLoading && !isStreaming && (
61          <div className="flex justify-start">
62            <div className="bg-gray-100 px-4 py-2 rounded-2xl">
63              <span className="animate-pulse">正在思考...</span>
64            </div>
65          </div>
66        )}
67      </div>
68
69      {/* 输入区域 */}
70      <div className="border-t p-4">
71        <div className="flex space-x-2">
72          <input
73            type="text"
74            value={inputValue}
75            onChange={(e) => setInputValue(e.target.value)}
76            onKeyDown={(e) => e.key === 'Enter' && handleSend()}
77            placeholder="输入消息..."
78            className="flex-1 px-4 py-2 border rounded-full focus:outline-none focus:ring-2 focus:ring-blue-500"
79            disabled={isLoading}
80          />
81          <button
82            onClick={handleSend}
83            disabled={isLoading || !inputValue.trim()}
84            className="px-6 py-2 bg-blue-600 text-white rounded-full hover:bg-blue-700 disabled:opacity-50"
85          >
86            发送
87          </button>
88        </div>
89      </div>
90    </div>
91  );
92}
93
94export default ChatPage;

验证集成

完成上述步骤后，启动您的项目并测试以下功能：

聊天窗口能够正常打开和关闭
发送消息后能收到 AI 回复
流式响应能够实时显示（打字效果）
刷新页面后会话记录能够保持

常见问题

Q: 提示 401 Unauthorized 错误？

请检查 API Key 是否正确，以及项目 ID 是否与 API Key 所属的项目匹配。

Q: 请求跨域 (CORS) 错误？

请确保您的域名已添加到项目的白名单中。进入控制台 → 项目设置 → 域名白名单。

Q: 如何在生产环境使用？

建议通过后端代理转发 API 请求，避免在前端暴露 API Key。详见"配置选项"中的 baseUrl 配置。

需要帮助？

如果您在集成过程中遇到任何问题，欢迎联系我们的技术支持团队。

GitHub 联系支持