衡石 Data Agent：语义准备、运行方式与权限边界

企业要把 AI 用进数据分析，重点不在于让模型“替人猜答案”，而在于把业务语义、可用数据和访问边界准备成可被持续使用的分析条件。衡石 Data Agent 提供对话式的数据分析、指标创建和仪表盘创作能力；技术决策者与集成团队则需要把它放进既有的数据治理、认证和交付流程中。这样，业务问题可以从一次问答发展为可核对、可调整、可复用的分析资产。

1 从业务问题到可用分析：先准备语义与数据

Data Agent 可以协助完成即时业务分析、指标创建和仪表盘生成，但回答质量首先取决于数据资产是否表达了业务本意。模型生成的是分析辅助，业务口径仍应由数据团队明确维护。衡石在 Data Agent 控制台中支持用提示词补充行业术语、组织规则和分析方向；数据集的知识管理可说明用途、隐含过滤规则、同义词，以及字段和指标的业务含义。相关配置的目标是让问题与正确的数据对象建立更清楚的联系，而不是用一次对话临时拼出关键规则。

例如，“销售完成率”在不同部门可能使用不同的目标版本、时间窗口或退货口径。团队应把该定义沉淀为可复用的指标，在描述中写清统计周期、过滤条件和容易混淆的别名；再把它放进合适的数据集或业务主题。这样，业务人员提问时能从已有口径出发，分析人员也能回到指标定义复核结果。业务主题与指标管理手册说明了指标、主题和授权的管理入口。

1.1 数据准备是回答质量的第一道工程工作

建议在数据包发布与日常维护时检查数据集命名、字段类型、字段与原子指标描述，并隐藏不参加问答的字段。清晰、精简的上下文有助于降低歧义和无关信息带来的干扰。需要跨团队复用的复杂计算，宜先沉淀为指标；单次对话可用于探索、解释和调整问题，但不宜成为关键口径的唯一载体。

衡石支持对字段、原子指标名称、描述和字段值等文本信息进行向量化，以便按语义检索相关信息，而不只依赖关键词。向量化可以帮助检索同义词、行业术语与上下文，并缩小需要送入模型的候选范围；它不能替代数据质量检查、权限配置或口径验收。官方文档也明确提示，AI 即使收到相同输入，也未必每次产生完全相同的响应。因此，重要结论仍应由业务负责人和数据负责人共同确认。

一个务实的准备顺序是：先确认数据集是否覆盖问题所需的时间、粒度和数据范围；再补齐字段、原子指标与业务主题的名称和描述；随后把易混淆术语、默认筛选逻辑和业务规则写入知识管理或提示词；最后用一组真实但脱敏的问题做回归检查。若某个问法持续命中错误对象，优先检查同义词、字段隐藏、指标定义和数据权限，而不是单独提高模型参数。这样，调优结论能够沉淀回数据资产，下一位使用者也可以获得同样的基础条件。

“数据准备”还意味着划清探索与发布的边界。探索阶段可以让业务人员用自然语言提出候选问题，比较不同切分维度或补充上下文；准备发布到经营看板、例会材料或下游应用前，则应确认指标版本、时间范围、筛选条件、数据刷新状态和责任人。对需要长期复用的结论，建议保留问题样例、对应的指标与数据对象，以及人工确认的解释。这份小型证据链既能帮助新成员理解结论，也能在数据或规则变更后定位需要复核的内容。

1.2 让提问范围与角色一致

ChatBI 支持在用户角色权限范围内选择数据集或业务指标主题作为提问范围。Data Agent 的 Agent 模式可以在用户有权限的数据范围内，从数据集市、应用集市和应用创作中检索相关内容；在数据包、数据集或仪表盘页面上，它还可利用当前页面与登录账号信息理解上下文。范围越明确，团队越容易检查回答引用的对象和适用口径。

2把能力放在正确的产品边界

面向业务用户，ChatBI 适合从一个明确问题开始，返回数据并以图表呈现；对话中的图表可进一步生成或加入仪表盘。Data Agent 则覆盖更长的协作链路：它可辅助问数、可视化创作、指标创作、HQL 表达式编写，以及对已有仪表盘添加图表、过滤器、富文本内容、布局或颜色调整。这里的价值在于把“问到一个结果”延续为“形成可继续编辑的分析资产”，而不是把自然语言当作绕开建模和审核的快捷通道。

智能解读是另一条清晰的能力边界：它可以按预先配置的解读思路查询、识别异常、分解和下钻，并生成描述性报告，帮助团队理解已有及历史数据呈现的情况。智能解读不做未来预测，也不支持复杂报表和复杂表格。遇到归因、预测或重大经营决策时，应补充业务假设、外部证据和人工复核。

2.1 先选运行方式，再选接入方式

运行方式回答“谁持续推进当前问答”；接入方式回答“能力以什么形态进入现有系统”。Agent 模式适合保留连续的代理式问答过程，过程中可能逐步产生状态、工具调用和图表结果。Workflow 模式由后端工作流服务推进执行，前端主要承担发起、读取状态和展示结果。若后端需要保留 Agent 模式，衡石提供 Node.js 版 Agent 服务承接这一运行方式。

组合	主要责任	适合的交付目标
Agent + iframe	嵌入的完整页面承载连续问答与结果	希望尽快复用完整 ChatBI / Data Agent 页面
Agent + JS SDK	宿主保留页面壳与入口，嵌入能力承接 Agent 前端运行	在自有业务页中保留连续的助手体验
Workflow + JS SDK	后端工作流推进执行，SDK 承载聊天或结果渲染	希望后端统一管理执行与交付节奏
API	集成方负责系统编排、页面展示与业务整合	已有后端、AI 网关、多 Agent 或工作流系统

iframe 适合直接复用完整页面；JS SDK 适合保留自己的页面壳，并嵌入完整聊天窗或局部结果卡片；API 则面向后端能力接入。API 是接入方式，不等同于 Workflow。选择前应明确谁发起请求、谁呈现结果、谁保存业务资产、谁对异常交付负责。JS SDK 的数据范围可配置为数据包与数据集模式，或业务主题域模式，但一次配置不应混用两种模式。

对前端团队来说，iframe 的优势是完整体验与较少的页面改造；JS SDK 的优势是保留宿主页面的入口、布局和交互，同时复用衡石的聊天、结果卡片与图表呈现。若宿主系统希望完全采用自己的展示协议和图表体系，就应预留相应的前端适配与测试责任，不能把 SDK 当作图表协议转换器。对后端团队来说，API 接入更适合放入既有的工作流、AI 网关或多 Agent 编排中，但仍需在设计中明确调用身份、数据范围、错误处理和结果消费位置。

认证与嵌入也应在方案早期确认。SDK 页面能否正常呈现问答和图表，依赖登录态已经准备妥当；如果 SDK 文件从与衡石不同的静态域加载，还需要正确指定后端地址。上线前应以目标部署环境、真实身份和最小授权范围完成联调，覆盖正常问答、无权限对象、过期登录态和嵌入容器尺寸等场景。这样可以避免把“页面已加载”误判为“数据分析已可交付”。

连续对话应围绕当前页面和当前会话完成。Agent 运行过程中切换页面或历史会话可能中断本次执行，因此演示与排障时应保留当前页面和会话。若业务需要跨日、跨终端恢复未完成任务，集成方应在自身后端定义任务、状态与恢复责任，不能把前端问答过程当作已承诺的持久化恢复机制。

2.2 模型配置应服务于可观测的交付

衡石提供大模型 API 的最大输出、超时、调用间隔、失败重试、随机种子、历史对话条数等系统级配置；公开手册列出的默认值包括最大输出 1000 token、调用超时 600 秒、失败重试 1 次和连续对话上下文 4 条。部署团队应结合模型服务能力、网络条件和业务时效性设置这些参数，并记录部署版本与实际取值。这些配置用于控制调用行为，不代表系统会自动按模型能力分级路由，或保证不同模型产生无差异结果。

参数治理的目标是让异常行为可预测、可处理。团队可把“等待多久”“失败后尝试几次”“携带多少历史对话”“谁有权修改配置”写入部署记录，并在模型供应、网络出口或版本升级后重新验证。对用户界面，应给出请求仍在处理、调用超时或需要重新提问等清晰反馈；对运维侧，应能关联发生时间、部署版本、所选运行方式和最小复现问题。这里的记录服务于联调和问题定位，不应把模型生成的分析文本本身误作可替代业务审核的审计结论。

3 权限边界要落在数据对象上

认证说明“谁进入系统”，权限说明“进入后能做什么、能看什么”。对于数据连接，衡石支持在连接、目录和表层级授予查看名称、查看数据结构、只读访问或完全访问；表级只读访问还可配置行、列权限。对于应用，数据权限模式决定访问应用时使用应用作者、数据集作者或使用者的数据；在应用作者和数据集作者模式下，应用管理者可以继续配置数据集的行、列规则。

权限设计需要对规则组合保持谨慎：同一用户、同一数据集的行权限和列权限取交集；同类多条行规则或列规则会形成并集。基础数据集上的行权限也不会自动下推到新建的下游关联数据集，后者需要单独配置。业务主题可以授权使用主题和指标，但主题访问仍应与底层数据包的行权限一起验证。不要把页面筛选、隐藏控件或嵌入样式当成数据授权的替代品。

3.1 用最小权限原则设计可验证的范围

权限方案应从真实的使用路径倒推。先确定业务人员需要问哪些数据集或主题、是否需要查看字段结构、是否需要编辑指标或仪表盘；再分配连接、目录、表、应用和主题上的最小可用权限。对于表级只读访问，可以结合固定值、用户属性、表达式或 SQL 表达式过滤实现行级范围控制，并用列权限隐藏不应暴露的字段。需要跨表或下游关联数据集时，应逐个对象检查规则是否已经配置，而不依赖上游规则自动继承。

验证不应只看管理员账号。至少使用一个普通业务账号、一个边界角色账号和一个不应访问该范围的账号，分别测试可选择的数据集或主题、返回的行范围、敏感列可见性以及嵌入后的结果。若同一用户命中了多条规则，还应按产品的并集与交集规则核对最终结果。把测试账号类型、预期范围、实际结果和例外处理记录下来，能让权限变更、主题发布和新数据集接入拥有可追溯的验收依据。

3.2 上线前用一份可读的验收记录闭环

下面的清单把数据准备、运行责任和权限验证放到同一次验收中。它不是衡石接口规范，也不是产品内部流程；它用于帮助集成团队在联调时保留可复查的证据。

验收项	要核对的事实	示例证据	责任人
业务语义	指标名称、时间范围、过滤条件和同义词已确认	指标定义与问题样例	数据负责人
提问范围	角色只能选择已授权的数据集或业务主题	测试账号的范围截图或记录	权限管理员
运行与接入	Agent / Workflow 与 iframe、SDK、API 的责任一致	集成设计与联调结果	技术负责人
结果复核	数据、图表和描述性解读能回溯到数据对象与口径	抽样问题、筛选条件和人工结论	业务负责人
异常处理	超时、失败重试、页面切换中断和用户提示已有约定	配置记录与故障演练结论	运维与集成团队

分析验收记录示例（文章示例，不是衡石 API 请求 schema）

{
  "analysis_topic": "区域销售完成情况",
  "scope": {
    "mode": "business_topic",
    "display_name": "销售经营"
  },
  "verification": {
    "metric_definition_checked": true,
    "role_scope_checked": true,
    "row_column_rules_checked": true,
    "human_review": "业务负责人已确认描述性结论"
  },
  "delivery": {
    "runtime_mode": "workflow",
    "integration_surface": "js_sdk",
    "test_result": "passed"
  }
}

4 让 AI 分析成为团队可复用的能力

衡石 Data Agent 的实际价值，在于把已治理的数据、指标和应用资产转化为更自然的分析入口，并把问数、图表、仪表盘编辑与描述性解读连接起来。对技术团队而言，可靠交付来自四件事：先准备语义与数据，再选定运行和接入责任，把权限落实到连接、数据集、主题与应用对象上，最后用业务复核与联调记录验证结果。当每次回答都能回到范围、口径和权限，AI 才能成为企业分析流程中值得信赖的一环。

这套方法也为持续改进留下了路径：把高频问题转化为指标与知识管理的改进项，把常见集成故障转化为认证、嵌入和运行方式的检查项，把业务复核中发现的歧义转化为更清楚的术语、规则和说明。随着数据资产和交付流程逐步完善，团队获得的不只是更快的单次回答，而是一种可由业务、数据和技术共同维护的分析协作方式。