中文 (简体)

English (US)

中文 (简体)

English (US)

主题

SDK 集成 ​

配置项 ​

ts
interface DataSource {
    appId: number;
    chartId?: number;
    dataAppId?: number;
    datasetId?: number;
    subjectId?: number; // 业务指标主题域 ID
}

interface CompletionConfig {
    meta?: string;
    openChartConfig?: boolean;
    stylesheet?: string;
    i18n?: {
        [key: string]: {
            [key: string]: string;
        };
    };
    onCompletionDone?: (conversationId: number, uid: string) => void;
}

interface Config {
  userConfig: {
    sourceAppId?: number;
    dataSources: DataSource[];
  };
  completionConfig?: CompletionConfig;
  closable?: boolean;
  draggable?: boolean | {
    enable: boolean;
    minWidth: number;
    minHeight: number;
    bounds: 'window' | 'parent';
    position: {
      x: number;
      y: number;
    };
    size: {
      width: number;
      height: number;
    };
  };
  locale?: string;
  i18n?: {
    [key: string]: {
      [key: string]: string;
    };
  };
  stylesheet?: string;
  className?: string;
  style?: React.CSSProperties;
  bodyClassName?: string;
  bodyStyle?: React.CSSProperties;
  header?: string | React.ReactElement;
  systemMsg?: string;
  parser?: {
    selectText: string;
    onSelect: (chart: any) => void;
  };
  chartTheme?: string | Theme;
}
interface Theme {
  base?: string | number;
  background?: string;
  color?: string;
  fontSize?: number;
  fontFamily?: any;
  fontWeight?: string;
  textAlign?: string;
  borderColor?: string;
  borderWidth?: number;
  borderStyle?: string;
  borderRadius?: number;
  boxShadow?: string;
  chartBackground?: string;
  chartPadding?: number;
  schema?: string[];
  mapTheme?: string;
}

// 创建 Copilot 配置对象
const config: Config = {
  userConfig: {
    // sourceAppId: 130870, // 应用集市、应用创作里的应用 id
    dataSources: [
      // 方式一：使用数据包和数据集
      {
        appId: 130870,
        dataAppId: 130870,
        datasetId: 1,
      },
      // 或者 方式二：使用业务指标主题域
      {
        appId: 130871,
        subjectId: 1,
      }
    ],
  },
  completionConfig: {
    meta: 'answer,chart,chartConfig', // 指定要渲染的内容组合
    openChartConfig: false, // 是否展开取数逻辑面板，默认为 true
    stylesheet: ':host > *, ::before, ::after { --brand: #4CAF50; }',
    i18n: {
      "zh-CN": {
        'copilot.question-reasoning': '问题理解',
        'copilot.question-answer': '数据表现',
        'copilot.question-reasoning-logic': '取数逻辑'
      }
    },
    onCompletionDone: (conversationId, uid) => {
      console.log('AI completion done:', conversationId, uid);
    },
  },
  closable: true, // 可选，是否显示关闭按钮，默认为 false
  draggable: { // 可选，是否可拖拽，默认不可以拖拽
    enable: true,
    minWidth: 440,
    minHeight: 440,
    bounds: 'window',
    position: {
      x: window.innerWidth - 480,
      y: 20,
    },
    size: {
      width: 440,
      height: window.innerHeight * 0.8,
    },
  },
  locale: 'zh-CN', // 可选，语言设置，默认为中文简体
  i18n: {
    "zh-CN": {
      'copilot.question-reasoning': '问题理解',
      'copilot.question-answer': '数据表现',
      'copilot.question-reasoning-logic': '取数逻辑'
    },
    "en-US": {
      'copilot.question-reasoning': 'Question Understanding',
      'copilot.question-answer': 'Data Performance',
      'copilot.question-reasoning-logic': 'Data Logic'
    }
  },
  stylesheet: '', // 可选，自定义 CSS 样式
  className: '', // 可选，自定义类名
  style: {}, // 可选，自定义样式
  bodyClassName: '', // 可选，对话框内容容器的类名
  bodyStyle: {}, // 可选，对话框内容容器的样式
  header: '', // 可选，标题内额外内容
  systemMsg: '欢迎使用智能分析助手', // 可选，欢迎语，默认值
  parser: {
    selectText: '选择图表', // 按钮文案
    onSelect: (chart) => {
      // 点击按钮时触发的事件，chart 参数需要根据实际使用场景定义类型
      console.log('图表选择事件', chart);
    },
  },
  chartTheme: 'HAWAII_SEA', // 可选，图表主题，参考仪表盘主题
};

> [!NOTE]
> 在 `dataSources` 配置中，每个数据源只能使用以下两种模式之一：
> 1. 数据包与数据集模式：提供 `dataAppId` 和 `datasetId`
> 2. 业务指标主题域模式：提供 `subjectId`
>
> 不能在同一个数据源配置中混用这两种模式。

## 登录认证

集成 SDK 时，您可能需要进行登录认证。我们提供两种方式：

1. **SSO 单点登录**：如果您的系统已与衡石系统集成，无需额外登录。
2. **JWT 认证**：通过以下代码使用 JWT 进行登录认证：

```js
fetch('https://develop.hengshi.org/api/auth/login-info?activeAuth=jwt-param&jwtParam=您的 JWT 参数')
  .then(response => {
    // 登录成功，继续使用 SDK
  })
  .catch(error => {
    // 登录失败，处理错误
  });

提示

确保您已经在 '设置->组织管理->认证方式->JWT 请求参数' 中配置了 JWT。

请将 '您的 JWT 参数' 替换为实际的 JWT 参数。

自定义样式 ​

如果您想自定义 AI 助手的样式，可以通过以下 CSS 代码实现：

css
/* 示例： 使用 css 批量自定义皮肤样式 */
*, ::before, ::after {
  --brand: #4CAF50; // 这是系统整体的品牌色
}
/* 设置 AI 助手对话框根元素样式 */
.hengshi-copilot-sdk .hst-copilot {
  position: fixed;
  // z-index: 1; // 按需设定
  top: 10vh;
  right: 50px;
  width: 440px;
  height: 80vh;
  border-width: 1px;
}
/* 设置 AI 助手 标题 元素样式 */
.hengshi-copilot-sdk .hst-copilot-header {
  color: #fff;
  background-color: darkslategray;
}
/* 设置 AI 助手 对话区域 元素样式 */
.hengshi-copilot-sdk .hst-copilot-conversations {
  border-color: #aaa;
  background-color: darkslategray;
  height: calc(100% - 50px);
}
/* 设置 AI 助手 消息 元素样式 */
.hengshi-copilot-sdk .hst-copilot-msg,
/* 设置 AI 助手 消息下方 ICON 操作 元素样式 */
.hengshi-copilot-sdk .hst-copilot-msg > .hs-relative > *,
/* 设置 AI 助手 辅助信息 元素样式 */
.hengshi-copilot-sdk .hst-copilot-mark {
  color: #fff;
}
.hengshi-copilot-sdk .hst-copilot-mark .hs-bg-\[color\:var\(--hs-bg-lighter\)\] {
  background-color: transparent;
}
/* 设置 AI 助手 消息下方 ICON 操作 hover 时 元素背景样式 */
.hengshi-copilot-sdk .hover\:hs-bg-\[\#eee\]:hover {
  --tw-bg-opacity: .2;
}
/* 设置 AI 助手 AI 消息气泡 元素样式 */
.hengshi-copilot-sdk .hst-copilot-msg-bot .hst-copilot-msg-inner,
/* 设置 AI 助手 用户消息气泡 元素样式 */
.hengshi-copilot-sdk .hst-copilot-msg-user .hst-copilot-msg-inner {
  border-color: darkgray;
  background-color: darkgray;
}
/* 设置 AI 助手推荐问题的问题气泡背景色 */
.hengshi-copilot-sdk .hst-copilot-msg-inner .hst-copilot-msg-inner {
  background-color: slategray !important;
}
/* 设置 AI 助手 输入内容区域 元素样式 */
.hengshi-copilot-sdk .hst-copilot-prompt {
  color: #fff;
  background-color: darkslategray;
}
/* 设置 AI 助手 输入框 元素样式 */
.hengshi-copilot-sdk .hst-copilot-prompt textarea {
  color: #fff;
  border-color: darkgray !important;
}
.hengshi-copilot-sdk .hst-copilot-prompt .hs-from-\[\#f1f1f1\],
.hengshi-copilot-sdk .hst-copilot-prompt .hs-to-\[\#f1f1f1\] {
  --tw-gradient-to: darkslategray;
}

将上述 css 作为字符串传递在 Copilot 配置中的 stylesheet 即可：

ts
// 创建 Copilot 配置对象
const config: Config = {
  ...
  stylesheet: css, 
  ...
};

API 方式的集成也有前端和后端两种方式，前端方式直接调用 Copilot SDK 提供的 js API，后端方式则通过 http 接口。

拦截 api 请求、自定义 api 请求 ​

你可以在 copilotConfig 中配置 api 拦截 api 请求、自定义 api 请求。

有下列 api 可以配置：

  • requestFetchConversations: 获取对话列表
  • requestCreateConversation: 创建对话
  • requestFetchConversation: 获取对话详情
  • requestDeleteConversation: 删除对话
  • requestFetchChats: 获取一个对话里聊天记录
  • requestCreateChat: 创建一条聊天记录
  • requestFetchChat: 获取一条聊天记录
  • requestUpdateChat: 更新一条聊天记录
  • requestDeleteChat: 删除一条聊天记录
  • requestfetchChatLogs: 获取一条聊天记录的日志
  • requestRegenerateChat: 重新生成回答

每一个 api 都是一个 js function，接收的参数是一个 object, 规则如下：

  • requestFetchConversations({ offset?: number, limit?: number })
  • requestCreateConversation({ body: { title: string }})
  • requestFetchConversation({ id: number })
  • requestDeleteConversation({ id: number })
  • requestFetchChats({ id: number, offset?: number, limit?: number })
  • requestCreateChat({ id: number, body: { prompt: string, userConfig: object }})
  • requestFetchChat({ id: number, chatUid: string })
  • requestUpdateChat({ id: number, chatUid: string, body: object })
  • requestDeleteChat({ id: number, chatUid: string })
  • requestfetchChatLogs({ id: number, chatUid: string })
  • requestRegenerateChat({ id: number, chatUid: string })

function 返回值也是一个 object，格式如下：

js
{
  abort: function abort() {}, // abort 接口请求
  value: Promise, // 接口请求的 Promise
}

例如你想要在每一次对话创建时，拦截请求并添加一些自定义参数，你可以这样配置：

js
const copilotConfig = {
  // ...
  api: {
    // 自定义创建对话的 api
    requestCreateChat: params => {
      // 添加一些自定义参数
      if (!params.body.yourCustomProperty) {
        params.body.yourCustomProperty = 'yourCustomValue';
      }
      return copilotInstance.context.endpoints.requestCreateChat(params);
    },
    // ... 也可以配置其他 api
  },
};

衡石分析平台使用手册

版权所有 © 2016-present hengshi.com