@baiducloud/qianfan-ai-assistant
v0.0.3
Published
AI Assistant SDK - AI助手SDK，提供UMD格式的第三方集成能力
Downloads
347
Readme
@baiducloud/qianfan-ai-assistant
AI 助手 SDK，提供 UMD 格式的第三方集成能力，支持通过 <script> 标签引入使用。
安装
npm install @baiducloud/qianfan-ai-assistant注意：本包提供 UMD 格式的构建产物，仅支持通过 <script> 标签引入。
使用方法
OpenAPI 文档
SDK 需要配合 OpenAPI 自行实现接口调用。在实现 IClientService 接口时，请参考 千帆 API 文档 中的AI助手 Agent 相关接口规范。
UMD 引入
通过 <script> 标签引入，SDK 会自动挂载到 window.AIAssistantAgent。
引入方式
方式一：直接引用构建产物
如果已将 UMD 包复制到项目的静态资源目录，可以直接通过相对路径引用：
<script src="/dist/index.js"></script>方式二：通过构建配置引入
在构建配置中（如 Vite、Webpack、Rsbuild 等），可以通过 publicDir 配置将 UMD 包引入到项目中：
// vite.config.js / webpack.config.js / rsbuild.config.ts 等
import path from 'path';
export default {
// ... 其他配置
publicDir: {
name: path.resolve(__dirname, 'node_modules/@baiducloud/qianfan-ai-assistant/dist')
}
};配置后，UMD 包会被复制到构建输出的静态资源目录，可以通过 <script> 标签引用：
<script src="/index.js"></script>使用示例
重要提示：UMD 包必须在应用代码之后加载，因为 SDK 需要挂载 UI 到对应的 DOM 元素上。请确保：
- 先创建用于挂载 SDK UI 的 DOM 容器
- 然后加载 UMD 包脚本
- 最后在脚本中初始化 SDK
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8" />
<title>AI 助手 SDK 示例</title>
</head>
<body>
<!-- 步骤1：创建容器（必须在脚本加载前存在） -->
<div id="ai-assistant-container"></div>
<!-- 步骤2：加载 UMD 包 -->
<script src="/dist/index.js"></script>
<!-- 步骤3：初始化 SDK（必须在 UMD 包加载后执行） -->
<script>
// 实现 IClientService 接口（接口定义见下方）
const clientService = {
/** 对话接口 - SSE流式接口 */
agentSpaceRun(param, callbacks, options) {},
/** 恢复对话 */
recoverChat(param, callbacks, options) {},
/** 文件上传 */
async uploadFile(file, conversationId) {
// 实现文件上传逻辑，返回文件ID和对话ID
return {
file_id: 'file-id',
conversation_id: conversationId
};
},
/** 获取用户偏好 */
async getUserPreferences(appId) {
return {
user_profile: {
instructions: '',
location_info: {
province: '',
city: '',
district: ''
}
}
};
},
/** 保存用户偏好 */
async saveUserPreferences(appId, preferences) {},
/** 获取已上传文件信息 */
async getUploadFileInfo(fileIds) {
return {data: [], has_more: false};
},
/** 取消正在进行的请求 */
async sendAbortRequest(param) {},
/** 语音识别 */
async speechToText(file, appId) {
return '';
},
/** 历史记录相关 */
async fetchHistoryChatList(params) {
return {data: [], has_more: false};
},
async fetchChatHistory(params) {
return [];
},
async fetchChatStatus(conversationIds) {
return {data: []};
},
async updateChatTitle(id, title, end_user_id) {
return {success: true};
},
async deleteHistoryChat(chatId) {
return {success: true, deleted_count: 1};
}
};
AIAssistantAgent.init(document.getElementById('ai-assistant-container'), clientService);
</script>
</body>
</html>IClientService 接口说明
使用 SDK 前，需要实现 IClientService 接口，该接口定义了 SDK 与后端服务的通信方式。
核心方法
| 方法 | 说明 | 返回类型 |
| --------------------- | ---------------------- | ---------------------------------- |
| agentSpaceRun | SSE 对话流式接口 | void |
| recoverChat | SSE 恢复对话接口 | void |
| uploadFile | 文件上传 | Promise<IFileUploadRes> |
| getUserPreferences | 获取用户偏好 | Promise<IUserPreferencesData> |
| saveUserPreferences | 保存用户偏好 | Promise<void> |
| getUploadFileInfo | 批量查询已上传文件信息 | Promise<ISessionHistoryFilesRes> |
| sendAbortRequest | 取消正在进行的请求 | Promise<any> |
| speechToText | 语音识别（ASR） | Promise<string> |
历史记录方法
| 方法 | 说明 | 返回类型 |
| ---------------------- | -------------------- | --------------------------------------------------------- |
| fetchHistoryChatList | 获取历史记录总列表 | Promise<{data: IConversationItem[]; has_more: boolean}> |
| fetchChatHistory | 获取历史对话消息列表 | Promise<IHistoryChatItem[]> |
| fetchChatStatus | 批量获取会话状态 | Promise<{data: IConversationStatus[]}> |
| updateChatTitle | 更新会话标题 | Promise<{success: boolean}> |
| deleteHistoryChat | 删除历史对话 | Promise<{success: boolean; deleted_count: number}> |
SSE 接口签名
agentSpaceRun 和 recoverChat 方法的签名：
(
param: any,
callbacks: {
onMessage: (message: string) => void;
onCompleted: () => void;
onError: (error: Error) => void;
},
options?: {
abortController?: AbortController;
headers?: HeadersInit;
}
) => void开发调试
在使用 SDK 进行开发时，建议在浏览器开发者工具中查看控制台输出，以便排查问题和调试接口调用。
依赖说明
SDK 采用全量打包方式，所有依赖（包括 React、ReactDOM 等）都已打包在 UMD 文件中，用户无需额外引入任何依赖即可使用。
类型声明
SDK 提供完整的 TypeScript 类型声明文件（dist/index.d.ts），包含：
IClientService- 客户端服务接口IFileUploadRes- 文件上传响应IAbortRequestParams- 取消请求参数IUserPreferencesData- 用户偏好数据ISessionHistoryDataReq- 历史消息请求参数IHistoryChatItem- 历史消息条目IUploadedFileInfo- 已上传文件详情ISessionHistoryFilesRes- 批量文件查询返回IConversationListReq- 会话列表请求参数IConversationItem- 会话列表元素IConversationStatus- 会话状态条目init- SDK 初始化函数
注意事项
UMD 模式说明：本包提供 UMD 格式的构建产物，仅支持通过
<script>标签引入，SDK 会自动挂载到window.AIAssistantAgent全局对象。加载顺序：UMD 包必须在应用代码之后加载，因为 SDK 需要挂载 UI 到对应的 DOM 元素上。正确的顺序是：先创建 DOM 容器 → 加载 UMD 包脚本 → 初始化 SDK。
构建配置引入：可以通过构建工具的
publicDir配置将node_modules/@baiducloud/qianfan-ai-assistant/dist目录复制到静态资源目录，然后通过<script>标签引用。文件上传：
uploadFile方法需要同时传入files（File 对象）和conversationId，SDK 会在内部处理文件上传逻辑。流式接口：
agentSpaceRun是一个函数属性，需要实现 SSE（Server-Sent Events）流式请求，并通过回调函数处理消息、完成和错误事件。语音识别：
speechToText方法接收Blob类型的音频数据，非File类型。错误处理：所有异步方法都应该正确处理错误情况，SDK 会在内部捕获并显示错误信息。
TypeScript 类型支持：可以通过引用构建产物中的
dist/index.d.ts文件来获得 TypeScript 类型支持。7. 错误处理：所有异步方法都应该正确处理错误情况，SDK 会在内部捕获并显示错误信息。TypeScript 类型支持：可以通过引用构建产物中的
dist/index.d.ts文件来获得 TypeScript 类型支持。