智能体开发分享：TEXT2SQL数据库查询智能体开发介绍

摘要：Text2SQL数据库查询智能体开发指南

文档目的与作用：
本文档旨在为开发团队提供一套标准化的 数据库查询智能体（Text2SQL Agent） 开发规范与实战指南。通过讲解智能体平台（XAG）的核心架构与工作流，指导开发者如何利用 AI 技术将自然语言问题转化为精准的 SQL 查询，并最终生成可视化的业务分析报告。本文档是连接业务需求与底层数据仓库的关键技术手册，旨在降低 AI 应用开发门槛，确保智能体输出的准确性与稳定性。

学习目标：
通过本文档，您将掌握以下核心技能：

1. 架构认知：理解 XAG_VANNA（Text2SQL）、XAG_TRAINING（知识库）、Dify（编排）智能体开发平台等核心组件的协作机制。
2. 全流程开发：学会从 0 到 1 构建一个 AI 问数的智能体，涵盖知识库建立、Dify 工作流配置、企微机器人对接及测试调优的全过程。
3. Prompt 工程进阶：深入理解 “三层提示词逻辑”（意图识别层、SQL 映射层、分析呈现层），掌握解决 AI 生成 SQL 不稳定、上下文缺失等痛点的核心方法论。
4. 实战调试：学会如何通过微调 SQL 知识库和优化提示词，提升智能体问数的准确率。

一. 核心服务组件概览

Text2SQL数据库查询分析智能体主要由以下核心服务协同工作，开发人员需熟悉各组件的功能定位：

二. 总体架构图

三. 开发全流程详解

3.1 第1步：建立智能体知识库

在开发前，必须明确智能体的基础身份信息，这些信息也将用于区分不同的知识库和后续的企微机器人注册。

值得注意的是，本文的Text2sql的知识库架构设计：知识库不是以业务系统数据库切分，而是一个查询的主题就是一个独立的知识库。

必须提供的信息：

• 目标数据库：明确查询源，例如 BI数据库、ERP数据库。
• 智能体代码：唯一标识，例如 BI_QBOEN_ORDER。
• 智能体名称：例如 BI销售订单。

说明：有了这些信息，即可在 XAG_TRAINING 中配置对应的 SQL 知识库。知识库配置需要改XAG_VANNA的配置文件，目前找samt007添加即可。

3.2 第2步：开发 Dify 智能体

建议直接复用现有成熟模板进行修改，以减少配置工作量。

• 参考模板：BI销售订单AI分析
• 模板链接：https://xagent.compny.com/app/c7d2fc49-4f38-4b95-895e-b3936016900b/workflow

关键修改点：

1. 开场白/帮助信息：修改当用户输入“你好”或“帮助”时的回复，指导用户如何使用当前智能体。
2. LLM-分析用户问题（节点1）：负责意图识别，将用户问题转换为 Text2SQL 可理解的标准化问题（详见后文专题说明）。
3. HTTP 请求-API获取数据：关键步骤，需将 API 请求参数中的 Knowledge Base Key 修改为步骤 3.1 中创建的对应知识库 KEY。
4. LLM-整理分析结果（节点2）：负责数据分析，根据数据库返回结果生成最终报告。

3.3 第3步：配置企微对接

1. 新增企微机器人：需联系企业微信管理员（目前直接找samt007配置）。
2. XBOT 新增配置：在 XAG_BOT 服务中配置新机器人的回调地址，打通企业微信与 Dify 智能体的消息链路。

3.4 第4步：测试验证与微调（核心工作）

这是耗时最长、工作量最大的环节。

• 核心目标：提高 AI 生成 SQL 的准确率。
• 调试逻辑：只有 SQL 正确，数据才正确，分析才有意义。
• 故障排查：
  • 如果 SQL 生成错误，需检查 SQL 知识库 是否缺少相关表结构或训练数据。
  • 如果 SQL 逻辑偏差，需检查 Dify 提示词 是否准确描述了查询意图。

四. 核心逻辑专题：数据库查询 Prompt 提示词分层逻辑

数据库查询分析智能体开发——三类提示词（Prompt）的逻辑分层解析

为了解决 Text2SQL 的准确性和稳定性问题，本架构将提示词（Prompt）划分为三个职能层级，分别对应 意图识别与标准化、SQL逻辑映射、数据分析与呈现。

第1层：意图识别与标准化层（配置于 Dify 第一个 AI 节点）

核心职能：负责将用户模糊的口语化提问，转化为 Text2SQL 模型可执行的精确指令（语义补全提示词）。

• 痛点解决：直接将“分析我上周工作”传给 Text2SQL 模型（如 Vanna）会导致失败，因为模型缺乏上下文（“我”是谁？“上周”具体指哪几天？）。
  • 或者你会考虑这个问题，我都给SQL知识库行不行？理论上是可行的，但是，实际上如果这样子做，会导致AI生成的SQL的稳定性大打折扣。
  • 因为生成SQL本身就是一个复杂而且容易出错的过程，如果再额外添加和SQL生成无关的自然语言分析，无非是导致模型的注意力机制（Attention Mechanism）被分散，从而显著增加了产生“幻觉”或逻辑错误的概率，使得最终生成的 SQL 既不准确也不稳定。
  • 简单来说，就是将“意图识别”与“代码生成”强行耦合在一起会导致推理逻辑的混乱，从而影响SQL的生成成功率。
• 处理逻辑：该节点需进行语义补全，将自然语言转换为包含具体时间范围、人员工号及指定查询脚本名称等的标准化提示词。
• 转换示例：

  • 用户输入1：分析我上周的工作情况。

  • AI 转换后：参考信息中心工时管理知识库，直接调用 [按月分析工时查询脚本] 和 [请假明细查询脚本]（请严格按照「工时数据」和「请假数据」生成 2 条独立的 SQL）。查询范围：2025年12月1日至2025年12月7日；人员工号：‘XX230482’。请汇总该员工的工时填报、项目工时及请假信息。

  • 用户输入2：分析25年份外销系统销售总量和销售总额，同比去年是否有增长？

  • AI 转换后：参考销售统计和公共模块知识库，查询销售发货明细表中业务类型='外销’的发货数据：1）统计2025年1月1日至2025年12月8日的销售总量（分玻璃和非玻璃）和销售总额；2）统计2024年1月1日至2024年12月8日的销售总量（分玻璃和非玻璃）和销售总额；3）按年份分组统计，以便进行同比分析。

第2层：SQL 逻辑映射层（配置于 SQL 知识库/RAG）

核心职能：存储标准化的 SQL 模板，负责将第一层指令中的查询要求（例如“脚本名称”等）映射为可执行的数据库查询语句。

• 处理逻辑：当接收到第一层传递的查询要求（如 [请假明细查询脚本]或者业务类型='外销'）时，系统从知识库中检索对应的 SQL 结构或者文档，并产生对应的SQL脚本。
• 知识库内容示例：

    -- [请假明细查询脚本]
    SELECT ITC_GROUP, ITC_SUB_GROUP, EMP_NUMBER, EMP_NAME,
           LEAVE_TYPE_DESC,  -- 请假类型
           LEAVE_ITEM,       -- 请假事由
           TO_CHAR(START_DATE,'YYYY-MM-DD') START_DATE,
           ...
      FROM OAUSER.XXX_ITC_EMP_LEAVE_V
     WHERE DOC_STATUS = 30 
       AND ... (动态条件占位符)
	   
	--[销售统计]
	统一使用销售发货明细表:`xx_dm.xxx_qboen_dm_report_sale_statistic_return_claim` 进行发货量和销售金额统计。
	查询约束与逻辑
	1.  核心过滤（默认必填）：
	- 除非明确排除，否则必须限制单据类型：`t1.bill_type_code in ('SALE')`。
	- 业务类型默认全选：`t1.biz_type_code in ('WX', 'NX', 'PT')`（WX=外销, NX=内销, PT=配套）。

• Vanna（text2sql）产生的SQL结果样例：

	WITH sales_data AS (
    SELECT 
        EXTRACT(YEAR FROM t1.report_date) AS sale_year,
        t1.unit,
        t1.sale_qty,
        t1.sales_amt,
        t1.sys_conversion_rate
    FROM xx_dm.xxx_qboen_dm_report_sale_statistic_return_claim t1
    WHERE t1.language = 'ZHS'
      AND t1.bill_type_code = 'SALE'
      AND t1.biz_type_code = 'WX'
      AND ((t1.report_date >= '2025-01-01'::date AND t1.report_date < '2025-12-08'::date + 1)
          OR
          (t1.report_date >= '2024-01-01'::date AND t1.report_date < '2024-12-08'::date + 1)))
	SELECT 
		sale_year::TEXT AS sale_year,
		SUM(CASE WHEN unit = '片' THEN sale_qty ELSE 0 END)::TEXT AS glass_qty,
		SUM(CASE WHEN unit != '片' THEN sale_qty ELSE 0 END)::TEXT AS non_glass_qty,
		ROUND(SUM(sales_amt * sys_conversion_rate), 2)::TEXT AS total_amt_cny
	FROM sales_data
	GROUP BY sale_year
	ORDER BY sale_year;

第3层：数据分析与呈现层（配置于 Dify 第二个 AI 节点）

核心职能：基于数据库返回的查询结果，结合业务背景生成分析报告及可视化图表。

• 处理逻辑：此节点的提示词专注于**“如何分析数据”和“结果呈现规范”**。它接收 SQL 执行后的原始数据，根据用户的业务需求（如“人力瓶颈分析”、“工时分布”）生成最终报告。
• 配置内容：主要是报告语言（例如中文输出），结果展示要求（例如不要输出SQL报错信息和数据库字段等），报告格式要求（如 Markdown 表格）以及图表生成要求（如 Echarts 图表展示）等。

五. 实战案例剖析：如何定位与解决 AI 智能问数异常

5.1 为什么要强调“逻辑分层”？

在日常的 AI 智能问数智能体开发中，我们最常遇到的反馈是：“这个数据不对”、“那个数据查不到”。
面对这些问题，开发者必须具备清晰的 问题定位思路：是 Dify 的意图理解歪了？还是 Vanna 的 SQL 知识库没覆盖到？

核心原则：

AI 问数问题的解决，最终必须落实到“让 AI 生成正确的 SQL”这一方向上。
任何不以修正 SQL 逻辑为目的的调整，通常都很难彻底解决问题。

5.2 典型故障排查案例

场景描述：
用户提问：“2025年1-11月份国际销售四部大巴夹层玻璃销量。”
故障现象：
AI 反馈查询不到数据结果。Vanna数据库查询服务返回的结果是空。

第1步：查看 AI 生成的错误 SQL（定位问题）

通过查看后台日志，发现 AI 生成的 SQL 如下：

SELECT ...
  FROM xx_dm.xxx_qboen_dm_report_sale_statistic_return_claim t1
 WHERE ...
   AND t1.assess_dept_name = '销售四部'   -- [正确] 知识库已覆盖部门映射
   AND t1.produce_type LIKE '%夹层%'     -- [正确] 知识库已覆盖加工类型
   AND t1.location_desc LIKE '%大巴%'    -- [错误] AI 误将“大巴”识别为“位置说明”字段

原因分析：
AI 理解了“销售四部”和“夹层”，但对于“大巴”这个词，它不知道对应数据库的哪个字段。由于缺乏明确指引，AI 产生幻觉，猜测它可能属于 location_desc（位置说明）字段，导致查询条件错误，自然查不到数据。

第2步：确定解决方案（对症下药）

经过对应的BI开发/实施确认（很有必要的是，复杂的取数也需要和业务确认），“大巴”实际上属于 “产品类型” 维度，该维度有 4 个固定值：大巴、加工玻璃、货车、轿车。

此时，我们需要调整 Dify 第一层（意图识别层） 的提示词，明确告诉 AI 如何翻译“大巴”。

第3步：实施调整

在 Dify 的第一个 AI 节点（意图识别与标准化）中，新增以下知识库定义：

「大巴/加工玻璃/货车/轿车」：对应‘产品类型’字段。
例如：用户问“大巴夹层玻璃”，应转换为：产品类型=‘大巴’，加工类型=‘夹层’。

(备注：前提是 SQL 知识库中已经定义了“产品类型”对应的数据库字段名 item_type。如果 SQL 知识库里连这个字段都没注册，那还需要同步调整 SQL 知识库。)

第4步：验证结果

调整后，AI 重新生成的 SQL 逻辑正确：

WITH ship_detail AS (
    SELECT ...
      FROM xx_dm.xxx_qboen_dm_report_sale_statistic_return_claim t1
     WHERE ...
       AND t1.assess_dept_name = '销售四部'
       AND t1.item_type = '大巴'       -- [修正成功] 正确映射到了 item_type 字段
       AND t1.produce_type = '夹层'
)
...

至此，数据查询恢复正常。

5.3 总结：调整策略

当遇到数据问题时，请遵循以下判断逻辑：

1. 如果是“词没听懂”（如本例中的“大巴”）：调整 Dify 意图识别层，增加名词解释。
2. 如果是“表/字段找不到”：调整 Vanna SQL 知识库，补充 DDL 或字段注释。
3. 如果是“逻辑太复杂写不对”：在 Vanna SQL 知识库 中增加类似的 SQL 问答对（Few-shot Training）作为参考范例。

六. 终端实现效果演示（以企业微信为例）

为了更直观地展现 Text2SQL 智能体为业务带来的价值，以下展示其在企业微信终端的实际交互效果。

场景 1：销售发货数据智能问询

本场景展示了销售部门业务人员如何通过简单的自然语言，快速获取多维度的发货数据统计及专业的分析报告。

场景 2：交互形式多样化（流式输出 vs 卡片呈现）

智能体支持根据不同的业务场景配置多种终端展示样式：

• OA工时管理查询：采用流式文本输出，极速响应并动态生成分析结论。
• 智能体运营分析：采用企微消息卡片呈现，如果分析的内容较多，用卡片跳转HTML链接方式的用户体验是最好的。而且数据结构更清晰，视觉体验更佳，便于阅读与转发。

💡 效果总结：
从上述演示可以看出，Text2SQL 智能体的核心基石在于“底层 SQL 生成的准确性”。只要智能体底层生成的 SQL 逻辑无误且提取的数据精准，AI 便能在数据分析与内容呈现层展现出极高的专业度与合理性，真正实现“让数据触手可及”，大幅提升业务决策效率。

七. 总结与思考

通过阅读本文，您应该要了解并掌握 数据库查询智能体（Text2SQL Agent） 的标准化开发全流程。

建议您动手实践：
最好是自己参考文档中的模板，尝试建立一个简单的智能体。通过配置 Dify 工作流、编写 Prompt、录入 SQL 知识库，亲身体验一下 AI 是如何将自然语言转化为 SQL 的。然后，尝试用不同的提问方式（模糊的、精确的）去测试智能体，观察并微调提示词，直到它能稳定输出正确的数据分析结果。

更深层的思考：
还有一点，通过本文的案例，您也应该能意识到，在面对 AI 辅助开发这种新兴技术时，“结构化思维” 比单纯的写代码更重要。我们通过将复杂的 Prompt 拆解为“意图识别”、“SQL 映射”、“数据分析”三层，成功解决了 AI 幻觉和不稳定的问题。

这启示我们，对于具有代表性的技术开发，应该思考通过什么样的架构设计（如逻辑分层）来提高系统的鲁棒性，以及如何制定可落地的开发规范（如标准化的 Prompt 模板）来提升团队的整体开发效率。

本次的技术培训文档就是这些内容，谢谢大家。