AI 问数与 SQL 分析
AI 问数把自然语言问题转换为只读 SQL，在数据源上执行预览，并对结果做图表和洞察分析。它是智能助理的工具能力之一，也保留了独立的问数界面。
AI 助手页面默认展示「智能助理」模式，独立问数模式未在模式切换中开放。智能助理遇到数据查询类问题时，会通过内置的 ai_query 工具复用本页描述的同一套问数链路。下文同时说明底层能力，便于理解行为与限制。
能力概览
处理分为四 个阶段：
| 阶段 | 说明 |
|---|---|
| understand | 解析问题、识别数据源、Schema、表、指标和时间范围 |
| generate | 结合语义层和表结构生成 SQL |
| execute | 只读校验通过后执行，返回受限行数的结果 |
| analyze | 生成结论、图表建议和后续追问 |
前置条件
- 平台已开启 AI 功能。
spring.ai.enabled默认关闭，部署时需显式开启并配置模型； - 使用关系型数据源（MySQL、PostgreSQL、Oracle、SQL Server、达梦等），且当前项目有数据源访问权限；
- 已选择数据源、Schema 和目标表；
- 模型服务可访问，密钥与模型名配置正确。
发起问数
- 选择数据源；
- 选择 Schema；
- 勾选一张或多张表作为查询范围；
- 输入自然语言问题；
- 等待阶段进度完成，查看 SQL、结果和洞察。
查询范围会记忆在浏览器本地，下次进入自动恢复。切换数据源或 Schema 会清空已选表。
问题示例
- 「最近 7 天每天的订单量」
- 「按地区统计销售 额，取前 10」
- 「查询状态为已完成的订单，按月汇总」
- 「对比今年和去年的新增用户数」
问题越具体，生成的 SQL 越稳定。涉及业务口径时，应先在语义层配置指标和术语。
SQL 安全边界
AI 生成的 SQL 和人工修改后的 SQL 都经过同一套只读校验：
| 规则 | 说明 |
|---|---|
| 允许的语句 | 只允许以 SELECT、WITH、EXPLAIN 开头 |
| 禁止的语句 | INSERT、UPDATE、DELETE、DROP、ALTER、TRUNCATE、CREATE、CALL、EXEC 等写操作和存储过程 |
| 多语句 | 禁止分号拼接多条语句 |
| 注释 | 禁止使用注释隐藏危险关键字 |
| 结果行数 | 默认最多返回 100 行，超出部分截断 |
| 执行超时 | 默认 30 秒 |
| SELECT * | 提示模型避免全字段查询，降低无效扫描 |
校验不通过时不会执行 SQL，页面会给出具体的安全限制提示。人工编辑 SQL 后重新预览，同样会重新校验。
只读查询仍可能消耗大量数据库资源。生产环境应使用只读账号、限制可查询的 Schema，并配合数据库侧的资源治理。
结果查看
SQL
- 展示生成的 SQL，支持语法高亮和展开/收起；
- 可以复制 SQL；
- 可以进入编辑模式修改 SQL，再执行只读预览；
- 低置信度、被自动纠正或存在告警时会给出标记。
数据表格
- 展示列名、类型和结果行；
- 支持选中行、复制结果；
- 结果行数受预览上限约束。
图表
支持 8 种图表类型：
| 类型 | 适用场景 |
|---|---|
| 折线图 | 时间趋势 |
| 面积图 | 累计量或趋势强调 |
| 柱状图 | 分类对比 |
| 堆叠柱状图 | 分类构成 |
| 横向柱状图 | 类别名称较长的排名 |
| 饼图 | 占比 |
| 散点图 | 两个数值维度的相关 性 |
| 双轴图 | 两个量纲不同的指标对比 |
图表基于结果列自动推断维度与指标，也可以手动切换类型。数据不满足图表要求时会提示原因，而不是渲染空图。
导出
查询结果支持导出 CSV：
- 文件编码为 UTF-8，并带 BOM，便于 Excel 正确识别中文；
- 只导出当前结果集，不导出图表；
- 导出在前端完成，不产生额外服务端任务。
结果洞察
- 对结果样本做摘要分析，默认采样 10 行；
- 给出趋势、异常、极值和可能的业务解释；
- 洞察是模型生成的辅助信息，不能替代人工核验。
保存为 API 草稿
问数结果可以转为 API 草稿：
- 点击「保存为接口」；
- 前端把 SQL、数据源、Schema、表名和问题写入
sessionStorage（键名ai-sql-draft-{timestamp}）； - 跳转到工作台的脚本模式，并携带
aiDraftKey； - 在工作台补全接口名称、路径、参数和响应配置；
- 测试通过后发布。
草稿只包含 SQL 和上下文，不会自动发布接口。关闭页面后未使用 的草稿会随会话存储清理。
语义层
语义层用于把业务术语映射到物理表和字段，提升生成准确率。
术语
| 字段 | 说明 |
|---|---|
| 术语名称 | 业务叫法，如「成交额」 |
| 同义词 | 多个同义表达，逗号分隔 |
| 术语类型 | 表、字段、枚举值、说明 |
| 数据源 / Schema / 目标对象 | 术语映射到的物理对象 |
| 启用状态 | 关闭后不参与提示词 |
指标
| 字段 | 说明 |
|---|---|
| 指标名称 | 业务指标名 |
| 指标编码 | 唯一编码 |
| 指标说明 | 业务含义 |
| 口径 SQL | 必填，定义指标的计算口径 |
| 关联表 | 指标涉及的表 |
| 维度提示 | 常用维度 |
| 示例 SQL | 参考查询 |
| 数据源 / Schema | 作用范围 |
| 启用状态 | 关闭后不参与提示词 |
语义配置有 60 秒缓存，修改后最多 1 分钟生效。单次提示词最多注入 30 条术语，避免上下文过长。
场景与词典运营
场景运营 用于维护场景路由、同义词词典和问数成功率统计：
- 场景定义决定问题进入哪条处理流程；
- 同义词词典补充业务叫法；
- 统计展示场景编码、失败原因、调用量、成功率、平均 Token 和平均耗时；
- 成功率按 ≥90%、≥70%、<70% 三档着色。
场景路由按「词典精确匹配 → 场景亲和度 → 模型判断」逐级降级。语义解析置信度低于 0.6 时不会猜测场景，而是发起澄清或走自由问答。
指标和术语在「语义配置」中维护；「场景运营」维护的是场景、词典和统计，两者不要混淆。
多轮与追问
- 多轮对话默认注入最近 5 轮历史；
- 结果下方提供追问建议，如按月汇总、只看某值、取前 10、计算平均值；
- 会话标题取首个问题前 12 个字符；
- 历史会话保留最近 50 个。
限制与默认值
| 项 | 默认值 |
|---|---|
| AI 总开关 | 关闭 |
| 最大返回行数 | 100 |
| 模型超时 | 30 秒 |
| 历史注入轮数 | 5 |
| 洞察采样行数 | 10 |
| 语义缓存 | 60 秒 |
| 单次注入术语 | 30 条 |
| 常规 AI 端点限流 | 10 次/分钟/用户 |
| 智能助理限流 | 30 次/分钟/用户 |
| 模型温度 | 0.2 |
常见问题
| 现象 | 原因 | 处理 |
|---|---|---|
| 提示 AI 未开启 | spring.ai.enabled=false | 在部署配置中开启并重启服务 |
| 无法选择数据源 | 当前项目未授权或数据源非关系型 | 检查数据源授权与类型 |
| 生成的 SQL 被拒绝 | 包含写操作、多语句、注释或非只读前缀 | 修改问题或手工调整 SQL |
| 结果为空 | 过滤条件过严、时间范围无数据或表选错 | 调整范围并重新提问 |
| 结果被截断 | 超过 100 行预览上限 | 增加聚合或过滤条件 |
| 回答与业务口径不一致 | 语义层未配置指标或同义词 | 在语义配置中补充术语和指标 |
| 保存草稿后找不到 | 草稿依赖浏览器会话存储 | 从工作台重新生成，或检查是否关闭了标签页 |