@baiducloud/qianfan-deep-research

v0.0.6

Published

2 days ago

Deep Research SDK - 深度研究SDK，提供UMD格式的第三方集成能力

0High
0Medium
0Low

deep-research sdk umd react

Deep Research SDK

深度研究 SDK，提供 UMD 格式的第三方集成能力，支持通过 <script> 标签引入使用。

安装

通过 npm 安装

npm install @baiducloud/qianfan-deep-research

注意：本包提供 UMD 格式的构建产物，仅支持通过 <script> 标签引入。

使用方法

OpenAPI 文档

SDK 需要配合 OpenAPI 自行实现接口调用。在实现 IClientService 接口时，请参考千帆 API 文档中的深度研究 Agent 相关接口规范。

UMD引入

通过 <script> 标签引入，SDK 会自动挂载到 window.DeepResearchAgent。

引入方式

方式一：直接引用构建产物

如果已将 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-deep-research/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>Deep Research SDK 示例</title>
</head>
<body>
    <!-- 步骤1：创建容器（必须在脚本加载前存在） -->
    <div id="deep-research-container"></div>

    <!-- 步骤2：加载 UMD 包（必须在应用代码之前加载） -->
    <script src="/dist/index.js"></script>
    <!-- 或使用通过构建配置引入的路径 -->
    <!-- <script src="/index.js"></script> -->

    <!-- 步骤3：初始化 SDK（必须在 UMD 包加载后执行） -->
    <script>
        // 实现 IClientService 接口（接口定义见下方）
        const clientService = {
            /** 对话接口 - SSE流式接口 */
            deepResearchRun: (param, callbacks, options) => {
                    // param: 请求参数对象
                    // callbacks: {
                    //     onMessage: (message: string) => void;  // 收到消息时调用
                    //     onCompleted: () => void;               // 完成时调用
                    //     onError: (error: Error) => void;        // 错误时调用
                    // }
                    // options?: {
                    //     abortController?: AbortController;      // 用于取消请求
                    //     headers?: HeadersInit;                  // 请求头
                    // }

                    // 实现 SSE 流式请求逻辑
                    // 示例：通过 EventSource 或其他方式实现流式请求
                    const eventSource = new EventSource('/api/stream', {
                        headers: options?.headers
                    });

                    eventSource.onmessage = (event) => {
                        callbacks.onMessage(event.data);
                    };

                    eventSource.onerror = (error) => {
                        callbacks.onError(new Error('Stream error'));
                        eventSource.close();
                    };

                    // 监听 abort 信号
                    options?.abortController?.signal.addEventListener('abort', () => {
                        eventSource.close();
                        callbacks.onError(new Error('Request aborted'));
                    });
            },

            /** 创建对话 */
            async createConversation() {
                // 返回对话ID
                return 'conversation-id-123';
            },

            /** 文件上传 */
            async uploadFile(files, conversationId) {
                // 实现文件上传逻辑，返回文件ID和对话ID
                return {
                    file_id: 'file-id-123',
                    conversation_id: conversationId
                };
            },

            /** 文件解析触发 */
            async fileParseCommit(fileIds) {
                // 实现文件解析提交逻辑，返回任务ID数组
                return fileIds.map((fileId, index) => `task-id-${index}`);
            },

            /** 文件解析状态查询 */
            async fileParseQuery(taskIds) {
                // 实现文件解析状态查询逻辑
                return taskIds.map((taskId, index) => ({
                    file_id: `file-id-${index}`,
                    parse_status: 'success' // 文件解析状态：init | running | success | failed
                }));
            },

            /** 应用基本信息查询 */
            async getAppInfo() {
                return {
                    name: '深度研究 Agent',
                    prologue: '广泛深度迭代检索全网信息及上传文件，根据指定大纲生成深度研究报告，适用于金融研报、科研综述等场景',
                    avatarUrl: 'https://deepresearch.baidu.com/logo.png'
                };
            }
        };

        // 初始化 SDK
        DeepResearchAgent.init(
            document.getElementById('deep-research-container'),
            clientService
        );
    </script>
</body>
</html>

类型声明文件

构建后会生成 dist/index.d.ts 类型声明文件，可以通过以下方式使用类型：

// 从类型声明文件导入类型
import type { IClientService, IFileUploadRes, IFileParseRes, IAppInfo } from '@baiducloud/qianfan-deep-research/dist/index.d.ts';

IClientService 接口定义

/** SDK模式下的客户端服务接口 */
interface IClientService {
    /** 对话接口 - SSE流式接口 */
    deepResearchRun: (
        param: any,
        callbacks: {
            /** 接受到消息的回调 */
            onMessage: (message: string) => void;
            /** 任务执行完成的回调 */
            onCompleted: () => void;
            /** 任务执行错误的回调 */
            onError: (error: Error) => void;
        },
        options?: {
            abortController?: AbortController;
            headers?: HeadersInit;
        }
    ) => void;

    /** 创建对话 */
    createConversation(): Promise<string>;

    /** 文件上传 */
    uploadFile(files: File, conversationId: string): Promise<IFileUploadRes>;

    /** 文件解析触发 */
    fileParseCommit(fileIds: string[]): Promise<string[]>;

    /** 文件解析状态查询 */
    fileParseQuery(taskIds: string[]): Promise<IFileParseRes[]>;

    /** 应用基本信息查询 */
    getAppInfo(): Promise<IAppInfo>;
}

/** 文件上传返回结构 */
interface IFileUploadRes {
    /** 文件id */
    file_id: string;
    /** 对话id */
    conversation_id: string;
}

/** 文件解析状态返回结构 */
interface IFileParseRes {
    /** 文件id */
    file_id: string;
    /** 文件解析状态 init | running | success | failed */
    parse_status: string;
}

/** 应用基本信息返回结构 */
interface IAppInfo {
    /** 应用名称 */
    name?: string;
    /** 应用开场白 */
    prologue?: string;
    /** 应用头像 */
    avatarUrl?: string;
}

开发调试

在使用 SDK 进行开发时，建议在浏览器开发者工具中查看控制台输出，以便排查问题和调试接口调用。

依赖说明

SDK 采用全量打包方式，所有依赖（包括 React、ReactDOM 等）都已打包在 UMD 文件中，用户无需额外引入任何依赖即可使用。

注意事项

UMD 模式说明：本包提供 UMD 格式的构建产物，仅支持通过 <script> 标签引入，SDK 会自动挂载到 window.DeepResearchAgent 全局对象。
加载顺序：UMD 包必须在应用代码之后加载，因为 SDK 需要挂载 UI 到对应的 DOM 元素上。正确的顺序是：先创建 DOM 容器 → 加载 UMD 包脚本 → 初始化 SDK。
构建配置引入：可以通过构建工具的 publicDir 配置将 node_modules/@baiducloud/qianfan-deep-research/dist 目录复制到静态资源目录，然后通过 <script> 标签引用。
文件上传：uploadFile 方法需要同时传入 files（File 对象）和 conversationId，SDK 会在内部处理文件上传逻辑。
流式接口：deepResearchRun 是一个函数属性，需要实现 SSE（Server-Sent Events）流式请求，并通过回调函数处理消息、完成和错误事件。
对话ID管理：SDK 会在需要时调用 createConversation 创建新对话，也可以在上传文件时传入已有的 conversationId。
错误处理：所有异步方法都应该正确处理错误情况，SDK 会在内部捕获并显示错误信息。
TypeScript 类型支持：可以通过引用构建产物中的 dist/index.d.ts 文件来获得 TypeScript 类型支持。