AI 生成报表
在设计器 AI 助手面板中用自然语言生成或美化网格报表、单据模板和仪表盘，含模型配置、工具智能开关、生成流程、各类型能力与限制。
概述
设计器右侧的 AI 助手面板可以按自然语言描述生成报表结构：网格报表、单据模板和仪表盘。开启「工具智能」时，AI 会先读取真实表结构和字段取值、试跑 SQL，再产出报表，并对结果自检，SQL 跑不通时自行修正。
AI 助手使用管理员配置的大语言模型。模型需兼容 OpenAI 的 /v1/chat/completions 接口。
功能入口
- 使用：报表设计器顶栏的「AI 助手」图标按钮（星光图标），再次点击关闭面板。网格报表、单据模板、仪表盘设计器均有此入口；数据大屏设计器不提供 AI 助手。
- 配置：左侧一级菜单「AI」>「使用指南」，页面标题为「AI 功能中心」，其中第三部分「AI 配置」用于配置模型和工具智能。该页面需要系统管理权限。
前置条件
| 条件 | 说明 |
|---|---|
| 启用 AI 功能并配置模型 | 需启用、填写 API Key 并选择模型。未满足时，面板空状态会列出缺项并提供「去配置」入口，此时发送消息会失败 |
| 有可用的数据连接 | 没有数据连接时，AI 只能凭空编造字段名，生成的报表绑不到真实数据。缺项时面板提示「去添加」 |
本地部署的模型服务（Ollama、vLLM 等）的 API Key 可留空。
操作步骤
配置模型
- 打开「AI」>「使用指南」，在「AI 配置」的「LLM（大语言模型）」中打开「启用 AI 功能」。
- 选择「AI 服务商」，填写「API Base URL」「API Key」，选择「模型」。
- 按需调整「Temperature」和「Max Tokens」。
- 点击「测试连接」，确认返回成功，再点击「保存」。
生成报表
- 在设计器中新建或打开报表，点击顶栏「AI 助手」。
- 在面板底部选择「数据连接」（智能生成时显示），在输入框描述需求，例如"做一张各科室收入汇总报表，按科室小计、底部总计，可按日期段筛选"，点击「发送」。
- AI 生成的结果自动落在画布上，处于未确认状态，顶栏出现「确认到报表」按钮（单据模板为「确认到单据模板」，仪表盘为「确认到看板」，随类型变化）。在「确认」之前可以逐步退回。
- 检查画布结果，满意后点击「确认到报表」，再保存报表。保存前改动不会落库。
- 需求过于简略时，AI 会弹出关键点澄清卡（如「要不要汇总？」），可选择后点击「按所选生成」，或点击「按推荐直接生成」。
其他输入方式：
- 参考图：可添加或粘贴一张图片让 AI 模仿样式，图片不超过 4 MB。
- 选中对象：在画布上选中单元格或组件后，面板显示针对所选对象的建议操作。
- 美化风格：网格报表下可在「风格」中选择预设，生成结果套用该主题。
- 结果卡片：有「接受」「仅接受版式」「放弃」等按钮的场景中，「仅接受版式」保留当前报表的数据集与参数，只替换版式；新版式用到的数据集当前报表里没有时会被拦截。
参数说明
LLM 配置
| 属性 | 说明 | 取值/默认值 |
|---|---|---|
| 启用 AI 功能 | 总开关 | 开关 |
| AI 服务商 | 服务商目录，可在目录管理中增删改 | 内置若干服务商，可自定义 |
| API Base URL | 模型服务地址，含 /v1 |
选服务商后自动带出默认值，可修改 |
| API Key | 密钥。保存后界面脱敏显示 | 本地服务可留空 |
| 模型 | 选择服务商提供的模型或手工输入 | 文本 |
| Temperature | 生成随机性，两端标注为精确和创意 | 0 到 1，步长 0.1 |
| Max Tokens | 单次回复的最大 token 数 | 16384 到 128000，步长 1024 |
| 自定义提示词 | 追加在系统提示词末尾的额外指示（「提示词与知识文档（高级）」中） | 文本，可选 |
| 重新加载知识文档 | 修改 data/ai-docs 下的规范和知识文档后点击，无需重启后端 |
按钮 |
| 文档更新 | 填写官网地址后「检查更新」「下载更新」，检测知识文档新版本 | 自部署一般无需 |
工具智能
| 取值 | 说明 |
|---|---|
| 先查真实表结构、试跑 SQL 再产出（默认） | AI 可调用只读工具：list_tables 列表、describe_table 查表结构、search_values 查字段取值、preview_sql 试跑 SELECT、compile_and_validate 编译并校验结果。单次生成的模型调用和数据库查询显著增多 |
| 只用已有信息一次生成 | 模型不能核对真实列名，SQL 更容易跑不通 |
工具的安全限制：
| 限制 | 说明 |
|---|---|
| 只读 | SQL 只能是单条 SELECT，自动加方言 LIMIT |
| 超时 | 查询超时 8 秒 |
| 行数 | 试跑最多返回 100 行；search_values 最多 50 个取值 |
各类型支持情况
| 类型 | 支持 | 说明 |
|---|---|---|
| 网格报表 | 生成、美化、问答 | 面板名称「智能报表助手」。可套用美化风格预设 |
| 单据模板 | 生成、美化、问答 | 面板名称「智能单据模板助手」 |
| 仪表盘 | 生成、美化、问答 | 面板名称「智能仪表盘助手」 |
| 数据大屏 | 不支持 | 大屏设计器没有 AI 助手 |
面板根据输入自动判断场景：问句或以"怎么""如何"开头的为问答；有报表时含"美化""配色""居中"等词的为美化；其余为生成。
示例
用 AI 生成"各科室收入汇总报表"：
- 「AI」>「使用指南」中完成模型配置，「测试连接」成功。
- 「数据连接」中已有指向业务库的连接。
- 新建网格报表，打开「AI 助手」，选择该数据连接，输入"做一张门诊收费明细报表，列出就诊日期、科室、核算项目、金额，可按日期段、科室筛选"，发送。
- 面板显示"智能设计中"，AI 依次查询表和列、试跑 SQL、编译校验，随后画布出现报表，数据集和查询表单已生成。
- 点击顶栏「确认到报表」，保存。
注意事项
注意：Max Tokens 不能低于 16384。思考类模型的推理过程与回复共用这份预算，预算被推理占满时接口仍返回成功但正文为空，表现为等待很久没有结果。
注意：外部 AI 助手（Claude、Codex 等）经 MCP 接入时使用它们自己的模型，不需要这里的模型配置，见 MCP 接入。
提示：AI 生成的结果仍需人工检查数据集 SQL、字段绑定和版式。开启「工具智能」能减少字段编造，但不保证业务口径正确。
提示：AI 的改动在点击「确认到报表」之前，可以在面板的「未确认的改动」中逐步撤销。
