衡石 ChatBI 用户手册
产品概述
衡石 ChatBI 是一款融合了 AI 技术的智能数据分析工具，旨在为企业业务人员提供直观、高效的数据交互体验。通过自然语言处理技术，用户可以直接与数据进行对话，快速获取所需信息，从而为业务决策提供有力支持。此外，衡石 ChatBI 支持私有化部署，确保企业数据的安全性和隐私性。
安装与配置
先决条件
在开始使用衡石 ChatBI 之前，请确保已完成以下步骤：
配置大模型
衡石服务启动后，进入系统设置的“功能配置”页面，配置 AI 助手 的相关信息，包括大模型的地址和密钥等。
不了解配置项？请参考常见问题。
使用指南
提升大模型的理解能力
为了确保 ChatBI 能够准确理解您的业务需求，建议进行以下配置：
1. 提升对公司业务、行业术语和私域知识的理解
在系统设置的 AI 助手控制台中，使用自然语言在 UserSystem 提示词中描述您的业务场景和术语。确保模型通用配置中的使用模型推理意图已开启。
例如，若需禁止回答某类问题，可在提示词中注明“不要回答收入相关的问题”。
2. 提升对数据的理解
- 数据集命名：确保数据集名称简洁明了，能够清晰反映其用途。
- 知识管理：在知识管理中详细描述数据集的用途、隐含规则（如过滤条件）、同义词及专有业务词语对应的字段和指标。
- 字段管理：确保字段名称简洁且具有描述性，避免使用特殊字符。在字段描述中详细说明字段的用途，如“默认用我做时间轴”。
- 指标管理：确保原子指标名称简洁且具有描述性，避免使用特殊字符。在原子指标描述中详细说明指标的用途。
- 字段隐藏：对于不参与问答的字段，建议隐藏，以减少发送给大模型的 token 数量，提高响应速度并降低成本。
- 字段与指标区分：确保字段名和指标名不相似，避免混淆。不需要参与回答问题的字段建议隐藏，不需要的指标建议删除。
- 数据向量化：发布应用时会触发数据集的智能数据向量化任务，您也可以手动触发“智能数据向量化”任务。该任务会对数据集进行字段值排重并向量化，以提高过滤准确性。
- 智能学习：建议触发“智能学习”任务，执行通用例子到数据集特异例子的转换。执行完成后，需人工检查学习结果，并进行增删改操作，以提升助手的能力。
3. 提升对复杂计算的理解
对于复杂的聚合计算，建议将其定义为指标，以减少模型在取数时的复杂度，并避免大模型对私域知识的误解。
例如，广告公司的 ROI 与制造业的 ROI 计算方式不同，但大模型无法自动识别这些差异。因此，建议您创建一个指标，并详细描述其含义，以确保大模型在取数时不会自行创造计算公式。
使用场景
1. 去分析
去分析是 HENGSHI SENSE 图表的增强功能。系统将指标分析功能与发布后的应用相结合，使发布后的图表具备二次分析的能力。
快速入门
- 登录系统：打开浏览器，访问衡石 ChatBI 的登录页面，输入您的账号和密码。
- 配置 AI 助手：进入“系统设置” > AI 助手配置，输入大模型的地址和密钥。(需要有系统管理员角色)
- 创建应用：在“应用创作”页面，点击新建应用，新建空白应用。
- 创建数据集：在“数据集”页面，点击新建数据集，上传您的数据，或通过数据连接连接到您的数据。
- 创建仪表盘：在应用中创建仪表盘，添加图表，并选择刚才创建的数据集作为数据来源。
- 发布应用：完成图表创作后，点击发布应用，将应用发布到应用集市，发布时勾选开启
去分析功能。 - 去分析：在应用集市中，点击已发布的应用，进入应用详情页，点击图表右上角的去分析按钮，即可进入二次分析功能页面。
- 开始对话：在 ChatBI 界面中输入您的问题，例如“显示上个月的销售额”。
- 查看分析结果：系统将生成图表或表格，您可以直接在界面上进行交互和再次分析。
2. 在仪表盘中对话
通过全局 JS 功能以及仪表盘控件事件，您可以在仪表盘中嵌入 ChatBI，使用户能够直接在仪表盘中与数据交互，获取数据洞察和进行二次分析。
快速入门
- 开启 sdk：登录衡石 ChatBI，进入“系统设置” > 全局 JS 功能，参考在衡石系统内的仪表盘里集成 Copilot，将代码配置好。
- 与去分析的快速入门步骤相同类似，需要创建好应用、仪表盘。
- 添加按钮：在仪表盘中添加一个按钮，并设置按钮的控件事件，参考在衡石系统内的仪表盘里集成 Copilot。
- 点击按钮：在仪表盘中点击按钮，即可弹出 ChatBI 窗口，进行对话分析。
3. 集成 ChatBI
HENGSHI SENSE 提供了多种集成方式，您可以根据需求选择合适的方式：
IFRAME 集成
使用 iframe 将 ChatBI 集成到现有系统中，实现与 HENGSHI SENSE BI PaaS 平台的无缝对接。iframe 的特点是简单易用，直接使用衡石 ChatBI 的对话组件、样式和功能，无需你的系统进行额外开发。
SDK 集成
通过 sdk 将 ChatBI 集成到现有系统中，可以实现更复杂的业务逻辑，实现更精细的控制，如自定义 UI 等。SDK 提供了丰富的配置项，满足个性化需求。根据你的开发团队的技术栈，选择合适的 SDK 集成方式，我们提供了两种 js sdk，分别是 Vanilla JS SDK 和 React Js SDK。
如何选择使用哪种 sdk？
vanilla js 与 react js 的区别在于，vanilla js 是纯 js，不依赖任何框架，而 react js 是基于 react 框架的 js，需要先安装 react。
vanilla js sdk 提供的 UI、功能与 iframe 集成类似，直接使用衡石 ChatBI 的对话组件、样式和功能，但通过 js 的控制、sdk 初始化时的传参等，可以做到自定义 api 请求，拦截请求等。
react js sdk 则只提供了 Completion UI 组件和 useProvider 的 hook，适用于你在自己的 react 项目中使用。
API 集成
通过 后端 API 将 ChatBI 能力集成到你的飞书、钉钉、企微、dify workflow 中，实现定制化的业务逻辑。
常见问题
测试模型连接失败怎么排查？
连接失败有多种原因，建议按以下步骤进行排查：
检查请求地址
确保模型地址是正确的，不同厂商提供的模型地址是不同的，具体请查找你购买的厂商提供的文档。
我们可以提供初步排查指引：
- 各家模型提供商的模型地址通常都以
<host>/chat/completions结尾，而不是只有域名，例如https://api.openai.com/v1/chat/completions。 - 假如你的模型厂商是 Azure OpenAI，模型地址的构成是
https://<your-tenant>.openai.azure.com/openai/deployments/<your-model>/chat/completions，其中<your-tenant>是你的租户名，<your-model>是你的模型名，需要你登录到 Azure OpenAI 平台查看，更详细步骤请参考连接 Azure OpenAI。 - 假如你的模型厂商是通义千问，模型地址有两种，一种是兼容 OpenAI 格式的
https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions，另一种是通义千问特有的https://dashscope.aliyuncs.com/api/v1/services/aigc/text-generation/generation，当你使用 OpenAI 兼容格式(指 url 里包含 compatible-mode)时，请在衡石智能查数助手模型配置中选择OpenAI或OpenAI-API-compatible作为供应商。 - 假如你的模型是私有部署的，请确保模型地址是正确的，并且模型服务已经启动，确保模型提供了 HTTP 服务，并且接口的格式与 OpenAI API 接口兼容。
检查密钥
- 各家模型提供商的大模型接口通常需要密钥才能访问，请确保你提供的密钥是正确的，并且有访问该模型的权限。
- 假如你公司采用了自己部署的模型，密钥是有可能不需要的，请与你公司开发人员或你公司工程团队确认。
检查模型名称
- 各家模型提供商普遍都提供了多种模型，请根据需要选择合适的模型，并确保你提供的模型名称是正确的，并且有访问该模型的权限。
- 假如你公司采用了自己部署的模型，模型名称是有可能不需要的，请与你公司开发人员或你公司工程团队确认。
问数时报错怎么排查？
- 向量数据库是否已安装？若没有请按照AI 助手部署文档完成相关服务的安装及部署。
- 模型是否能连接？按照上一个问题的排查步骤，检查模型是否能连接。
向量数据库地址怎么填？
按照AI 助手部署文档完成相关服务的安装及部署即可，无需手动填写。
是否支持其他向量模型？
目前暂不支持，如有需求，请联系售后工程师。