Data Agent

概述

在 HENGSHI SENSE 中，借助大模型的能力 Data Agent 可以帮助用户充分使用数据。基于对话式交互体验，Data Agent 可以帮助用户完成从业务数据即时分析到指标创建、仪表盘生成等任务。我们还将持续在产品中融入 Agent 能力，旨在提高数据分析及数据管理人员的工作效率，简化工作流程及复杂任务。

安装与配置

先决条件

请确保完成以下步骤使 Data Agent 进入可用状态：

安装与启动：按照安装与启动指南完成衡石服务的安装。
AI 部署：按照AI 部署文档完成相关服务的安装及部署。

配置大模型

衡石服务启动后，进入系统设置的“功能配置”页面，配置 Data Agent 的相关信息，包括大模型的地址和密钥等。

Data Agent 功能配置

使用指南

在使用 Data Agent 之前，需要对数据做一些处理，以确保 Data Agent 理解独特的业务背景，能够优先识别正确信息，并提供一致、可靠且符合目标的响应。

为 Data Agent 准备数据，就是在为高质量、接地气且懂场景的 Data Agent 体验打下根基。如果数据杂乱无章或含义模糊，Data Agent 可能难以准确理解，给出的结果要么流于表面，要么偏离事实，甚至可能产生误导。

投入精力做好数据准备，Data Agent 就能真正吃透业务场景，精准抓取关键信息，给出的回答不仅稳定可靠，更与目标高度契合，更能让 Data Agent 发挥实效。

注意

AI 的行为是不确定的，即使输入相同内容，AI 也并不总是产生完全相同的响应。

为 AI 编写提示词

行业术语、私域知识

为了让大模型发挥更强性能，我们在系统设置的 Data Agent 控制台中提供了配置提示词的功能，您可以使用自然语言在 UserSystem 提示词中向大模型提供包括不限于公司行业背景信息、业务逻辑、思考分析方向指引、特定指导，Data Agent 会运用这些指令来理解组织内部的语言习惯、专业术语和分析重点，准确理解你所在领域的专有术语和分析预期，从而提升回答质量与相关性。

提示词可以帮助 Data Agent 根据您的行业、战略目标、术语或运营逻辑做出响应，进而可以确保用户获得更准确、更相关的数据分析。例如：

大促是指每年的10月11日至11月11日
当用户提到产品相关问题时，请同时获取产品名称和产品 id

UserSystem 提示词

数据集分析规则

在数据集的知识管理中，您可以使用自然语言详细描述数据集的用途、隐含规则（如过滤条件）、同义词及专有业务词语对应的字段和指标，指导 Data Agent 如何进行某些类型的分析。例如：

"小订单"是指同一订单号下订单数量汇总小于等于2的订单
"财年"是指上年的12月1日开始到本年的11月30日结束。例如2025财年是指2024/12/1至2025/11/30，2024财年是2023/12/1至2024/11/30
当问 AAA 时，同时列出 BBB、CCC、DDD 等指标数据

数据集提示词

注意

了解提示词工程的最佳做法非常重要。AI 可能对收到的提示词很敏感，提示词的构造会影响 AI 的理解和输出。提示词的特点如下：

明确、具体
使用类比和描述性语言
避免歧义
使用 markdown 按主题按结构化编写
尽可能将复杂的指令分解为简单的步骤

将 agent 与企业知识库、外部 api 等打通

Data Agent 通过“工具 (Tool)” 以插件化方式扩展能力。只要目标系统提供可访问的 HTTP/HTTPS 接口（REST、GraphQL、基于 HTTP 的 RPC 等），就可以被接入：企业内部知识库、全文 / 向量检索、内部微服务、第三方 SaaS / 平台 API、搜索引擎、RPA 服务…… 这意味着 Agent 不仅能理解并回答，还能实时“调用”你的外部/内部系统获得或写入数据，形成强大的能力边界。

下面以接入 Tavily Web Search 为例，演示如何在“系统设置 → 全局 JS”中注册一个搜索类 Tool：

// 确认 Agent 运行环境已注入 createTool
if (typeof window.heisenberg?.createTool === 'function') {
  const apiKey = '<tavily_api_key>'; // 建议使用代理服务管理功能，而不是直接写死
  window.heisenberg.createTool({
    // 工具名称：英文 + 下划线，便于 LLM 可靠指称
    name: 'web_search',
    // 工具用途：帮助模型判断何时调用
    description: '使用 Tavily 搜索最新的互联网信息，并返回答案与来源',
    // 参数：完全可按需扩展 —— 任何你希望 LLM 生成 / 传入的控制项都可以放进来
    parameters: window.heisenberg.zod.object({
      plan: window.heisenberg.zod.string().describe('你调用该工具的目的与关键信息摘录'),
      query: window.heisenberg.zod.string().describe('搜索内容/查询关键词'),
      max_results: window.heisenberg.zod.number().min(1).max(20).default(5).describe('需要的结果条数'),
      // 可继续添加如 language、time_range、site、freshness 等参数
    }),
    // 具体执行逻辑：只要能发起 HTTP 请求即可集成（fetch / axios / 自建 SDK 均可）
    execute: async (args) => {
      try {
        const { query, max_results } = args;
        const resp = await fetch('https://api.tavily.com/search', {
          method: 'POST',
          headers: {
            Authorization: `Bearer ${apiKey}`,
            'Content-Type': 'application/json',
          },
          body: JSON.stringify({
            query,
            max_results,
            search_depth: 'basic',
            include_answer: true,
            include_raw_content: true,
            include_images: false,
            time_range: null,
          }),
        });
        const data = await resp.json().catch(() => ({}));
        if (!resp.ok) {
          return `搜索失败：${data?.error || resp.status} ${resp.statusText}`;
        }
        return `搜索结果：\n\n${data.answer || '（无直接答案）'}\n\n来源：\n${JSON.stringify(data.results || [], null, 2)}`;
      } catch (err) {
        return `搜索时出现错误：${err?.message || String(err)}`;
      }
    },
  });
}

保存并刷新后，Data Agent 即可通过该 Tool 搜索互联网。以此类推：只要目标能力能够通过 HTTP 请求访问，就可以封装成一个 Tool 并被 Agent 动态调用，快速扩展到企业内部系统或任意第三方服务。

通用接入建议：

身份与安全：优先采用代理服务管理，避免直接在全局 JS 中明文暴露 token。
返回格式：将原始响应提炼为简洁文本或结构化 JSON，再拼接成字符串返回，减少无关噪音。
最小权限：服务端实施鉴权、IP/速率限制与访问审计，防止滥用。
参数设计：让 LLM 只暴露必要、可控的参数，减少越权或无效调用。

提示

你可以注册多个 Tool（搜索、知识库检索、报表生成、流程触发、工单创建……），Agent 会在推理链中自主选择并组合调用，形成持续可演进的“能力面”。
通过全局 JS 拓展的工具目前只能在网页端使用，无法在 api agent 模式下使用。

为 AI 准备数据

数据向量化

为了在海量数据资产中更高效、准确地定位到与问题最相关的信息，建议对数据进行“向量化”处理。向量化会将字段/原子指标的名称、描述、字段值等文本信息转换为可计算的语义向量，并写入向量数据库，使 Data Agent 能够基于语义进行检索与召回，而不仅仅依赖关键词匹配。

向量化的收益：

更高的相关性：理解同义词、行业术语与上下文，减少漏检与误检。
更快的响应：缩小检索范围，减少大模型上下文填充成本。
更强的可扩展性：支持跨数据包的语义联想与知识链接，适配多语言场景。
持续优化：配合“智能学习”任务，结合人审结果不断提升问答质量。

操作步骤：

进入目标数据包页面，在操作栏点击“向量化”。
在系统设置-任务管理-执行计划中查看进度，按需开启定时任务，提升召回的稳定性与覆盖面。

数据向量化

数据管理

良好的数据管理是 Data Agent 正确理解业务语义与指标口径的基础。通过统一命名规范、补全字段/指标的描述、合理设置数据类型，以及对无关对象进行隐藏或清理，可以显著提升问答相关性与响应速度，降低大模型上下文成本并减少误解。建议在数据包发布前和日常维护时，按下列清单进行自检；配合“数据向量化”和“智能学习”使用，效果更佳。

数据集命名：确保数据集名称简洁明了，能够清晰反映其用途。
字段管理：确保字段名称简洁且具有描述性，避免使用特殊字符。在字段描述中详细说明字段的用途，如“默认用我做时间轴”。另外，字段的类型需要跟使用目的一致，比如需要求和的字段应该用数字类型，日期字段应该用日期类型等等。
指标管理：确保原子指标名称简洁且具有描述性，避免使用特殊字符。在原子指标描述中详细说明指标的用途。
字段隐藏：对于不参与问答的字段，建议隐藏，以减少发送给大模型的 token 数量，提高响应速度并降低成本。
字段与指标区分：确保字段名和指标名不相似，避免混淆。不需要参与回答问题的字段建议隐藏，不需要的指标建议删除。
智能学习：建议触发“智能学习”任务，执行通用例子到数据集特异例子的转换。执行完成后，需人工检查学习结果，并进行增删改操作，以提升助手的能力。

提升对复杂计算的理解

在数据侧预先沉淀可复用的业务口径，以指标形式对外暴露，可以在问数场景中获得更高准确率、稳定性与可解释性。

实践建议：

对行业特有口径（如金融风控、广告投放、电商转化）给出域内统一定义，并在数据集的知识管理中维护同义词映射。
对易混淆概念（如“转化率”“ROI”“复购率”）建立“业务术语 → 指标”的映射，避免模型自由组合字段。
优先用“指标”承载口径，而非单次对话里的临时计算表达式；重要指标建议建立版本与变更记录，防止口径漂移。

示例（ROI）：

广告/电商：ROI = GMV ÷ 广告投放成本。请在指标描述中明确是否含优惠券、是否扣除退款与运费、是否包含平台服务费，统计口径以“支付时间/下单时间”为准，以及时间窗口（如自然日/周/月）。
制造/项目：ROI = (收益 − 成本) ÷ 成本，窗口为项目全周期或财务期。

使用场景

Data Agent 的 agent 模式特点有：

不限制对话来源

Data Agent 将根据用户的输入内容，自主判断用户意图，分解用户需求，在用户有权限的数据范围内，从数据集市、应用集市、应用创作中进行混合检索，再从目标数据来源中分析并查询数据，最终给出回答。

复杂问题拆解

Data Agent 不仅支持常规数据查询问题，还支持一次输入多个问题，尤其是前后存在推理关系的情况下。Data Agent 将会视需求复杂程度进行一次或多次数据查询。

环境感知

Data Agent 能够读取登录账号的信息，可以丝滑理解用户输入内容中的指示代词（如“我的部门”等用户属性）。此外还可以读取用户正在浏览的页面信息，当用户在具体的数据包、数据集、仪表盘页面时，Agent 在处理数据查询等需求时将直接基于当前页面的信息进行交互。

在这些能力的加持下，Data Agent 将能够化身为可视化创作助手、指标创作助手，或者分析师助理等多重身份。

智能问数

升级 Data Agent 后，智能问数不再局限于有限的数据范围内的，不再需要手动选择范围才能开始问数。这意味着 agent 的任务将涉及到寻找内容、临时分析或见解。

仪表盘对话示例

可视化创作

Data Agent 可以根据用户需求在仪表盘列表页面开始从零创建仪表盘，也可以直接编辑已有的仪表盘，不论是图表创作、添加过滤器、分析数据添加富文本报告，还是调整仪表盘布局、调整颜色、批量操作控件。

仪表盘创作示例

智能解读

为了方便业务用户使用 Data Agent 做业务数据分析、定期复盘、数据解读等，我们增加了 “智能解读” 的配置以及快捷按钮，在仪表盘页面时，Data Agent 中将出现 “智能解读” 按钮，点击后即可让 Data Agent 跟随预先配置好的解读思路，进行实时的数据查询、异常识别、分解、下钻，最后给出解读报告。

仪表盘数据解读

在仪表盘编辑状态时，右上角下拉菜单中可以点击弹出“智能解读配置”，其中用户可以按自己的业务需求配置固定形式的解读思路，也可以点击按钮让 AI 分析仪表盘结构和数据，生成解读思路模板。仪表盘的图表也支持各自单独配置解读思路，图表控件右上角有“智能解读”按钮，点击将会唤起 Data Agent 并发送解读指令。

仪表盘数据解读设置

智能解读功能通过人工智能技术，对用户指定的数据范围执行自动化分析，其核心能力与边界如下：

数据查询与提取：根据用户指令或内置分析思路，从数据源中快速定位并提取相关信息。
数据汇总与归纳：对查询结果进行多维度整合、统计与浓缩，揭示数据中的关键事实、规律与现状。
生成描述性报告：将分析结果以结构化的报告或简洁的文本总结形式输出，帮助用户理解“过去发生了什么”以及“当前情况如何”。

注意智能解读不进行预测推断，本功能严格基于已有及历史数据进行分析，其输出为对既定事实的描述与总结。它无法预测未来的数据走势、业务结果或任何尚未发生的概率性事件。

注意

复杂报表、复杂表格不支持智能解读

表达式编写

Data Agent 基于对 HQL 的理解，可以辅助用户编写复杂表达式、创建指标。

指标创作示例

集成 ChatBI

HENGSHI SENSE 提供了多种集成方式，您可以根据需求选择合适的方式：

IFRAME 集成

使用 iframe 将 ChatBI 集成到现有系统中，实现与 HENGSHI SENSE BI PaaS 平台的无缝对接。iframe 的特点是简单易用，直接使用衡石 ChatBI 的对话组件、样式和功能，无需你的系统进行额外开发。

SDK 集成

通过 sdk 将 ChatBI 集成到现有系统中，可以实现更复杂的业务逻辑，实现更精细的控制，如自定义 UI 等。SDK 提供了丰富的配置项，满足个性化需求。根据你的开发团队的技术栈，选择合适的 SDK 集成方式，我们提供了两种 js sdk，分别是原生 JS SDK 和 React JS SDK。

如何选择使用哪种 sdk？

原生 js 与 react js 的区别在于，原生 js 是纯 js，不依赖任何框架，而 react js 是基于 react 框架的 js，需要先安装 react。

原生 js sdk 提供的 UI、功能与 iframe 集成类似，直接使用衡石 ChatBI 的对话组件、样式和功能，但通过 js 的控制、sdk 初始化时的传参等，可以做到自定义 api 请求，拦截请求等。

react js sdk 则只提供了 Completion UI 组件和 useProvider 的 hook，适用于你在自己的 react 项目中使用。

API 集成

通过后端 API 将 ChatBI 能力集成到你的飞书、钉钉、企微、dify workflow 中，实现定制化的业务逻辑。dify workflow 工具可以参考附件衡石AI工作流工具v1.0.1.zip

企业即时通讯工具数据问答机器人

可以通过企业即时通讯工具数据问答机器人来创建智能数据问答机器人，关联衡石 ChatBI 中的相关数据，在即时通讯工具中实现智能数据问答。目前支持的企业即时通讯工具包括企业微信，飞书，钉钉。

常见问题

测试模型连接失败怎么排查？

连接失败有多种原因，建议按以下步骤进行排查：

检查请求地址

确保模型地址是正确的，不同厂商提供的模型地址是不同的，具体请查找你购买的厂商提供的文档。

我们可以提供初步排查指引：

各家模型提供商的模型地址通常都以 <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 接口兼容。

检查密钥

各家模型提供商的大模型接口通常需要密钥才能访问，请确保你提供的密钥是正确的，并且有访问该模型的权限。
假如你公司采用了自己部署的模型，密钥是有可能不需要的，请与你公司开发人员或你公司工程团队确认。

检查模型名称

各家模型提供商普遍都提供了多种模型，请根据需要选择合适的模型，并确保你提供的模型名称是正确的，并且有访问该模型的权限。
假如你公司采用了自己部署的模型，模型名称是有可能不需要的，请与你公司开发人员或你公司工程团队确认。

问数失败、报错怎么排查？

失败、报错涉及多个环节的诊断，在遇到问题时需要收集以下信息并联系售后工程师：

点击对话卡片下方三点菜单，点击“执行日志”，点击“复制完整日志”

复制执行日志

键盘 F12 或鼠标右键点击“检查”打开浏览器控制台，点击“网络”-“Fetch/XHR”

打开浏览器控制台

再次问数复现错误，鼠标右键出错的网络请求点击“复制”-“复制响应”

复制网络请求响应

进入“系统设置”-“智能运维”-“系统调试”，将“统一设置”调整为“DEBUG”，打开“实时调试”，再次问数复现错误，然后点击“导出日志”

实时调试日志

向量数据库地址怎么填？

按照AI 助手部署文档完成相关服务的安装及部署即可，无需手动填写。

是否支持其他向量模型？

目前暂不支持，如有需求，请联系售后工程师。

Data Agent 侧边栏与 ChatBI 有哪些区别？

能力	Data Agent 侧边栏	ChatBI
指定数据源智能问数	✅	✅
不限数据源智能问数	✅	❌
对话图表一键生成看板	❌	✅
可视化辅助创作	✅	❌
指标辅助创作	✅	❌
智能解读	✅	❌

Agent 模式、workflow 模式、api 模式之间有哪些区别？

能力	agent 模式	agent api 模式	workflow 及 workflow api 模式
指定数据源智能问数	✅	✅	✅
不限数据源智能问数	✅	✅	❌
可视化辅助创作	✅	❌	❌
指标辅助创作	✅	❌	❌
智能解读	✅	❌	❌

用户手册

SDK

ChatBot

数据集成

数据填报

创建数据集

数据集加工

函数列表

仪表盘创作

图表类控件

图表高级计算

功能类控件

展示类控件

应用设置

Data Agent

模型供应商

Data Agent ​

概述 ​

安装与配置 ​

先决条件 ​

配置大模型 ​

使用指南 ​

为 AI 编写提示词 ​

行业术语、私域知识 ​

数据集分析规则 ​

将 agent 与企业知识库、外部 api 等打通 ​

为 AI 准备数据 ​

数据向量化 ​

数据管理 ​

提升对复杂计算的理解 ​

使用场景 ​

智能问数 ​

可视化创作 ​

智能解读 ​

表达式编写 ​

集成 ChatBI ​

IFRAME 集成 ​

SDK 集成 ​

API 集成 ​

企业即时通讯工具数据问答机器人 ​

常见问题 ​

测试模型连接失败怎么排查？ ​

检查请求地址 ​

检查密钥 ​

检查模型名称 ​

问数失败、报错怎么排查？ ​

向量数据库地址怎么填？ ​

是否支持其他向量模型？ ​

Data Agent 侧边栏与 ChatBI 有哪些区别？ ​

Agent 模式、workflow 模式、api 模式之间有哪些区别？ ​

Data Agent

概述

安装与配置

先决条件

配置大模型

使用指南

为 AI 编写提示词

行业术语、私域知识

数据集分析规则

将 agent 与企业知识库、外部 api 等打通

为 AI 准备数据

数据向量化

数据管理

提升对复杂计算的理解

使用场景

智能问数

可视化创作

智能解读

表达式编写

集成 ChatBI

IFRAME 集成

SDK 集成

API 集成

企业即时通讯工具数据问答机器人

常见问题

测试模型连接失败怎么排查？

检查请求地址

检查密钥

检查模型名称

问数失败、报错怎么排查？

向量数据库地址怎么填？

是否支持其他向量模型？

Data Agent 侧边栏与 ChatBI 有哪些区别？

Agent 模式、workflow 模式、api 模式之间有哪些区别？