WorkBuddy 自动化实施润乾 NLQ 向导 - 以保险主题为例
在各类智能问数技术中，润乾NLQ的实施成本相对来讲已经很低，但仍需要人工完成元数据、词典、大模型转换提示词等工作。使用WorkBuddy 可以自动化完成这些工作，大幅度提升效率。
本文以保险数据为例，引导用户从材料准备开始，在一个全新的环境下，利用 WorkBuddy 自动化部署 NLQ 系统，最终实现“用自然语言查业务数据”。
简化的保险主题数据包括4个表，包含主子关系、多层外键关系，比较有代表性，表间关系如下图：
一、输入和输出
输入清单：
d:\attachments目录下有4个文件
01_表结构说明.csv
02_中文术语同义词说明.csv
03_枚举值说明.csv
04_动词和指标说明.csv
输出清单：
C:\Program Files\raqsoft\report\services\insurance\conf\insurance.lmd
C:\Program Files\raqsoft\report\web\webapps\demo\WEB-INF\files\dql\insurance.nlq
C:\Program Files\raqsoft\report\web\webapps\demo\WEB-INF\classes\insurance.md
C:\Program Files\raqsoft\report\web\webapps\demo\WEB-INF\classes\action\*.md
下面对输入输出逐一说明。
1.1 01_表结构说明.csv
需要明确：表、字段（不一定所有表、字段都要进 NLQ，只挑要问数的）、逻辑主键、逻辑外键。
采用csv格式可以方便编辑，而且文件比Excel小，也容易给WorkBuddy 。
1.2 02_中文术语同义词说明.csv
两种情况，按实际情况选：
●情况1：数据库表、字段本身有中文注释 → 直接用。
●情况2：整理一份"表名/字段名 → 标准中文名 → 同义词"对照文档，交给 WorkBuddy 。
1.3 03_枚举值说明.csv
●情况1：数据库直接存枚举值名称 → WorkBuddy 会自动 SELECT DISTINCT查出所有不重复值。
例：保单表的"付款方式"字段，枚举值直接是"网上支付、银行转账、银行代扣、银行代收、第三方支付"。WorkBuddy 会自动查出来写入词典。
●情况2：数据库存的是代码、又没有对应维表 → 整理一份枚举值说明文档。
1.4 04_动词和指标说明.csv
WorkBuddy 能自动生成动词和指标。用户可指定部分业务上重要的动词和指标，其他让WorkBuddy 自动生成。
1.5 输出物说明
元数据：
C:\Program Files\raqsoft\report\services\insurance\conf\insurance.lmd
说明：在数据库基础上封装而成，主要用于简化多表关联计算
打开方式：直接双击打开，在元数据IDE中编辑。
词典：
C:\Program Files\raqsoft\report\web\webapps\demo\WEB-INF\files\dql\insurance.nlq
说明：用于存储实体词、字段词、维词等。
打开方式：直接双击打开，在词典IDE中编辑。
大模型转换提示词：
C:\Program Files\raqsoft\report\web\webapps\demo\WEB-INF\classes\insurance.md
C:\Program Files\raqsoft\report\web\webapps\demo\WEB-INF\classes\action\*.md
说明：提交给大模型，用于把随意的自然语言转换成规范文本。insurance.md用于对话式页面、*.md用于查询式页面。
二、实操步骤
2.1 环境准备
●安装润乾报表、BI，配置好授权。
●准备数据库连接参数。
●确认 JDBC 驱动 jar 已就位。
●编辑 C:\Program Files\raqsoft\report\web\webapps\demo\WEB-INF\llm.properties，写入大模型的秘钥。
示例：
项 |
内容 |
格式 |
库类型 |
PostgreSQL |
名称 |
url |
jdbc:postgresql://192.168.1.5:5432/postgres |
JDBC 连接串 |
driver |
org.postgresql.Driver |
驱动全类名 |
user |
postgres |
用户名 |
password |
postgres |
明文 |
schema |
public |
模式名 |
同时确认 JDBC 驱动 jar 已放到安装目录的 common\jdbc\下（如 postgresql-42.7.3.jar）。
2.2 给 WorkBuddy 写工作要求
把准备好的材料，组织成一份四段式提示词，交给 WorkBuddy 自动完成。下面逐段说明每段内容，解释和示例。
第一段：# 工作目标（一句话说清要做什么）
●内容：一句话交代"基于什么数据、要上线什么、是什么场景"。
●解释：让 WorkBuddy 一开始就明确这是"多表关联的 NLQ 问数部署"。
●示例：帮我基于润乾 NLQ 上线一个智能问数 DEMO，数据集用保险数据集（postgres），是多表关联场景。
第二段：# 环境信息（列出所有客观事实）
●内容：安装根目录、数据库连接串、表清单、实例命名等，全部用明确的键值/列表列出。
●解释：这些是 WorkBuddy 无法自己猜到的客观信息，必须原样给出，否则会连错库、写错路径。
●示例：安装根目录、url/driver/user/password、表名、实例命名 insurance（lmd/nlq/jsp 统一用这个名）。
第三段：# 任务（按顺序全部完成，逐条列产出）
●内容：把要产出的和部署步骤拆成编号任务，每条写清"产出什么 + 关键规则 + 输出路径"。
1、生成元数据insurance.lmd
2、生成汉语词典insurance.nlq
3、配置数据源
4、真连真查验证
5、生成提示词*.md，这里要注意修改自带的样例提示词中的表结构和例句
6、Web 上线
●解释：明确每步的产出物和硬性规则（如"日期字段建外键"、"同类型词不重复"），能显著减少返工。规则宁可写细，也不要省略。WorkBuddy 在工作时会自动搜索官网中DQL、NLQ的相关文档，不需要专门给它提供文档。
●示例：任务 1 生成元数据 insurance.lmd（物理表 type:0、日期字段建日期外键、枚举字段建假表、desc 用中文）；任务 2 生成词典 insurance.nlq（全局词表复用 insurance、金额字段加 unitName、配实体/动词/指标）……以此类推。
第四段：# 约束（写明格式与检查要求）
●内容：输出语言、报错处理方式、访问方式等硬性约定。
●解释：约束段让 WorkBuddy 在出错时按正确方向排查（先查命令/classpath/URL），而不是乱猜，同时保证交付物可直接访问。
●示例：中文输出；报错先查编译/运行命令、classpath、URL 是否写对；要求这样访问：
http://localhost:6868/demo/raqsoft/dql/jsp/insurance.jsp。
2.3 检查 、修改WorkBuddy 的工作结果
WorkBuddy 的工作完成后，需要人工检查所有的输出物，发现问题通知WorkBuddy 改正。
这时也可以根据业务的需要，对各个输出物提出修改。
每个产出物的检查方法：
步骤 |
产出物 |
如何检查 |
生成元数据 |
insurance.lmd |
日期字段都有日期外键；枚举字段都建了假表；desc 是中文 |
生成词典 |
insurance.nlq |
动词/指标/量纲齐全；同类型词不重复；金额字段有 unitName |
生成提示词 |
insurance.md action/*.md |
词典部分和例子与 .nlq 一致，其他部分不变；含查询范式和不支持清单 |
配置数据源 |
raqsoftConfig.xml+ nlqConfig.xml |
JDBC 真连连通 |
Web 上线 |
insurance.jsp chat.jsp |
浏览器可访问、能点查询 |
真连真查 |
验证结果 |
自然语言问句返回真实数据 |
改正举例：
检查发现词典文件insurance.nlq有多个字段词重复，对WorkBuddy 提出下面的要求：
#词典中的词险种状态重复了，要改正
#其他词也要检查一下，有重复也要改正
#检查后续步骤，相应修改、调整
WorkBuddy 会自动改正，也会自动调整后续的提示词等内容。
修改举例：
假设希望WorkBuddy 在完成的工作基础上，为词典增加一个指标：某年某月的保费，可以这样提要求：
#词典中为保单表增加指标
名称：某年某月的保费；同义词某年某月度的保费
(1)计算方法：先从保单表中，按"签单日期"筛选出某年月（年月由查询时指定，例如 2026、12）的所有保单；
(2)再对这些保单的"保费"字段做求和；
(3)求得的保费总和，就是"某年某月的保费"。
#检查后续步骤，相应修改、调整
多轮检查、改正：
WorkBuddy 修改、调整后，需要人工再复查。有问题继续要求WorkBuddy 修改、再复查，直到完全正确为止。
三、效果和总结
访问查询页面：
http://localhost:6868/demo/raqsoft/dql/jsp/insurance.jsp
访问对话页面：
http://localhost:6868/demo/raqsoft/chatbi/jsp/chat.jsp
工作量估计：
准备工作加上WorkBuddy 的工作，大约需要1到1.5天。
检查、修正工作大于需要0.5天。
总共需要约2天即可完成。
四、附录：WorkBuddy 工作要求
下面是给 WorkBuddy 的完整工作要求原文，其中斜体的部分是针对保险数据的，可以把这部分替换成实际项目中的信息，复制给WorkBuddy ：
# 工作要求
帮我基于润乾NLQ 上线一个智能问数 DEMO，数据集用保险数据集（postgres），是多表关联场景。
# 环境信息
- 安装根目录：`C:\Program Files\raqsoft\report`（运行实例），文件名 / 服务名统一。
- 数据库：postgres，`url=jdbc:postgresql://192.168.1.5:5432/postgres`，`driver=org.postgresql.Driver`，`user=postgres`，`password=`postgres`。
- 授权文件：`D:\ 授权 \润乾报表研发人员内部专用授权20261231 含 nlr.xml`。
- 实例命名：`insurance`（lmd/nlq/jsp 统一用这个名）。
## 任务（按顺序全部完成）
1.** 生成元数据 `insurance.lmd`**：d:\attachments 目录中有我准备好的附件，要求根据这些附件，并连接数据库读数据表的真实结构，生成 DQL 元数据（JSON，UTF-8，顶层 `{tableList, namedDimList}`）。物理表 `type:0`，含主键与 `fkList`。日期型字段建「日期」虚拟维（`type:2`, dimType 5，levelList 含年 / 季度 / 月 / 日 / 年月 / 月日 / 年季度 / 星期 / 周 / 年周），日期字段都要建立外键。字符串枚举字段建枚举虚拟维（比如性别、省等，根据需要自己定义假表）。字段 desc 用中文。输出到 `WEB-INF/files/dql/insurance.lmd`。
注意：附件内容与数据库真实结构/ 取值比对，不一致处写入 d:\attachments\ 不一致.csv。
** 启动 web 服务：C:\Program Files\raqsoft\report\bin\startreportcenter.bat**
（其中包含了DQL 服务）。
2. ** 生成汉语词典 `insurance.nlq`**：基于上面的 lmd，生成 NLQ 词典（JSON）。要点（务必遵守，否则查不出）：
- 全局词表（无效词 / 量纲 / 存在词 / 非法词 / 宏词 / 聚合词 / 连词 / 比较词）参考 demo 自带 的nlq 直接复用。
- ** 注意：同类型的词不能重复，比如不能定义两个实体词都是“险种”，不能定义两个字段词都是“险种类别”等等。**
- `dimConfigList` 里 `dimName` 必须等于 lmd 中维表名（实体维 = 物理表名如 insurance/customer，日期/ 枚举维 = 虚拟表名如 日期 /保单状态）。
- `tableViewList` 的 `expStr` 规则：` 表名. 字段名 ` 或 `fkN. 字段名. 字段名…`；** 路径必须终止于外键引用字段（FK key）**，例如国家名称 =`fk1.N_NATIONKEY`（不是 `fk1.N_NAME`）、客户地区 =`fk1.C_NATIONKEY.N_REGIONKEY`。原生主键字段不要加 `isFKCluster:true`。
- 字段簇 `fieldCluster` 只放字符串维度字段，** 数值字段不进簇 **；簇词不指向含数值的簇。
- `dataType`：数值 =1、字符串 =11、日期 =8（与 lmd 不同）。金额字段加 `unitName:"元"`。
- 每张表配 `entityList` 实体（例如：保单、客户、险种、保单产品），多表外键字段用中文命名（如「客户国家」「客户地区」）。
- 参照 tpch2.nlq，生成动词和指标
- 输出到 `WEB-INF/files/dql/insurance.nlq`。
3. ** 配置数据源（xml）**：
- `WEB-INF/raqsoftConfig.xml` 的 `DBList` 参照TPCH2 和 NLQ4TPCH加两个 DB：
`DQL4insurance`，`NLQ4insurance`
- `WEB-INF/classes/nlqConfig.xml` 参照TPCH2加insurance：
`<NLQname="insurance">
<DB>DQL4insurance</DB>
<MetaData><insurance.nlq 绝对路径 ></MetaData>
<RaqsoftConfig></RaqsoftConfig>
</NLQ>`。
4. ** 真连真查验证 **：写一个 JDBC 测试程序，用 DQL 驱动验证多表深路径聚合，例如“基本保额大于10000 的个人险种详情”，用 NLQ 驱动验证汉语查询（如「按年汇总个人保单数和保费求和」「某月新增保单」「签单日期是去年的个人保单」），返回真实结果，确认全链路可用。
5.** 生成 LLM 提示词 **：基于 nlq 的词典，依据`WEB-INF/classes/Chat_NLQ_NLC.md` ，** 要求：只改字典部分和例句，其他保持不变 **，生成「自然语言→规范文本 (nlq)」的提示词 `insurance.md`，词典部分与 nlq 完全一致（表 / 字段 / 维词 / 常数词 / 聚合词）。
基于nlq 的词典，把`WEB-INF/classes/action/`中的所有md 文件都改成 insurance 对应的内容，包括词典内容和所有例句都按照词典修改。
6.**Web 上线 **：
复制 `raqsoft/dql/jsp/dqlSearch.jsp` → `raqsoft/dql/jsp/insurance.jsp`，改 `dataSource="NLQ4insurance"` 。
修改`raqsoft/chatbi/jsp/chat.jsp`，改 `dataSource="NLQ4insurance"`
## 约束
- 中文输出；报错先查编译 / 运行命令、classpath、URL 是否写对。
- 要求这样访问
http://localhost:6868/demo/raqsoft/dql/jsp/insurance.jsp
http://localhost:6868/demo/raqsoft/chatbi/jsp/chat.jsp
