几天前介绍了个基于银行风控场景的 Text2SQL 案例，上次这个案例是在 Coze 上搭建且整体结构比较简单。这篇来进一步演示下，如何在 dify 上实现一个更加完整且符合当前业界最佳实践的 Text2SQL+Python 案例。
这篇试图说清楚：
当前主流的几种 Text2SQL 技术范式、信贷风控场景需求分析、工作流的深度拆解，工程化实践与优化方向参考。
以下，enjoy:
注：视频中演示的是基于Coze的实现过程，下述Dify复现最终效果类似。
1
四种主流 Text2SQL 技术范式介绍
从 Text2SQL 的技术发展脉络来说，前后大致包括：基于规则的方法、深度学习模型、预训练语言模型到 LLM 这四个阶段发展，每个阶段都有其特点和局限性。前面三种在我上篇文章中已经详细介绍，这里不再赘述。在正式介绍案例前，再快速过下当前业界常见的三种方法。
Text2SQL案例演示：信贷风控策略场景（Coze工作流版）
1.1
基于 Prompt Engineering 的方案
这类方案比较简单粗暴，就是通过精心设计的提示来引导 LLM 生成 SQL，一般包含下面这些做法：
零样本提示：直接向 LLM 提供数据库模式和自然语言查询，直接生成 SQL。少样本提示：在提示中包含几个示例，帮助 LLM 理解任务模式。链式思考（也就是 Chain-of-Thought）：引导 LLM 逐步推理，分解复杂的 SQL 生成过程。自我纠正：让 LLM 生成 SQL 后，再让它检查和修正可能的错误。
1.2
基于模型微调的方案
这类方案是通过在特定数据集上微调预训练模型，使其更适合特定任务场景的 Text2SQL 任务：
指令微调：使用特定于任务的指令来微调 LLM。多任务微调：同时在多个相关任务上微调模型，提高其泛化能力。特定架构微调：设计特定的模型架构来处理 Text-to-SQL 任务的特点。
注：对这部分感兴趣的盆友可以了解下 MIGA（基于 T5 的两阶段多任务预训练模型）、RESDSQL 等。
1.3
RAG 驱动的方案
RAG 方案的思路是结合外部知识来增强 Text2toSQL 的能力，给 LLM 提供足够清晰的上下文,这也是本文要介绍的方案特性之一。
模式检索：根据自然语言查询检索相关的数据库模式信息。示例检索：检索类似的查询 SQL 对作为参考。文档检索：检索相关的文档或知识来帮助理解查询意图。历史查询检索：在多轮对话中检索历史查询来维护上下文。
注：文档检索和历史查询检索在下述案例中没有涉及
上述三种分类更多是一种方法的区分，实际应用中建议采用结合上述多种技术的混合方案，将任务分解为多个阶段，每个阶段使用最适合的技术，从而发挥各自的优势。
2
信贷场景需求分析
上篇文章中，花了些篇幅介绍了标准企业信贷风险策略迭代的完整流程，这里同样不再做赘述相关细节，以下针对其中的核心痛点再做次总结说明。
信贷产品的风控策略迭代日常工作中，涉及大量且时效要求较高的数据查询、加工及分析工作。也因为这些数据查询及加工环节一般会涉及多库表关联，代码调试和数据验证耗时较多，导致很多时候大量精力消耗在基础数据处理上，侵占了风险模式识别、策略创新和业务赋能这些核心工作的时间。
与此同时，有一定工作经验的风险策略从业人员都在历史工作中沉淀了大量的参考代码库，经过人工和标注可以很快的进行结构化提炼，从而构建贴合使用场景的高质量知识库，这也是 LLM 动态生成 SQL-Python 脚本的重要基础。理想状态下，使用这种基于 RAG 的 Text2SQL+Python 工作流，可以让数据查询及加工响应时间从传统小时级或天级缩短至分钟级，减少 70%+的代码开发和调试时间成本。
3
工作流深度拆解
3.1
系统架构介绍
核心设计理念是"理解→生成→验证→执行→解释"的全自动化闭环。通过SQL模板库和字段参考库实现领域知识的系统化沉淀，采用"取数与分析分离"的计算架构让SQL专注数据获取、Python承担复杂分析，创新性地引入分步推理的SQL生成机制（预处理+生成）和验证闭环（验证失败自动修正），在多层安全防护下实现了从自然语言需求到技术实现的全自动化转换。
3.2
各核心组件说明
知识库增强
这个模块采用了混合检索策略，系统同时查询"SQL 模板库"和"字段参考库"。召回更多的上下文和原始查询一起传递给下游 LLM 预处理节点。
SQL 生成的两阶段设计
SQL 生成采用了两阶段架构，也就是现在常说的规划+执行。第一阶段的"SQL 生成预处理"节点会输出结构化的 JSON 分析，包含 query_analysis（意图分析）、data_requirements（数据需求）、required_fields（字段需求）等维度，这实际上是让 LLM 先"想清楚"再"动手"。
第二阶段的核心提示词强调了 PostgreSQL 与 MySQL 语法差异（如双引号 vs 反引号），并内置了跨表日期查询的特殊处理逻辑。比如当识别到"基于企业查询日期"这类表述时，会自动生成子查询模式，通过(SELECT "查询日期" FROM enterprise_info WHERE "企业代码" = 'E1')来获取基准日期，再进行时间范围计算。
SQL 验证节点的多层防护
SQL 验证节点首先进行关键字黑名单扫描，检测 DROP、DELETE、UPDATE 等危险操作和注释符号。接着进行表名白名单验证，只允许 enterprise_info 和 invoice_info 两个预定义表。字段验证环节，不仅检查字段是否存在，还内置了字段映射机制，能自动将'enterprise_code'修正为'企业代码'，'company_name'修正为'企业名称'。如果验证失败，系统会激活修正分支，让另一个专门的 LLM 节点分析错误原因并重新生成 SQL 形成闭环。
HTTP 请求与结果整合的细节处理
Python 动态分析的沙箱化执行
根据数据特征和分析需求，动态生成并安全执行 Python 分析代码。 这个设计的好处就是把复杂计算逻辑从 SQL 层移至 Python 层，提高灵活性的同时，可以支持更复杂的计算或分析，这点类似 Code Interpreter 的设计。
4
工程化实践总结
因为原始项目是在 Coze 上搭建的，在 dify 上复现时碰到了很多环境不一致的坑，这里简单列举 4 个感受下：
4.1
函数参数解析差异
在 sql 验证节点，最开始我是直接复制了 Coze 的代码，其主函数是 def main(args)，期望所有输入都被打包进一个 args 对象。但是碰到了 TypeError: main() got an unexpected keyword argument 'llm_sql'的报错。
测试了下发现，这是因为 Dify 的代码节点执行逻辑更符合传统 Python，它把 UI 上定义的每个输入变量直接映射为函数的同名命名参数 (def main(llm_sql: str, ...)），当然改变函数签名后就自然解决了。
4.2
Dify 的布尔值缺失
同样是 SQL 验证节点，is_valid 字段无法直接设为 True/False，因为输出变量类型中没有 Boolean。这让得用其他类型来“模拟”布尔逻辑。本来是打算换成 1 或 0 显示，但是考虑到可读性的问题，最后采用字符串 "true"/"false" 作为布尔值的代理，并在下游的 IF/ELSE 节点中对这个字符串进行比较。Coze 支持原生布尔值返回，而 Dify 需要开发者适应这种基于字符串的逻辑控制，这算是另一个非常具体的平台差异。
4.3
HTTP 请求的 JSON 引用
SQL 验证通过，在 http 请求节点碰到了 Failed to parse JSON 的报错。硬编码可以，但引用变量就失败。测试下来发现，Dify 的 {{...}} 变量替换是纯文本替换，它不会自动为变量内容中的特殊字符进行 JSON 转义。最后我选择在上游的 Python 节点中，使用 json.dumps() 预先生成一个完全符合 JSON 规范的、已经转义好的字符串，然后在 HTTP 节点中不带任何引号直接引用它。
这个问题在任何需要拼接 JSON 的模板系统中都可能出现，但 Dify 的这种纯文本替换行为是其具体实现。从 Coze 迁移过来，如果习惯了平台会自动处理，就容易在这里踩坑。
4.4
LLM 结构化幻觉
在 LLM 正确的生层了 python 脚本后，我发现 LLM 的输出经常夹带着思考链 ...、Markdown 标记 json ... 等内容，这严重干扰了 Dify 的 JSON 提取器，导致下一个 python 执行节点持续报错。 解决方法也很简单，就是当 LLM 无法稳定输出纯净的 JSON 的时候，强制使用“结构化输出”是不可靠的。 更稳健的方案是放弃 Dify 的“结构化输出”开关。 在提示词中，要求 LLM 将结果用简单、明确的自定义标签（如 ...）包裹起来。然后在下游的 Python 节点中，自己编写一个简单的**解析函数（如正则表达式）**来提取标签内的纯净内容。
这是一个通用的大模型应用工程经验，不分平台。但从一个平台迁移到另一个时，我们需要重新审视新平台提供的“结构化输出”工具的可靠性，并准备好随时切换到手动解析的“防御性编程”模式。
5
优化方向参考
5.1
性能优化
这个案例中演示的工作流，在实际应用的时候，考虑到用户经常会执行相似或重复的查询，实现有效的缓存策略可以显著提高系统响应速度。以语义级缓存为例，不同于传统的精确匹配缓存，这种方法可以很好的识别语义相似的查询，即使它们在表述上有所不同。
例如：查询1："查询北京分行2024年第一季度的不良贷款率"查询2："2024年Q1北京分行的不良贷款比例是多少"
这两个查询在语义上是相同的，但表述不同。语义级缓存可以识别这种相似性，并复用之前的查询结果。
具体实现上，可以先使用向量嵌入技术将自然语言查询转换为向量表示，计算新查询与缓存查询之间的余弦相似度，当相似度超过预设阈值时，再复用缓存结果。
5.2
SQL 生成优化
除了不断丰富知识库、引入 neo4j 适应更复杂的数据库结构等主要迭代方向外，这里介绍个更加具体和实际的工程优化方向，也就是不一次性生成完整 SQL，而是增量生成并验证。实测这种做法对较为复杂的查询成功率和准确率提升也有明显的帮助
具体做法是，先把 SQL 生成分解为多个步骤（如 SELECT 子句、FROM 子句、WHERE 子句等），然后每生成一个部分就进行验证，类似于传统开发流程中的单元测试一样的思路。如果发现错误，只需重新生成错误部分，而不是整个 SQL。
5.3
评估与迭代
为了增加系统的实用性，除了上述提到的优化方向外，还需要同步构建全面的测试套件，覆盖各种查询场景。主要可以考虑以下四个方面：
基本查询测试：覆盖基本的 SQL 操作（SELECT、INSERT、UPDATE、DELETE 等）
复杂查询测试：包含窗口函数、多层嵌套、复杂 JOIN 等
边缘情况测试：处理空值、异常值、大数据量等边缘情况
多轮对话测试：模拟真实的多轮对话场景
可以考虑通过自动化测试的方式，定期运行下测试套件，针对发现的问题进行针对性的调优。需要注意的是，SQL 执行结果的准确性，是最直接的性能指标。把生成的 SQL 在真实数据库上执行，考虑结果的顺序、格式等因素的前提下，比较执行结果和预期结果的一致性。
6
写在最后
构建和维护专门的知识库（如 SQL 模板库、数据库模式知识库、领域术语库等），可以为 Text2SQL 系统提供丰富的上下文信息，这也是当前业界优化 SQL 生成准确性天花板的重要方向之一。
此外，确保测试数据能够代表实际业务场景的查询需求也是一个不小的挑战。很多开源测试数据集（如 Spider、WikiSQL 等）对垂类场景还是无法有效覆盖实际应用中的各种复杂查询。这也和上述的知识库搭建一样，是个在冷启动阶段的 dirty work。
Anyway，基于 RAG 的 Text2SQL 应用是企业 LLM 应用落地的热门方向之一，其他还有很多基于 RAG 底座的任务导向场景目前涌现了些阶段性的最佳实践。我在之前的文章里介绍过了基于 Bad cases 知识库的合同审核工作流，最近在知识星球中有成员问到了合同生成的做法。这部分我下篇来写，欢迎各位蹲一蹲。
