Skip to main content
Version: 5.1.0

Enable ChatBI - 智能问数技能

Enable ChatBI 是 TIS 本体域的核心技能之一，它为已构建好的本体域开启自然语言查询能力，让不懂 SQL 的业务人员也能直接"对话式"地查询数据，快速获取业务洞察。

什么是 ChatBI​

ChatBI（Chat-Based Business Intelligence）是"对话式商业智能"，用户用日常语言提问，系统自动理解问题、生成 SQL、执行查询并返回结果。

传统方式 vs ChatBI：

传统方式ChatBI 方式
业务人员提需求 → 数据分析师写 SQL → 返回结果（耗时数小时）业务人员直接问："上个月销售额是多少？" → 系统 2 秒返回结果
需要掌握 SQL 语法、表结构、字段命名只需用自然语言描述业务问题
分析师成为瓶颈，请求排队等待自助式查询，即问即答

工作原理（简化说明）​

Enable ChatBI 技能在保存时会执行以下操作，为智能问数做好准备：

1. 构建语义图谱​

系统将本体域中的所有元数据（ObjectType、Property、LinkType、Glossary 等）加载到图数据库（Neo4j）中，构建一张"语义知识图谱"：

  • 节点：每个 ObjectType、Property、Glossary 术语都是一个节点
  • 边：LinkType 关系成为连接节点的边
  • 属性：每个节点携带名称、描述、类型等信息

2. 生成语义向量索引​

为每个本体实体生成 384 维的语义向量（Embedding），并构建向量索引（HNSW）。这使得系统能够快速找到与用户问题最相关的表和字段。

举例：
用户问"销售额"，系统通过向量相似度搜索，快速召回：

  • orders.amount（订单金额列）
  • order_items.unit_price（商品单价列）
  • Glossary 术语"总销售额" → SUM(orders.amount)

3. 自然语言 → SQL 流程​

当用户提问时：

  1. 语义检索：从图谱中召回与问题最相关的 ObjectType、Property、LinkType
  2. 上下文拼装：将召回结果序列化为结构化的 Prompt 上下文
  3. LLM 生成 SQL：大语言模型根据上下文和问题，生成候选 SQL
  4. 三层校验：
    • 关键字白名单：只允许 SELECT/WITH 等只读语句，拒绝 DROP/DELETE
    • AST 语法校验：解析 SQL 语法树，检查表名、列名是否存在于召回集中
    • EXPLAIN 校验（可选）：提交数据库验证 SQL 语义正确性（如函数签名、类型匹配）
  5. 执行并返回结果：校验通过后执行 SQL，返回结果表格

使用前提​

启用 ChatBI 前，需要确保：

  1. 本体域已创建 ObjectType
    至少导入一张表的元数据（通常从数据源批量导出）

  2. ObjectType 已绑定数据源
    每个 ObjectType 必须指定来自哪个数据库（通过 DataSourceBinding 绑定）

  3. 属性已配置语义角色（推荐）
    为 Property 标注 roleType（Identifier、Dimension、TimeDimension、Measure），帮助 LLM 理解字段用途：

    • Identifier：主键、唯一标识列
    • Dimension：用于分组和筛选的维度（如城市、状态）
    • TimeDimension：时间列（支持按日/周/月/季/年聚合）
    • Measure：可聚合的度量（如金额、数量），需指定聚合函数（SUM/AVG/COUNT 等）

  4. 已配置 Glossary 业务术语（推荐）
    将常见的业务口语化表达映射到本体实体，提升召回准确率：

    • 术语"客户" → ObjectType customer
    • 术语"订单金额" → Property orders.amount
    • 术语"总销售额" → 指标表达式 SUM(orders.amount)

配置参数说明​

在本体域详情页点击"Enable ChatBI"按钮后，需要配置以下核心参数：

1. LLM Provider（大语言模型）​

选择用于生成 SQL 的大模型服务。不同模型在准确率、速度、成本上有差异：

推荐模型适用场景准确率成本（每次查询）速度
🏆 通义千问 Max / GPT-4生产环境，复杂查询90-95%¥0.10-0.15中等
💰 DeepSeek Chat / 通义千问 Plus性价比场景，中等复杂度85-90%¥0.02-0.05快
⚡ 通义千问 Turbo / GPT-3.5-turbo内部测试，简单查询75-80%¥0.01-0.02很快

注意：

  • 不推荐使用代码类模型（如 DeepSeek Coder），它们擅长生成代码但不擅长理解业务语义
  • 如果未配置 LLM Provider，需先在"系统管理 → LLM 配置"中添加

2. Top-K 种子数（检索配置）​

控制语义检索阶段召回多少个"种子实体"（最相关的 ObjectType 和 Property）。

取值建议适用场景Token 消耗准确率
3-5单表或 2 表 JOIN，简单聚合2000-3000适中
5-8（默认 5）3-4 表 JOIN，有复杂聚合3000-5000较高
8-105 表以上 JOIN，多层嵌套5000-8000高

权衡：

  • 值越大 → 上下文越丰富（准确率↑）、但 Token 消耗增加（成本↑）、响应变慢（速度↓）
  • 优化技巧：如果发现召回了很多无关的表，说明本体中存在命名混淆，应优化 Glossary 而不是提高此参数

3. EXPLAIN 校验（验证配置）​

默认：启用

开启后，系统会在执行 SQL 前先运行 EXPLAIN <SQL> 命令，验证 SQL 的语义正确性。

作用：

  • ✅ 拦截函数签名错误（如 DATEDIFF('year', col1, col2) 在 Doris 中应为 DATE_DIFF(col2, col1, 'year')）
  • ✅ 拦截类型不匹配（如对 VARCHAR 字段使用 SUM 聚合）
  • ✅ 拦截表/列不存在错误（防止 LLM"幻觉"出不存在的字段）

代价：增加约 200-300ms 延迟（相当于总耗时的 5-10%）

建议：

  • 生产环境强烈建议开启，保障查询质量
  • 性能敏感场景且对准确率容忍度高时可关闭

4. Token 预算（检索配置）​

默认：3000

限制 GraphRAG 序列化的 Prompt 上下文长度，防止超出大模型的上下文窗口。

超出预算时，系统会按相关性剪枝 ObjectType 和 Property，优先保留：

  • 主键（pk）字段
  • Measure 角色的度量字段
  • TimeDimension 角色的时间字段

取值建议：

  • 设为模型上下文窗口的 20-30%
  • 例如：GPT-4 128K 窗口 → 建议 3000-5000；通义千问 32K 窗口 → 建议 2000-3000
  • 如果经常遇到"token 预算不足"警告，可适当提高此值，或降低 Top-K 种子数

5. 重试次数（重试配置）​

默认：2

SQL 校验失败时，允许重新调用 LLM 修正的次数。

场景：AST 校验或 EXPLAIN 校验失败时，系统会将错误信息反馈给 LLM，引导其修正 SQL。

建议：

  • 保持默认值 2 即可（总共最多 3 次 LLM 调用）
  • 过高会增加延迟和成本，过低会降低复杂查询的成功率

6. 查询超时（执行配置）​

默认：30 秒

SQL 执行的超时时间，防止慢查询阻塞服务。

建议：

  • 小型数据库（<1000 万行）：30 秒
  • 大型数据库（>1 亿行）：60 秒

配置完成后，会显示"已成功开启 ChatBI 功能"提示。

使用步骤​

步骤 1：进入本体域详情页​

在 TIS 控制台，导航至"本体管理" → 点击目标本体域，进入详情页。

步骤 2：点击"Enable ChatBI"按钮​

在详情页顶部工具栏找到"Enable ChatBI"按钮并点击。

点击”查看状态“后进入Chat-BI 状态控制台

步骤 5：开始智能问数​

方式 A：TIS Web 控制台​

  1. 在本体域详情页，点击"ChatBI 查询"标签页
  2. 在输入框中输入自然语言问题，例如：
    • "2025 年各城市的销售总额排名前 10"
    • "库存低于 100 的商品有哪些"
    • "最近 7 天每天的新增用户数趋势"
  3. 点击"提交"，等待 2-5 秒
  4. 查看结果：
    • 生成的 SQL 语句（支持复制和编辑）
    • 执行摘要（检索到的 ObjectType、LLM 调用耗时、SQL 执行耗时等）

方式 B：通过 MCP 协议接入专业 Agent​

TIS 提供了标准的 MCP（Model Context Protocol）服务器，可以无缝接入 OpenClaw、Hermes 等专业 Agent 工具。

优势：

  • 定时任务：配置每天定时执行固定的问数任务，并推送结果到邮件或 IM 工具
  • 多轮对话：Agent 能理解上下文，支持追问和条件调整（如"把上一个查询改成按周统计"）
  • 专业渲染：利用 Agent 的图表组件自动渲染结果为可视化图表
  • 混合能力：在同一个对话中结合 ChatBI 和 Agent 的其他技能（如文档检索、代码生成）

接入步骤：

  1. 在 TIS 中启动 MCP Server（通常在"系统管理 → MCP 配置"）

  2. 在 OpenClaw 或 Hermes 中添加 MCP 服务器地址: http://{tis_host}:8080/tjs/mcp

  3. 通过自然语言调用 ChatBI 功能，例如："使用chat_bi 工具:找出库存量高于平均水平的门店及其所在城市，显示门店名称、城市和总库存量"

    注意

    前缀“使用chat_bi 工具:”不能少

常见问题​

Q1：为什么生成的 SQL 不正确？​

可能原因：

  • 本体中缺少相关的 Glossary 术语，导致召回失败
  • ObjectType 或 Property 的描述信息不够清晰
  • 选择的 LLM 推理能力不足

解决方法：

  • 补充 Glossary 业务术语，将常见口语化表达映射到本体实体
  • 丰富 ObjectType 和 Property 的 description 字段
  • 尝试更换推理能力更强的模型（如 GPT-4、通义千问 Max）

Q2：查询速度慢怎么办？​

可能原因：

  • Top-K 种子数过大，导致上下文序列化耗时
  • LLM 响应速度慢
  • 数据库查询本身慢（数据量大、未建索引）

解决方法：

  • 降低 Top-K 种子数（如从 8 降到 5）
  • 选择响应更快的 LLM（如通义千问 Turbo）
  • 在数据库侧优化查询性能（添加索引、分区）

Q3：如何控制成本？​

ChatBI 的主要成本来自 LLM API 调用。控制成本的方法：

  • 选择性价比高的模型：DeepSeek Chat、通义千问 Plus
  • 降低 Top-K 种子数：减少上下文长度，降低 Token 消耗
  • 关闭 EXPLAIN 校验（不推荐）：可节省一次数据库调用，但可能降低准确率
  • 设置查询频率限制：避免高频刷新

Q4：ChatBI 支持哪些类型的查询？​

支持：

  • 单表查询、多表 JOIN
  • 聚合统计（SUM/AVG/COUNT/MAX/MIN）
  • 分组聚合（GROUP BY）
  • 时间维度切分（按日/周/月/季/年）
  • 排序和 TOP-N
  • 简单条件筛选（WHERE）

暂不支持：

  • 子查询（部分支持）
  • 窗口函数（部分支持）
  • 自定义 UDF（需在 Glossary 中预定义）

相关文档​