JimuChatBI：用自然语言查数据，不再为一条 SQL 找开发排期

预计阅读时间：11 分钟

业务同学想看"上个月华东区各品类销售额 TOP10"，要么自己学 SQL 写半天，要么提需求等开发排期——这条链路少则几小时，多则几天。JimuChatBI（积木问数）要砍掉的就是这段等待时间：你用中文提问，它秒级生成 SQL、执行查询、返回图表，全程不需要写一行代码。

从提问到图表，中间发生了什么

JimuChatBI 的核心链路可以拆成四步：

自然语言解析 — 把"华东区上月销售额"翻译成结构化查询意图（维度、指标、筛选条件、排序方式）。
SQL 生成 — 根据意图 + 数据库元数据（表名、字段、关系），拼出可执行的 SQL。
查询执行 — 在目标数据库上跑 SQL，拿到结果集。
可视化渲染 — 自动选图表类型（表格、柱状图、折线图等），把数据画出来。

关键难点在第 1、2 步：自然语言到意图的映射容易歧义，意图到 SQL 需要准确理解表结构。JimuChatBI 的做法是预先注册数据模型的元信息——表、字段、维度/指标标注、同义词映射——让大模型在生成时有足够的上下文约束，而不是裸跑。

快速上手：本地跑起来

JimuChatBI 即将开源，基于 Java / Spring Boot 体系，和积木报表（JimuReport）同源。下面是一个最小化部署的实操路径，假设你已经有一个可用的 MySQL 数据库。

1. 拉取项目 & 配置数据源

# 克隆仓库（开源发布后可用，此处为预期路径）
git clone https://github.com/jeecgboot/JimuChatBI.git
cd JimuChatBI

在 application.yml 中配置你的业务数据库连接：

spring:
  datasource:
    url: jdbc:mysql://127.0.0.1:3306/sales_db?useUnicode=true&characterEncoding=UTF-8&serverTimezone=Asia/Shanghai
    username: root
    password: your_password
    driver-class-name: com.mysql.cj.jdbc.Driver

# JimuChatBI 数据模型元数据存储（可用同一库的不同 schema）
jimuchatbi:
  meta-datasource:
    url: jdbc:mysql://127.0.0.1:3306/chatbi_meta?useUnicode=true&characterEncoding=UTF-8&serverTimezone=Asia/Shanghai
    username: root
    password: your_password

两个数据源分开是推荐做法：sales_db 是你要查的业务库，chatbi_meta 存 JimuChatBI 的模型注册信息、对话历史等。小团队可以合用一个库，但别混到同一张表里。

2. 注册一个数据模型

JimuChatBI 需要你先告诉它"有哪些表、哪些字段能查"。这是降低大模型幻觉的关键步骤。以一个销售表为例：

{
  "modelCode": "sales_order",
  "modelName": "销售订单",
  "table": "t_sales_order",
  "fields": [
    { "column": "region",       "name": "区域",     "type": "dimension", "synonyms": ["大区","地区"] },
    { "column": "category",     "name": "品类",     "type": "dimension", "synonyms": ["商品类别","类目"] },
    { "column": "order_date",   "name": "订单日期", "type": "dimension", "timeFormat": "yyyy-MM-dd" },
    { "column": "sales_amount", "name": "销售额",   "type": "metric",    "agg": "SUM" },
    { "column": "order_count",  "name": "订单数",   "type": "metric",    "agg": "COUNT" }
  ]
}

同义词字段的作用：当用户说"大区销售额"时，系统知道"大区"映射到 region 列，而不是去猜。type 标注 dimension / metric 决定了字段在查询中的角色——维度用于分组，指标用于聚合。agg 直接告诉生成器：销售额默认求和，订单数默认计数。

3. 启动 & 对话查询

# 编译启动
mvn clean package -DskipTests
java -jar target/JimuChatBI.jar

打开浏览器访问 http://localhost:8080，进入对话界面，输入：

上个月华东区各品类销售额 TOP10

JimuChatBI 会生成类似这样的 SQL：

SELECT 
    category AS 品类,
    SUM(sales_amount) AS 销售额
FROM t_sales_order
WHERE region = '华东'
  AND order_date >= DATE_FORMAT(DATE_SUB(CURRENT_DATE, INTERVAL 1 MONTH), '%Y-%m-01')
  AND order_date <  DATE_FORMAT(CURRENT_DATE, '%Y-%m-01')
GROUP BY category
ORDER BY SUM(sales_amount) DESC
LIMIT 10

并自动渲染为柱状图或表格，整个过程通常在 3-5 秒内完成。

接入自有系统：API 调用示例

如果你想把 JimuChatBI 嵌进自己的业务系统（比如 CRM、运营后台），它提供了 REST API。以下是一个 Python 调用示例：

import requests

CHATBI_URL = "http://localhost:8080/api/chatbi/query"

def ask_chatbi(question: str, model_code: str = "sales_order") -> dict:
    """向 JimuChatBI 提问，返回查询结果和生成的 SQL"""
    resp = requests.post(
        CHATBI_URL,
        json={
            "question": question,
            "modelCode": model_code,
        },
        timeout=30,
    )
    resp.raise_for_status()
    data = resp.json()
    # data 包含: sql（生成的SQL）、rows（结果集）、chartType（建议图表类型）
    print("生成的 SQL:", data["sql"])
    print("结果行数:", len(data["rows"]))
    return data

# 示例：查本月各区域订单数
result = ask_chatbi("本月各区域订单数是多少")
for row in result["rows"]:
    print(row)

运行前确保 JimuChatBI 服务已启动，且 sales_order 模型已注册。返回结构中 sql 字段可以拿来做审计——每条自然语言查询对应什么 SQL，一目了然。

准确性怎么保障

对话式 BI 最怕的不是慢，而是错。一条看起来合理但逻辑有偏差的 SQL，比没有查询更危险。JimuChatBI 在这方面有几层防线：

模型注册约束 — 字段类型、聚合方式、同义词都在注册时锁定，大模型不是自由发挥，而是在约束框内生成。
SQL 审查机制 — 生成的 SQL 会经过语法校验和基础安全检查（禁止 DROP/DELETE 等写操作），只允许 SELECT 类查询。
结果可追溯 — 每次对话都保留生成的 SQL原文，业务同学可以点开看"我这句话到底查了什么"，发现不对能及时反馈修正。

但也要承认现实：复杂的多表关联、嵌套子查询、时间口径歧义（"最近7天"是自然日还是工作日？），这些场景下大模型仍有出错概率。建议的做法是：

初期只注册单表或简单的星型模型，避免让生成器处理复杂 JOIN。
对高频查询做"意图固化"——把常见问题保存为模板，下次直接匹配模板而非重新生成。
上线前让数据团队抽检 50-100 条典型提问的生成 SQL，建立基线准确率。

什么时候该用，什么时候别用

适合的场景：

运营、市场、产品经理的日常取数——维度固定、指标明确、查询模式重复度高。
替代低价值的数据看板需求——那些"只看一次就扔"的临时查询，不值得开发一个报表页面。
数据探索阶段——分析师快速试不同维度组合，找到值得深挖的方向后再用专业工具做深度分析。

不适合的场景：

涉及多表复杂关联的深度分析——大模型生成 JOIN 的准确率目前不够稳定。
对数据口径有严格合规要求的财务/监管报表——这类查询必须由人工 SQL 保证精确性。
高并发实时查询——对话式 BI 的生成链路有延迟，不适合毫秒级响应的 API 服务场景。

上线前的 Checklist

把 JimuChatBI 引入团队前，建议逐项确认：

[ ] 数据源权限隔离 — JimuChatBI 连接的数据库账号只给 SELECT 权限，禁止写操作。
[ ] 模型注册完成 — 至少覆盖 80% 的高频查询字段，同义词映射经过业务同学确认。
[ ] 抽检基线建立 — 50 条典型提问的生成 SQL 经过数据团队审核，准确率 ≥ 85% 再开放使用。
[ ] 对话审计机制 — 确认每次查询的 SQL 都有留存，可回溯、可复盘。
[ ] 兜底通道 — 对于 ChatBI 处理不了的复杂需求，仍然保留传统提需求 → 开发写 SQL 的路径，别让业务同学卡死在对话窗口前。

JimuChatBI 的价值不是替代数据开发，而是把大量低复杂度、高重复的取数需求从人工链路搬到自动链路，让数据团队腾出手做真正需要深度建模的工作。开源后值得优先试水的，是那些每天都在微信群里问"这个数是多少"的团队——如果一条提问 5 秒出图，那些群消息会少一半。