Version: 5.1.0

chat_bi

所属分类：智能问数 · Tool 名称：chat_bi

功能说明

chat_bi 将 TIS 的 ChatBI 智能问数能力通过 MCP 开放出来：输入一句自然语言问句，TIS 基于本体（Ontology）元数据与 GraphRAG 检索生成 SQL、执行查询，并返回结构化的查询结果与完整的执行轨迹（Trace）。

与其他查询类 Tool 不同，chat_bi 的执行过程涉及 GraphRAG 检索与大模型调用，耗时较长（数秒到数十秒）。执行过程中会通过 MCP progressNotification 实时推送执行步骤，客户端可据此渲染进度；最终结果中也包含完整的 trace 数组供回溯与调试。

前置条件

使用本 Tool 前，需要已在 TIS 中构建本体域（Ontology Domain）并为该域启用 ChatBI 功能。配置方法请参考 Enable ChatBI - 智能问数技能。

输入参数

参数	类型	必填	说明
`nlq`	string	是	自然语言问句，例如：`最近一个月销售额最高的前10个产品是什么？`

输出结果

返回 TIS 标准信封结构（详见总览 - 通用返回约定），业务结果在 bizresult 中：

字段	类型	说明
`success`	boolean	本次问数是否成功
`errormsg`	string[]	错误信息列表。出现非空 `errormsg` 时调用端应立即终止后续执行并告知用户
`msg`	string[]	结果描述，成功时包含生成的 SQL 摘要
`bizresult`	object	ChatBI 业务结果，结构见下表

bizresult 字段：

字段	类型	说明
`sql`	string	生成的 SQL 语句
`data`	object	SQL 查询结果数据，结构见下表
`trace`	array	完整的执行步骤轨迹，元素结构见下表
`reqId`	string	请求唯一标识，格式 `yyyyMMddHHmmss-{uuid32}`，可用于在服务端日志中追踪本次请求
`error`	string	错误信息（仅执行失败时出现）

bizresult.data 字段：

字段	类型	说明
`columns`	string[]	列名列表
`rows`	object[]	查询结果行数据（按列名取值）
`rowCount`	integer	本次返回的行数
`truncated`	boolean	结果是否被截断（超过最大返回行数限制时为 true）
`actualRows`	integer	实际查询到的总行数

bizresult.trace[]（TraceStep）字段：

字段	类型	说明
`step`	string	执行步骤：`retrieve`（GraphRAG 检索）/ `prompt`（提示词组装）/ `llm`（大模型调用）/ `extract`（提取 SQL）/ `validate`（SQL 校验）/ `execute`（执行查询）
`ok`	boolean	该步骤是否成功
`message`	string	步骤描述信息
`millis`	integer	该步骤耗时（毫秒）
`data`	object	步骤相关数据，包含 `model` / `tokens` / `sql` / `issues` 等，具体内容取决于步骤类型

返回示例

{
  "success": true,
  "errormsg": [],
  "msg": ["成功生成并执行 SQL：SELECT product_name, SUM(sales_amount) AS total_sales FROM ..."],
  "bizresult": {
    "sql": "SELECT product_name, SUM(sales_amount) AS total_sales FROM orders WHERE ...",
    "data": {
      "columns": ["product_name", "total_sales"],
      "rows": [
        { "product_name": "Product A", "total_sales": 10000 },
        { "product_name": "Product B", "total_sales": 8600 }
      ],
      "rowCount": 10,
      "truncated": false,
      "actualRows": 10
    },
    "trace": [
      { "step": "retrieve", "ok": true, "message": "GraphRAG retrieval completed", "millis": 120, "data": {} },
      { "step": "prompt", "ok": true, "message": "Prompt assembled", "millis": 5, "data": {} },
      { "step": "llm", "ok": true, "message": "LLM invoked", "millis": 3500, "data": { "model": "qwen-plus", "tokens": 2150 } },
      { "step": "extract", "ok": true, "message": "SQL extracted", "millis": 2, "data": {} },
      { "step": "validate", "ok": true, "message": "SQL validated", "millis": 8, "data": {} },
      { "step": "execute", "ok": true, "message": "SQL executed", "millis": 230, "data": {} }
    ],
    "reqId": "20260625183000-abc123def456"
  }
}

执行失败时：

{
  "success": false,
  "errormsg": ["ChatBI 执行失败：SQL 校验未通过"],
  "msg": [],
  "bizresult": {
    "error": "SQL 校验未通过",
    "sql": "SELECT ...",
    "trace": [],
    "reqId": "20260625183000-abc123def456"
  }
}

执行过程实时推送（progressNotification）

执行过程中，服务端会为每个执行步骤推送一条 MCP notifications/progress 通知：

{
  "method": "notifications/progress",
  "params": {
    "progressToken": "chatbi-1719388800000",
    "progress": 120,
    "message": "GraphRAG retrieval completed",
    "_meta": {
      "traceStep": {
        "step": "retrieve",
        "ok": true,
        "message": "GraphRAG retrieval completed",
        "millis": 120,
        "data": {}
      }
    }
  }
}

通知字段	说明
`progressToken`	格式为 `chatbi-{timestamp}`，同一次查询的所有通知共享同一 token，客户端可据此关联
`progress`	累计耗时（毫秒）。总耗时未知，因此 `total` 为空
`message`	当前步骤描述
`_meta.traceStep`	完整的 TraceStep 对象，结构与最终结果 `trace` 数组元素完全一致

错误返回

情况	表现
`nlq` 为空	信封 `success: false`，`errormsg` 包含「自然语言问句（nlq）不能为空」
未找到可用的本体域 / 本体域未启用 ChatBI	MCP 层 `isError: true`，内容为通用错误提示文本
SQL 生成 / 校验 / 执行失败	信封 `success: false`，`errormsg` 与 `bizresult.error` 包含原因，`bizresult.trace` 记录已完成的步骤
服务端内部异常	MCP 层 `isError: true`，内容为通用错误提示文本

注意点

目标本体域的选择：当前版本自动选择目标本体域——TIS 中仅有一个本体域时直接使用该域；存在多个本体域时使用标记为「默认」的域；多域但未设默认域时会报错。请提前在 TIS 控制台确认默认域设置。
业务失败 ≠ 协议错误：SQL 生成失败、校验失败等业务失败通过信封 success: false 表达，MCP 层的 isError 为 false。调用端应检查信封 success 与 errormsg，而不是仅依赖 MCP 层错误标记。
结果截断：返回行数存在上限，data.truncated 为 true 时表示结果未完整返回（actualRows 为实际总行数），此时应引导用户细化问句条件。
耗时：涉及检索与大模型调用，单次执行数秒到数十秒属正常。客户端应利用 progressNotification 向用户展示进度，避免判定为超时。
Hermes 中使用技巧：为提高 Tool 命中率，建议在问句前显式加上「使用chat_bi 工具：」前缀。
可通过 reqId 在 TIS 服务端 ChatBI 日志（<TIS数据目录>/chatbi/trace/<日期>/<请求ID>.jsonl）中追踪本次请求的完整细节。

典型用法

在 Hermes 中的提问示例：

使用chat_bi 工具：最近一个月销售额最高的前 10 个产品是什么？

使用chat_bi 工具：找出库存量高于平均水平的门店及其所在城市，显示门店名称、城市和总库存量

上图：在 Hermes 中通过 MCP 调用 chat_bi 工具完成自然语言问数。

chat_bi

功能说明​

输入参数​

输出结果​

返回示例​

执行过程实时推送（progressNotification）​

错误返回​

注意点​

典型用法​