先说明一下这标题一出来懂行的人大概就能感觉到这不是那种“接个大模型让它生成 SQL”的玩具 demo而是在解决一个真正让数据工程师头疼的问题——LLM 写 SQL 非常不稳定同样的问法换个措辞出来的 SQL 可能天差地别一个不存在的表名字段名就能让整段查询直接报废。我在实际项目中测试过 GPT 系列、Claude 和几个国产模型直接生成复杂查询结论很明确从自然语言直接到 SQL 的“一步到位”路线在报表统计、数仓查询这种需要逻辑严密、结果可复现的场景下基本走不通。真正可用的方案是把 LLM 的“创造力”圈养起来让它只负责理解需求、做规划决策而最终 SQL 的生成交给人写的代码——也就是标题里说的编译器逻辑——来做。这篇文章我就围绕“LLM 规划 编译器生成 工作流契约”这套架构把完整的设计思路和落地细节拆开讲清楚适合正在做 Text-to-SQL 系统、想给公司内部搭报表查询助手、或者单纯对大模型工程化感兴趣的朋友参考。1. 问题根源为什么 LLM 直接写 SQL 必然翻车1.1 大模型生成 SQL 的典型事故现场先从最常见的失败案例说起。我让 LLM 直接根据“查一下上个月各区域销售额排名前三的客户”生成 SQL它给出了形如SELECT customer_name, SUM(sales_amount) FROM sales_data WHERE region 华东 GROUP BY customer_name ORDER BY SUM(sales_amount) DESC LIMIT 3的查询——乍看没错但执行后大概率报错因为真实表里根本不存在sales_data这张表实际是ods_sales_order_detail字段也不叫customer_name而是cust_nm。这类问题不是偶发而是 Structure 层面的系统性缺陷。大模型在训练中见过海量相似的 SQL 片段它会“拼接”一段看起来合理的查询但它并不知道你数据库里到底有什么表、什么字段、表与表之间怎么 JOIN。更麻烦的是它还会编造根本不存在的过滤条件比如你只说“近三个月”它能给你加一个deleted_flag 0或者status IN (paid)的限制结果数据直接对不上。这种幻觉在真实业务查询里是最致命的。1.2 根因概率生成与确定性校验的天然矛盾把问题拆到根上大模型本质是一个下一位 Token 的概率预测器。它会根据上下文里的统计规律生成“最像正确答案”的字符串而不是“逻辑上确实正确”的代码。SQL 恰恰是确定性要求极高的领域——表名拼错一个字母就报错聚合逻辑换一个 JOIN 类型结果完全不同。概率模型做创作、写文案没问题但让它直接输出需要精确语义的 DSL相当于让一个擅长散文的人去写法律条文写出来的东西“形似而神不似”。从工程视角来看Text-to-SQL 直接生成还有一个隐性成本输出不可控导致无法做系统的正确性保障。你可以在 Prompt 里塞一堆“请使用正确的表名和字段名”但模型依然可能无视因为它的概率分布里根本没有“查数据库元数据”这一步。同样的问题你换一个日期表达方式它可能就 JOIN 到了另一张错误的时间维度表。这种不确定性让测试、上线、审计全部失去意义——你无法保证同一个问题在两次请求里得到结构一致的结果也就没法通过自动化测试去拦截错误。1.3 主流方案的局限性与新思路的切入点业内常用的几条路线我都试过各有明显短板。第一种是“纯 Prompt 约束”在系统提示里写上“你必须根据数据库 Schema 生成 SQL”配合 few-shot 示例。它的效果只对极简单的单表查询还行一旦涉及多表 JOIN、复杂聚合模型的注意力会漂移照样输出臆造的字段。第二种是“给模型喂 Schema”把数据库全部表结构和字段信息塞进 Prompt。这能减少一部分“编造字段”的问题但包体巨大、推理成本高昂而且当数据库有几千张表时模型根本不知道应该优先看哪张表反而更容易被无关表结构干扰。第三种是“专门微调 Text-to-SQL 模型”。这条路的效果上限更高但需要准备大量的高质量标注 SQL对数据标注团队和迭代周期都是巨大投入中小团队很难持续维护。所以我在多次踩坑后确定了新的切入角度不要试图让 LLM 自己把 SQL 写对而是把所有需要“精确记忆”的片段从 LLM 的工作里剥离出来。LLM 只负责判断用户想问什么、需要哪几张表、用什么聚合方式然后把结果交给一个用传统代码写的编译器模块由它根据预定模板真正生成 SQL。这就是标题里“LLM 规划编译器生成”的由来——让两个系统各干自己擅长的事。2. 整体设计以工作流契约为核心的架构思路2.1 把 SQL 生成拆成“规划”与“编译”两截这套架构最关键的认知是阶段拆分。上游的 LLM 承担“规划”职责理解自然语言输出一个描述执行意图的结构化结果。这个结果不是 SQL而是一个“我想做什么”的语义描述——查哪张业务表、按哪个维度分组、需要什么粒度的时间窗口、做哪种聚合计算。下游的编译器承担“生成”职责拿到这个语义描述对照预先定义好的工作流模板机械地填充变量拼接 SQL。举个例子你就明白了。“上月各区域销售额 Top3 客户”这句话LLM 输出的是这样一个规划片段{ workflow_id: sales_customer_ranking, params: { time_range: [2024-05-01, 2024-05-31], group_dim: region, metric: sales_amount, top_n: 3 } }它没有解释“到底查哪张表”、没有写SUM、没有写ORDER BY只是把用户的自然语言需求翻译成了结构化的参数。然后编译器拿着workflow_id sales_customer_ranking找到对应的预编译模板把参数填进去产出严格的 SQL。整个过程中 LLM 没有机会编造表名和字段名因为它根本没有权限输出那部分内容。这个“分离”是我认为整个系统能稳定落地的核心原因。2.2 工作流即契约给 LLM 划出安全边界那么问题来了编译器怎么知道sales_customer_ranking这个模板的 SQL 长什么样这就需要“工作流契约”的概念。一个工作流契约定义了一类查询的完整形态包括使用的核心基表、占位符参数、默认的聚合逻辑、可选的维度组合。它的本质是“这类查询只能这样做不能有别的写法”。我常打一个比方LLM 不是建筑师而是一个客户它只能从装修公司提供的几种风格套餐里选一个再把预算、房间面积告诉设计师。“现代简约、20 万预算、120 平米”设计图风格是确定的。如果它能自由发挥说“我要客厅贴瓷砖但餐厅用水泥地还要在墙里养鱼”那整个工程就失控了。工作流契约就是“装修套餐清单”规定了有哪些可以选、有哪些不能选、有哪些参数必须填。这样做还有一个额外好处——可审计性。每一次 LLM 调用的输出都要经过契约校验器的检查必须能完整映射到一个已注册的工作流模板上字段名和枚举值也都是白名单内的。如果 LLM 胆敢在参数里塞入一个不存在的字段名校验器直接拒绝而不是让它流入 SQL 执行。这对企业级应用特别重要数据安全审计的要求基本都能达成。2.3 系统分层与核心模块职责我把整个系统按流水线方式分成四层每一层有明确的输入、输出和职责边界也通过统一的“契约格式”串联起来避免层与层之间出现不可控的传参。层级模块职责输入输出意图理解层从自然语言提取业务意图、参数值用户问题标准化的查询意图参数规划决策层基于参数和语义匹配最合适的工作流模板填充参数并做归一化意图参数 工作流注册表结构化 Workflow 实例编译生成层将工作流实例映射为可执行 SQL做引用校验与绑定Workflow 实例 数据库元数据参数化的 SQL 语句校验兜底层语法解析、字段存在性检查、安全规则过滤、兜底重试SQL 语句 元数据白名单可执行的确认 SQL这样的分层设计带来的直接好处是每一层都可以独立测试、独立降级。比如编译层完全不需要 LLM 参与任何一个步骤出问题都知道出在哪一层而不是像之前那样“黑盒生成 SQL”出了问题完全不知道是模型错了还是业务理解错了。3. 工作流契约建模与编译器的核心实现3.1 用 JSON Schema 定义可约束的工作流契约要实现“契约”第一件事就是找到一种既能让代码程序严格校验、又方便 LLM 理解和生成的描述格式。我最终选择了 JSON Schema原因很实在它天生就是一套声明式的结构约束语言能描述哪些字段必填、哪些值只能从枚举列表里选、字符串有多长、数组最多几个元素。这些都直接对上了我需要的“白名单控制”。以一个“销售额汇总”工作流为例契约可以定义成这样{ workflow_id: sales_summary_metric, bind_table: ods_sales_order_detail, params: [ { name: group_dim, type: enum, allowed: [region, channel, product_category, customer_type] }, { name: metric, type: enum, allowed: [sales_amount, order_cnt, refund_amount, profit_amount] }, { name: time_range, type: date_range, required: true } ], joins: [ { target_table: dim_region, condition: ods_sales_order_detail.region_id dim_region.region_id, when_param: group_dim region } ], sql_template: SELECT {group_col}, {metric_expr} FROM ods_sales_order_detail {join_clause} WHERE occur_date BETWEEN {start_date} AND {end_date} GROUP BY {group_col} ORDER BY {metric_expr} DESC }每个参数都定义了严格的类型和取值空间。比如group_dim只能是region、channel、product_category、customer_type中的一个不可能出现 LLM 幻觉一个sales_rep_name进来。这里的sql_template也不是给用户看的最终 SQL而是编译器的“浇筑模具”它把所有可能出错的语法结构固定住能变的只有参数值。在实际搭建中这个 JSON Schema 定义完以后我们还要额外做一件事用程序把 Schema 编译成可供 LLM 读取的压缩描述。因为如果直接把完整 JSON 塞进 PromptToken 消耗会很大。我通常的做法是只把字段名、枚举取值表、表说明传进去让模板结构留在服务端代码里LLM 只需要做“选值”而不是“读 Schema 全文”。3.2 规划器设计让 LLM 只做选择题而不是自由发挥有了契约定义下一步就是设计 LLM 的调用方式。这里有个容易被忽视但很重要的工程决策不要把 LLM 当作一个“文本生成器”而要把它当作一个“结构化信息抽取器”。我的做法是把 Prompt 限制成“根据用户请求从给定枚举值中挑选参数”并要求输出严格合法的 JSON。即使模型偶尔输出一段乱编的文本我也有 JSON 解析层和 Schema 校验层两层护栏。实际 Prompt 长这样你是一个将业务查询翻译为结构化参数的规划器。只输出 JSON不要输出任何解释。 可用的工作流参数定义 - workflow_id: 枚举 [sales_summary_metric, sales_customer_ranking, inventory_snapshot] - group_dim: 枚举 [region, channel, product_category, customer_type] - metric: 枚举 [sales_amount, order_cnt, refund_amount, profit_amount] - time_range: 格式 YYYY-MM-DD~YYYY-MM-DD 用户请求上个月各渠道的退款金额 你的输出配合这一个限定输出格式的 PromptLLM 的“发挥空间”已经被压缩到最小。它要做的只是从枚举里选中合适的值跟做一道选择题没有本质区别。我还引入了一个策略如果有两个候选工作流都能满足请求规划器必须在输出中标注每个候选的参数匹配度评分再由规则层决定选哪个而不是让模型直接“拍板”。这一步进一步减少模型的主观臆断把决策权还给人写的代码。3.3 编译器实现模板匹配、参数绑定与防注入调度层拿到 LLM 输出的规划实例后会把它传给编译器模块。编译器核心函数要做的事情非常机械根据workflow_id找到模板把 JSON 参数里的值绑定到模板占位符同时做三件重要的校验。第一是字段白名单校验编译器会查数据库元数据缓存确认模板里引用的每一列都真实存在避免模板本身在迭代中发生过期修改。第二是类型绑定校验比如时间范围参数必须符合约定的YYYY-MM-DD格式数值参数必须能被转成整数或浮点避免把字符串拼进 SQL 的数值比较里。第三是防注入审查因为所有值都可能来自用户原始输入即便是 LLM 抽取出来的也绝不能直接拼进 SQL 字符串。编译器的所有参数绑定都必须走参数化查询接口即使是用模板拼接也只会用预处理变量的形式传值。核心的编译器代码用 Python 组织的话逻辑可以很简洁def compile_workflow(wf_instance: dict, meta_cache: dict) - str: wf_id wf_instance[workflow_id] contract load_workflow_contract(wf_id) # 1. 校验所有传入参数都在契约声明的 allowed 枚举内 for param in contract[params]: if not is_valid_param(param, wf_instance): raise ContractViolation(fparam {param[name]} not allowed) # 2. 校验引用的表字段真实存在 for table, column in extract_table_column_refs(contract): if not meta_cache.column_exists(table, column): raise SchemaViolation(fcolumn {table}.{column} missing) # 3. 渲染模板但值替换必须用参数占位符禁止直接拼接 sql_fragments [] sql_fragments.append(render_template(contract[sql_template], wf_instance, safeTrue)) # 4. 对最终 SQL 做一次语法树解析确保没有注入语法 ast parse_sql(sql_fragments[0]) if not ast.is_valid(): raise SyntaxViolation(invalid sql generated) return build_parameterized_sql(ast, wf_instance[params])这里第四步的“语法树解析”很多人会忽略。我强烈建议不要只看字符串是否包含SELECT等关键词这种做法太浅了。你是要真实地解析 SQL 的抽象语法树看它有没有多出不属于模板的自由片段。我一般直接用 sqlglot 这类库做解析它不仅能把 SQL 解析成 AST还能做方言转换对后续支持不同数据库也特别方便。3.4 确定性保障三层校验与结果一致性绑定很多人看到这里会问你说这套方案确定性很高那到底高到什么程度我把我自己实践下来总结的“确定性保证三层次”列一下。第一层是结构确定性。同一类查询从同一个工作流模板编译出来的 SQL结构是完全一致的只有参数值在变。这保证了你对某张报表做性能调优的效果可以复用到所有同类查询上也保证了 SQL 审阅时的模式稳定。第二层是语义确定性。每次执行前系统都会把“用户原始问题”和“编译后的 SQL”一起吃进一个校验器通过轻量模型判断 SQL 的过滤条件、分组维度是否覆盖了用户请求里的核心语义要素。如果覆盖不齐就直接拦截重试。第三层是结果可复现性。因为启用了参数化查询同一个工作流实例 同一组参数生成的结果必然一致这是可复现实验和自动化测试的基础。实际项目中这三层分别对应了三个独立的测试套件模板结构测试、语义覆盖测试、结果一致性对比测试。每次工作流模板修改后跑完三套测试才能上生产。这其实就是把软件工程里的“契约测试”思想平移到了大模型应用里。4. 实操过程从零搭建一套可用的生成器4.1 环境选型与技术栈建议先说清楚我实践时的技术栈选择给想复现的读者一个基准配置。LLM 部分我建议优先选择支持 JSON Output Mode 的模型比如带函数调用能力或结构化输出的服务这样规划器拿到合法 JSON 的概率会大幅提升。在不具备结构化输出能力的私有化部署场景里就用我前面说的“外置 JSON 解析 Schema 校验”兜底实战下来也能接受。编译器部分强烈推荐 Python 3.10配合 sqlglot 库做 SQL 的 AST 解析和方言转换。工作流注册表用最简单的 JSON 文件存储在 Git 仓库里就能起步每个模板一个文件代码和配置分开管理走标准 Review 流程。数据库元数据缓存建议用 Redis 或是 Python 的字典缓存先顶住等到规模大了再换专门的库表结构存储。整个系统的核心依赖其实非常轻不需要引入重型框架这也是我这套方案能快速落地的一个重要原因。4.2 第一步编写第一版工作流契约实操时千万不要一上来就写很多模板我的经验是先挑 3 到 5 个高频查询场景把它们的工作流契约完整定义出来跑通链路后再扩展。我以“销售客户 TopN”和“库存快照”两个场景说明。工作流契约 JSON 文件存在workflows/目录下命名规则是workflow_id.json内容字段保持和前文一致的风格重点要把sql_template写得足够“粗颗粒度”即所有可变的业务判断都映射到参数上而不是在模板内部写死分支逻辑。比如“库存快照”模板的 SQL 长这样SELECT warehouse_code, product_sku, current_stock_qty, safety_stock_qty FROM dwd_inventory_snapshot WHERE snapshot_date {snapshot_date} AND warehouse_code IN ({warehouse_list})那么契约里的warehouse_list就必须是一个数组参数由编译器负责展开成参数化列表而不是让 LLM 去写WH001,WH002这种拼接。这一步做到位后面防注入就省心了。4.3 第二步规划器 Prompt 与结构化输出实现规划器的具体实现我建议写成一个独立的调用函数不要和业务代码混在一起。输入是用户的问题输出是校验后的规划 JSON。在实现时我会给模型两个关键信号一是用户问题本身二是当前可用的工作流参数定义。这里有个细节容易踩坑工作流定义往往很长尤其字段说明多时 Token 消耗会急剧上升。我的优化方案是把参数定义压缩成精简枚举表每个参数用一行文本描述。比如可用 group_dimregion区域, channel渠道, product_category产品分类, customer_type客户类型这样既能让模型理解每个枚举值的业务含义又不会占用太多上下文长度。实测下来同样的任务定义压到 60 个 Token 以内后模型的选择准确率反而提升了因为注意力更集中。通过这种方式规划器每次调用的 Token 数可以压得非常低成本可控。4.4 第三步编译器函数与元数据缓存的落地编译器的实现我会在项目里单独开一个sql_compiler.py模块并引入数据库元数据缓存模块。元数据缓存很关键因为校验“字段是否存在”如果每次都实时查数据库的information_schema在高并发下会有不小的压力。实际落地时我建议在服务启动时构建一次表结构映射包括表名、字段名、字段类型、主外键关系然后按天或者按需增量刷新。这个元数据缓存本身也是 LLM 规划器的好帮手。在为 LLM 构建 Prompt 时可以直接从缓存里把工作流涉及的字段名和描述提取出来确保模型看到的枚举列表跟编译器用的校验列表是同一份数据。单一数据源避免了很多两边不一致带来的诡异 bug。4.5 第四步校验层与失败重试机制校验层我放在编译器之后、SQL 执行之前。除了 AST 解析检查外我还会加一道业务规则检查器。比如审计要求不允许一次性查询超过 90 天的明细数据那么校验层就会在time_range上做天数限制超过就直接报错拒绝不让 SQL 进入执行引擎。这类业务规则不进 Prompt而是硬编码在校验代码里保证不会被模型绕过。失败重试机制也要设计好。如果规划器输出无法通过 Schema 校验我采取的策略是“最多重试两次”。第一次重试把校验失败的原始报错信息一起拼给 LLM让它在已有答案基础上修正而不是重新问一遍第二次重试还失败就走人工兜底直接告诉用户“无法理解查询需求”。这样做的好处是避免模型在错误方向上反复生成浪费推理成本也让线上体验更可控。5. 踩坑记录与常见问题速查5.1 规划器总把参数选歪怎么办我遇到最典型的问题是group_dim的选择不正确。比如用户问“北京和上海的销售对比”模型把channel选成了分组维度而正确的应该是region。这一般是因为 Prompt 里对枚举值的业务语义写得不够明确。我的解法是把每个枚举值补充一个“识别特征”的描述比如region按地区维度聚合常用于地域对比channel按渠道维度聚合常用于线上/线下对比。模型看到这种提示后选择准确率能从 75% 提升到 93% 左右效果很明显。而且我建议在规划器后面连接一个“规则修正器”用逻辑代码处理一些模型不太擅长的歧义判断。比如当用户同时提到两个及以上地域名时规则修正器可以自动把group_dim改为region而不用依赖模型每次都猜对。这类确定性规则可以越来越多地替代模型的不确定判断。5.2 工作流模板数量太多维护不过来怎么办系统用久以后每个业务方都会提出要“单独定制一个查询场景”工作流模板数量可能膨胀到上百个。模板越多相互之间的边界就越模糊同一个查询能匹配到好几个模板规划器会犯选择困难症。我的应对思路是建立模板分组和优先级机制。同类型的模板比如所有销售相关的划分到同一个“域”下规划器先选域再选域内的模板缩小选择范围。同时要定期合并重复模板比如“按区域销售额”和“按区域利润额”本质上结构相同只是metric参数变化那完全可以归并成一个工作流由参数控制计算列。我在实践里用这种合并把模板数量缩减了将近 40%维护成本显著下降编译器渲染效率也更高。这一条真的建议所有想长期维护这套系统的团队都去执行。5.3 生成速度慢、成本偏高如何优化整套链路走完的耗时大头基本在 LLM 调用上特别是规划器要读取工作流参数定义时上下文越长速度越慢。我的优化重点是把 Prompt 压缩和缓存手段都用上。首先是定义合理的工作流上下文长度只用最少的枚举说明不要动不动把整份 JSON Schema 塞进 Prompt。其次是引入语义缓存对用户提问先做意图哈希如果命中相同问题直接返回历史编译结果不走 LLM。实测这类系统的缓存命中率往往能到 35% 以上因为它服务的是固定业务人群问题模式相对集中节省的成本非常可观。另外还有一个小技巧把“参数抽取”和“模板匹配”拆成两次轻量调用而不是一次重型调用。第一次调用只识别时间、地域、指标类型等核心要素第二次调用再根据要素匹配工作流。分开调用后单次 Prompt 更短、错误更容易定位综合算下来总成本反而更低因为单次失败重试的概率大幅下降了。5.4 常见错误码与排查步骤速查表我把实际操作中积累的常见错误和排查思路整理成一个速查表方便大家在项目里直接对照。故障现象可能原因排查思路LLM 输出的 JSON 无法被解析模型未遵循输出格式启用结构化输出模式检查 Prompt 里是否混入了无关示例Schema 校验报“字段不存在”元数据缓存过期刷新元数据缓存检查契约里的字段名是否与库表实际命名一致SQL 语法树校验不通过模板拼接时破坏了语法用 sqlglot 单独解析模板片段检查引号和转义字符同一问题频繁命中不同模板模板边界重叠合并同类模板增加域间优先级规则参数包含无需注入的字符串防注入规则未完全覆盖检查所有值是否都走参数化绑定杜绝直接字符串拼接规划器上下文长度超限工作流参数定义太全压缩为枚举简版描述删掉模板结构只留字段含义执行结果与业务预期不符JOIN 条件和过滤逻辑有误对比工作流模板的 SQL 与用户原始需求重点检查 WHERE 条件覆盖6. 进阶扩展这套架构还能往哪些方向走路径已经跑通之后可以明显看到这套“LLM 规划 编译器生成”的架构并不只适用于 SQL 一种场景。只要目标语言有严格的语法约束和有限的模式空间理论上都可以复制这套思路。比如数据分析平台里常用的可视化仪表板配置可以把workflow_id换成“图表类型”让 LLM 只输出数据字段和聚合方式再由编译器把字段映射成可视化的查询配置再比如物联网领域的规则引擎配置同样可以用契约约束每个条件的枚举值避免模型生成非法的条件表达式。在 SQL 这个具体应用上下一步很自然的演进方向是把“用户提问历史”记入反馈回路。用户最终查看了哪些查询结果、对哪条 SQL 结果点了赞或直接重新表述了问题都可以作为模板启发式的输入提升规划器后续选模板的命中率。另外多轮对话里“修改上一轮查询”的需求也很值得做——比如用户说“把时间改成上季度”这时可以复用上一次的工作流实例只做参数重规划而不必重新走一遍全流程。这会显著提升交互体验也是契约化架构天然支持的能力。我个人更看好的扩展方向是“跨方言编译”。因为编译器生成 SQL 时用的是中间表示理论上可以用一套工作流契约编译输出适用于 MySQL、PostgreSQL、ClickHouse 不同方言的 SQL。sqlglot 这类库已经提供了很好的方言转换能力只需要按目标库把模板和执行层做分层处理就能一套业务逻辑适配多种数据底座这对很多有多套异构数据源的团队来说价值很大。最后回到开头那个问题直接让 LLM 写 SQL 到底能不能用我的答案是让它做“思想家”别让它做“打字员”。把理解、规划交给大模型把精确、机械的翻译交给编译器用工作流契约把二者缝合起来——这是我现在面对所有“生成式代码”类需求时优先考虑的工程框架实测下来是稳定性和性价比之间最好的平衡。
