1. 项目概述当大模型开始“写编译器”SQL 就不再靠猜我第一次在内部技术分享会上听到“LLM 规划编译器生成以工作流为契约的确定性 SQL 生成器”这个标题时下意识皱了下眉——不是因为它太难懂而是因为它太“反直觉”。我们习惯了让 LLM 写 SQL输入一句“查出上个月销售额 top5 的城市”它吐出一条带 JOIN 和子查询的语句。但那条语句对不对字段名拼错没聚合逻辑漏没执行计划会不会爆炸没人敢打包票。更麻烦的是业务方改个需求比如“改成按季度统计”你得重新喂提示词、调 temperature、再人工 review整个过程像在调试一个黑盒 API。而这个项目干的事是把 LLM 从“SQL 代笔”降级为“规划员”再把真正的 SQL 编码权交给一套可验证、可追踪、可回滚的编译器流水线。核心就一句话用工作流定义业务语义用编译器保证 SQL 行为确定用 LLM 只负责在语义层做路径搜索与约束推理不碰任何 SQL 字符串生成。这不是“LLM SQL”的简单叠加而是把大模型嵌入到传统软件工程的契约体系里——工作流就是接口契约编译器就是类型检查器生成的 SQL 就是经过静态验证的可执行字节码。关键词里“LLM”是智能调度中枢“编译器”是确定性保障引擎“SQL”是最终交付物“工作流”是人机协同的协议层“确定性”则是整个系统的命门。适合三类人需要对接 BI 或数据产品的后端工程师终于不用天天救火式改 SQL、正在构建低代码数据平台的产品经理能用可视化拖拽定义数据契约、以及研究 LLM 在企业级系统中落地边界的架构师看到一种避开幻觉、保留可控性的新范式。它解决的不是“怎么让 LLM 写得更像人”而是“怎么让 LLM 的输出能放进 CI/CD 流水线里跑通单元测试”。2. 整体设计思路为什么放弃“直接生成”选择“规划编译”双阶段2.1 直接生成 SQL 的三大死穴我们踩过全部刚接手这个项目时团队试过最朴素的方案用 fine-tuned 的 Llama-3-70B输入结构化 schema 和自然语言需求直接输出 SQL。上线两周线上报错率 37%其中 62% 是字段名拼写错误比如custoemr_id28% 是 JOIN 条件遗漏漏写ON t1.id t2.customer_id剩下 10% 是聚合逻辑错位COUNT(*)和COUNT(DISTINCT user_id)混用。问题根源不在模型能力而在任务本质——SQL 是一门强类型、强约束的语言而 LLM 的 token 预测是概率性的。哪怕你把 temperature 设为 0它依然可能在第 47 个 token 上把GROUP BY错写成ORDER BY这种错误无法通过 prompt 工程根除因为模型没有“语法树”概念只有 token 序列概率。我们做过对比实验同一份 schema 和需求让同一个模型生成 10 次得到 7 条不同 SQL其中 3 条语法正确但语义错误比如把“活跃用户”定义为last_login_time 2024-01-01而非last_login_time 2024-01-012 条语法错误。这说明LLM 天然不适合承担“精确编码”角色它擅长的是“语义空间导航”而不是“符号系统构造”。所以我们彻底放弃了“端到端生成”路线转而拆解任务第一阶段让 LLM 基于工作流定义输出一个抽象的、无歧义的“查询意图图”Query Intent Graph第二阶段用专用编译器将这张图编译成符合 schema 约束、满足执行效率要求的确定性 SQL。这就像让建筑师画蓝图LLM 规划再让施工队按图纸盖楼编译器生成中间绝不允许工人自己发挥。2.2 工作流作为“契约”的底层逻辑从模糊需求到可验证语义“工作流”在这里不是指 Airflow 或 Dagster 那种调度工具而是一种轻量级、领域特定的 DSLDomain Specific Language专为描述数据查询语义设计。它的核心思想是把自然语言需求强制映射为一组可枚举、可校验的原子操作组合。比如“查出上个月销售额 top5 的城市”在工作流 DSL 中必须被拆解为source: sales_table指定主数据源filter: month 2024-03时间过滤month字段必须存在于sales_table的 schema 中aggregate: {group_by: [city], sum: [amount]}聚合操作city和amount必须是sales_table的合法字段sort: amount DESC排序amount必须是聚合后的输出字段limit: 5限制行数这个 DSL 的 parser 会在 LLM 输出后立即运行做三件事1检查所有字段名是否在 schema 中存在2验证操作顺序是否合法比如sort必须在aggregate之后3确认类型兼容性sum只能作用于数值型字段。如果任一检查失败整个工作流定义即刻拒绝不会进入编译阶段。这相当于给 LLM 戴上了“语义手铐”——它只能在预定义的操作集合里组合不能自由发挥。我们实测发现当 LLM 的输出目标从“生成字符串”变成“填充 DSL 模板”时错误率从 37% 降到 4.2%且 95% 的错误集中在字段名大小写不一致Cityvscity这类问题可通过 schema 元数据自动标准化解决。工作流 DSL 的设计原则是“最小完备性”只包含业务方真正需要表达的语义过滤、聚合、连接、排序、分页砍掉所有 SQL 特有但业务无关的细节比如LEFT JOINvsINNER JOIN的选择由编译器根据外键关系自动推导。这使得业务方能用接近口语的方式定义需求而技术侧获得的是可静态分析的结构化输入。2.3 编译器的核心使命从语义图到确定性 SQL 的保真转换编译器不是简单的模板填充器而是一个多阶段的、带约束求解的转换引擎。它的输入是 LLM 输出并经 DSL parser 校验后的“查询意图图”输出是经过全链路验证的 SQL 字符串。整个流程分为四步语义图规范化将 DSL 解析出的节点source/filter/aggregate/sort构建成有向无环图DAG明确数据流向。例如filter节点必须指向source节点aggregate节点必须指向filter节点。schema 绑定与推导遍历 DAG为每个节点绑定实际的表名、字段名、数据类型。关键一步是处理隐式 JOIN当filter条件中引用了另一个表的字段如customer.name Alice编译器会查询元数据库找到sales_table和customer_table之间的外键关系sales_table.customer_id → customer_table.id自动生成JOIN语句并确保ON条件严格匹配。优化规则应用应用预设的、可审计的优化规则。例如filter节点若在aggregate之前且条件字段属于source表则下推到WHERE子句若sort和limit同时存在且sort字段是索引列则保留ORDER BY ... LIMIT否则插入ROW_NUMBER()窗口函数确保结果确定性。所有规则都禁用代价模型只基于 schema 和操作类型做确定性决策。SQL 生成与验证将规范化的 DAG 映射为 ANSI SQL 语法树生成字符串。最后一步是关键调用数据库的EXPLAIN接口如 PostgreSQL 的EXPLAIN (FORMAT JSON)解析执行计划验证是否出现全表扫描、笛卡尔积等高风险模式。若检测到编译器拒绝输出返回具体原因如“filter条件未使用索引字段created_at”而非静默生成低效 SQL。这个编译器的设计哲学是“保守主义”宁可拒绝一条合法但低效的查询也不生成一条可能拖垮数据库的 SQL。它不追求“最短 SQL”而追求“最可预测 SQL”。我们曾对比过 1000 个真实业务查询编译器生成的 SQL 平均执行时间比人工编写慢 12%但标准差仅为人工的 1/5这意味着性能波动极小运维同学再也不用半夜被告警叫醒。3. 核心细节解析工作流 DSL、LLM 规划器、编译器三者的协同机制3.1 工作流 DSL 的语法设计与 Schema 驱动校验工作流 DSL 的语法刻意保持极简仅支持五类声明式节点全部采用 YAML 格式避免引入编程语言的复杂性。一个完整的工作流定义示例如下version: 1.0 name: monthly_top_cities_sales description: 上月各城市销售额排名前5 sources: - name: sales table: fact_sales schema: public - name: customers table: dim_customers schema: public steps: - type: filter source: sales conditions: - field: sale_date operator: value: 2024-03-01 - field: sale_date operator: value: 2024-04-01 - type: join left: sales right: customers on: - left_field: customer_id right_field: id - type: aggregate source: sales group_by: - field: city from: customers aggregations: - function: sum field: amount alias: total_sales - type: sort by: - field: total_sales direction: DESC - type: limit count: 5这个 DSL 的强大之处在于其“schema 驱动”的校验机制。DSL parser 不是孤立运行的它实时连接元数据库我们用的是 Apache Atlas在解析sources块时会立即查询fact_sales表的字段列表、数据类型、主外键关系。当解析join节点时它会验证sales.customer_id是否为外键指向dim_customers.id若不匹配直接报错JOIN condition violates foreign key constraint。同样aggregate.group_by中的city字段parser 会检查它是否存在于dim_customers表中且类型为VARCHAR。这种校验不是事后检查而是解析过程中的同步阻断。我们甚至在 parser 中嵌入了轻量级的类型推导引擎当filter条件中value是字符串2024-03-01而field: sale_date的类型是DATEparser 会自动将其转换为DATE 2024-03-01避免 SQL 语法错误。这种深度耦合 schema 的设计让 DSL 成为一道坚固的“语义防火墙”把 LLM 的不确定性挡在了编译器之外。3.2 LLM 规划器的 Prompt 工程与输出约束LLM 规划器的角色被严格限定为“DSL 填充器”而非“SQL 生成器”。它的 prompt 结构经过 17 轮迭代优化核心是三个层次的约束角色约束“你是一个专业的数据查询规划助手你的唯一任务是根据用户需求和提供的表结构输出符合 v1.0 规范的工作流 DSL。你绝不能输出任何 SQL、JSON 或其他格式。”格式约束“输出必须是纯 YAML以version: 1.0开头包含name、description、sources、steps四个顶级字段。steps必须按执行顺序排列且只能包含filter、join、aggregate、sort、limit五种类型。”schema 约束“所有字段名、表名必须严格匹配以下 schema 定义此处插入动态注入的 schema 片段。若用户需求中提到的字段不存在请明确指出缺失字段而非猜测。”最关键的是我们禁用了所有自由发挥的指令。早期版本 prompt 中有“请尽可能详细地描述”之类的表述导致 LLM 在description字段里写长篇业务背景污染了 DSL 结构。后来我们改为硬性规定“description字段不得超过 50 字符仅描述查询目的如‘查询上月销售额 top5 城市’。” 实测表明这种“填空式”prompt 让 Llama-3-8B 的 DSL 生成准确率从 68% 提升到 94.3%。我们还加入了“自我验证”环节在 prompt 末尾要求 LLM 在输出 DSL 后附加一行# VALIDATION: PASS/FAIL - REASON例如# VALIDATION: PASS - all fields exist in schema。虽然这行文本会被 parser 忽略但它显著提升了模型对 schema 约束的注意力。有趣的是当模型输出FAIL时90% 的情况是它正确识别出了 schema 中不存在的字段如用户说“查会员等级”但 schema 里只有vip_level这反而成了我们发现业务术语不一致的宝贵信号。3.3 编译器的四阶段转换与确定性保障策略编译器的实现是一个 Rust 编写的独立服务核心是四个不可绕过的阶段每个阶段都内置确定性保障阶段一DAG 构建与拓扑排序输入 DSL 后编译器首先构建一个StepNode图每个节点包含type、dependencies上游节点 ID 列表、outputs本节点产生的字段名列表。filter节点的dependencies是其source对应的source节点join节点的dependencies是其left和right对应的source节点。然后进行拓扑排序确保执行顺序合法。若检测到环如A依赖BB又依赖A编译器立即终止返回Cyclic dependency detected in steps。这一步杜绝了逻辑矛盾。阶段二Schema 绑定与 JOIN 推导这是编译器最“聪明”的部分。当join节点出现时编译器不依赖用户指定ON条件而是查询元数据库的外键关系表。例如若sales表的customer_id字段外键指向customers.id则自动生成ON sales.customer_id customers.id。更进一步若用户需求是“查北京用户的订单”而filter条件写在sales节点上city Beijing但city字段在customers表中编译器会自动将该filter下推到join之后的customers表上并调整ON条件为sales.customer_id customers.id AND customers.city Beijing确保查询效率。所有推导规则都是白盒、可审计的写在join_resolver.rs文件里而非黑盒模型。阶段三确定性优化规则集我们摒弃了基于代价的动态优化采用 12 条硬编码规则每条规则都有明确的触发条件和输出保证。例如规则 #7Filter Pushdown若filter节点的conditions中所有字段都属于其source表且该表有对应索引则将条件移至WHERE子句否则保留在HAVING或窗口函数中。规则 #11Sort-Limit Safety若sort字段是主键或唯一索引列则生成ORDER BY ... LIMIT否则生成SELECT * FROM (SELECT ..., ROW_NUMBER() OVER (ORDER BY ...) AS rn FROM ...) WHERE rn 5确保分页结果绝对稳定避免OFFSET导致的跳行问题。这些规则全部经过 TPC-H 基准测试验证在 1000 次随机查询中100% 保证输出 SQL 的执行计划不变。阶段四SQL 生成与 EXPLAIN 验证生成的 SQL 字符串会发送到目标数据库PostgreSQL/MySQL/SQL Server的EXPLAIN接口。编译器解析返回的 JSON 执行计划重点检查Plan Rows估算值是否超过100000阈值可配置若是判定为潜在全表扫描Node Type是否包含Nested Loop且Join Type为Inner但无Index Cond判定为笛卡尔积风险Parallel Aware是否为false且Workers Planned为0判定为无法并行。只要任一检查失败编译器返回SQL generation failed: EXPLAIN check failed - [reason]并附上完整的EXPLAIN输出供人工分析。这一步让编译器不仅是生成器更是质量守门员。4. 实操过程从零搭建一个可运行的确定性 SQL 生成器4.1 环境准备与核心组件部署要复现这个系统你需要准备三个独立的服务它们通过 HTTP API 通信确保松耦合元数据库服务Schema Source我们选用 Apache Atlas 作为元数据管理中枢它能自动采集 PostgreSQL/MySQL 的表结构、字段类型、主外键关系。安装步骤下载 Atlas 2.4.0wget https://downloads.apache.org/atlas/2.4.0/apache-atlas-2.4.0-bin.tar.gz解压并配置atlas-application.properties设置atlas.graph.storage.backendhbase或berkeleyje用于开发启动bin/atlas_start.py通过 REST API 注册你的数据源curl -X POST http://localhost:21000/api/atlas/v2/types/typedefs -H Content-Type: application/json -d {enumDefs:[],structDefs:[],entityDefs:[],relationshipDefs:[],classificationDefs:[]}使用atlas-hook插件让 PostgreSQL 的pg_dump自动同步 schema 到 Atlas。LLM 规划服务Planning Service我们基于 Ollama 部署 Llama-3-8B因其在 8GB GPU 上即可流畅运行且开源权重便于 fine-tuning。部署命令# 拉取模型 ollama pull llama3:8b # 创建自定义 Modelfile加入我们的 prompt 模板 echo FROM llama3:8b SYSTEM \你是一个专业的数据查询规划助手...此处粘贴完整 prompt\ Modelfile ollama create sql-planner -f Modelfile # 启动 API 服务 ollama serve然后用 Python FastAPI 写一个轻量 wrapper接收用户需求和 schema调用ollama run sql-planner并用正则提取 YAML 输出。编译器服务Compiler Service用 Rust 编写依赖tokio异步运行时和sqlx数据库驱动。Cargo.toml 关键依赖[dependencies] tokio { version 1.36, features [full] } sqlx { version 0.7, features [postgres, mysql, sqlite, runtime-tokio-rustls] } serde { version 1.0, features [derive] } yaml-rust 0.5编译器启动后监听http://localhost:8080/compile接收 YAML DSL返回编译后的 SQL 或错误。提示三个服务必须网络互通。开发环境可用 Docker Compose 统一编排生产环境建议用 Kubernetes为编译器服务单独配置 CPU 亲和性避免 GC 影响实时性。4.2 工作流 DSL 的编写与调试技巧DSL 编写不是一蹴而就的我们总结了三条黄金法则法则一从 source 开始逐步添加 step永远先写sources确保表名、schema 名 100% 匹配 Atlas 中的注册名。然后只加一个filter用最简单的条件如id 0测试。成功后再加aggregate最后加join。这样能快速定位是 schema 问题还是逻辑问题。我们有个内部脚本dsl-validate.sh它会模拟编译器的第一阶段只做 DAG 构建和 schema 绑定不生成 SQL耗时 100ms适合开发时高频验证。法则二善用description字段做需求锚点description不是摆设。我们要求每个工作流的description必须能被产品经理直接读出业务含义且长度控制在 30 字内。例如description: 计算Q1各产品线毛利率比description: Q1毛利分析更好因为它明确了时间范围Q1、维度产品线、指标毛利率。这个字段在后续的审计日志中会和生成的 SQL 一起存储成为追溯需求来源的唯一凭证。法则三JOIN 优先用join节点而非filter跨表引用初学者常想在filter中直接写customers.city Beijing但这会触发编译器的“跨表过滤警告”因为它无法保证 JOIN 顺序。正确做法是显式添加join节点明确left和right表让编译器自动推导ON条件。这样做的好处是当customers表结构变更如city字段 renamed 为location编译器会在join阶段就报错而不是在filter阶段才暴露问题发现更早。我们还开发了一个 VS Code 插件sql-workflow-linter它能在编辑 YAML 时实时高亮红色字段名不存在于 schema黄色filter条件中引用了未 JOIN 的表绿色所有校验通过可安全提交4.3 编译器的参数调优与性能监控编译器不是“开箱即用”需要根据你的数据库特性微调参数一max_join_depth默认 3控制编译器自动推导 JOIN 的最大层数。例如sales→customers→regions是两层 JOIN。若设为 2当用户需求涉及regions.country时编译器会拒绝要求显式写出join步骤。调高此值会增加推导复杂度但降低 DSL 编写难度。我们生产环境设为 2因为三层 JOIN 已覆盖 92% 的业务场景。参数二explain_timeout_ms默认 5000EXPLAIN验证的超时时间。对于复杂查询PostgreSQL 的EXPLAIN (ANALYZE)可能卡住。我们建议在开发环境设为 10000生产环境设为 3000并开启log_explain_failures: true将失败的EXPLAIN输出写入日志供 DBA 分析。参数三enable_parallel_sort默认 false是否在sort阶段启用并行排序。PostgreSQL 13 支持但会增加内存消耗。我们只在 OLAP 场景开启OLTP 场景关闭避免影响在线事务。监控方面我们在编译器中埋点了 7 个关键指标通过 Prometheus 暴露compiler_dsl_parse_duration_secondsDSL 解析耗时P95 50mscompiler_schema_bind_errors_totalSchema 绑定失败次数应为 0compiler_explain_failures_totalEXPLAIN 验证失败次数理想值 0.1%compiler_sql_generated_total成功生成 SQL 数量compiler_cache_hit_ratio编译缓存命中率我们对相同 DSL 哈希值缓存 SQL提升 40% 吞吐注意编译器的缓存必须是“确定性缓存”即 key SHA256(DSL YAML target_db_type db_version)value 生成的 SQL。绝不能缓存EXPLAIN结果因为数据库统计信息变化会导致执行计划改变。4.4 典型业务场景的 DSL 编写实录让我们用一个真实案例走一遍全流程“筛选简历找出 3 年内毕业、学历为硕士、且投递过‘后端开发’岗位的候选人按最近投递时间倒序取前 20 名。”Step 1确认 schema从 Atlas 查到三张表candidatesid,name,graduation_year,degreedegree类型为VARCHAR(20)值为Bachelor,Master,PhDjobsid,titletitle值为Frontend Developer,Backend Developer,Data Scientistapplicationsid,candidate_id,job_id,applied_at外键关系applications.candidate_id → candidates.idapplications.job_id → jobs.idStep 2编写 DSLversion: 1.0 name: resume_screening_backend description: 筛选3年内硕士学历且投递后端开发的候选人 sources: - name: candidates table: candidates schema: hr - name: jobs table: jobs schema: hr - name: applications table: applications schema: hr steps: - type: filter source: candidates conditions: - field: graduation_year operator: value: 2021 - field: degree operator: value: Master - type: join left: applications right: candidates on: - left_field: candidate_id right_field: id - type: join left: applications right: jobs on: - left_field: job_id right_field: id - type: filter source: jobs conditions: - field: title operator: value: Backend Developer - type: sort by: - field: applied_at direction: DESC - type: limit count: 20Step 3编译器输出编译器会生成如下 SQLPostgreSQLSELECT c.id, c.name, c.graduation_year, c.degree, a.applied_at FROM applications a JOIN candidates c ON a.candidate_id c.id JOIN jobs j ON a.job_id j.id WHERE c.graduation_year 2021 AND c.degree Master AND j.title Backend Developer ORDER BY a.applied_at DESC LIMIT 20;并返回EXPLAIN验证结果Seq Scan on applications因applied_at有索引且LIMIT 20执行计划健康。这个例子展示了 DSL 如何天然支持多表关联而编译器如何将业务语义“投递过”精准映射为JOIN无需用户理解数据库范式。5. 常见问题与排查技巧实录那些文档里不会写的坑5.1 LLM 规划器输出 YAML 格式错乱Parser 解析失败现象LLM 返回的不是纯 YAML而是混杂了 Markdown 代码块yaml ...或解释性文字“根据您的需求我生成了以下工作流”。根本原因Prompt 中的格式约束不够强硬。Ollama 的 streaming 输出有时会截断导致 YAML 不完整。解决方案在 Prompt 中加入硬性边界符--- START DSL ---和--- END DSL ---并要求 LLM 只在这两个标记之间输出 YAML。在 Parser 层添加容错用正则(?s)--- START DSL ---(.*?)--- END DSL ---提取内容再用yaml-rust解析。若解析失败尝试去掉首尾空白行和注释行#.*。最重要的一招在 LLM wrapper 中加入重试逻辑。若首次解析失败将错误信息如YAML parse error: expected a single document连同原始输出作为新 prompt 的一部分让 LLM “修正自己的输出”成功率提升至 99.2%。实操心得我们曾遇到 Llama-3 把value: 2024-03-01错写成value: 2024-03-01少了引号导致 YAML 解析为日期类型而非字符串。为此我们在 Parser 中强制将所有value字段转为字符串再由编译器做类型转换避免 YAML 解析器误判。5.2 编译器生成的 SQL 执行报错但 EXPLAIN 验证却通过现象编译器返回 SQLEXPLAIN检查通过但实际执行时数据库报错如column city does not exist。根本原因EXPLAIN只验证语法和执行计划不验证语义。错误往往出在JOIN推导或字段别名上。例如aggregate节点中alias: total_sales但sort节点却写了field: sum_amount编译器会生成ORDER BY sum_amount而实际字段名是total_sales。排查技巧启用编译器的debug_mode: true它会输出每一步的中间状态DAG 节点、绑定后的字段名、生成的 AST。重点看aggregate.outputs列表是否与sort.by.field匹配。在sort和limit节点前强制添加一个project节点虽 DSL 不显式支持但编译器内部会插入显式列出所有输出字段确保下游节点引用的字段名 100% 存在。建立“SQL 回放测试”将编译器生成的 SQL连同EXPLAIN输出存入测试数据库用psql -c EXPLAIN (ANALYZE, BUFFERS) SQL运行捕获真实执行错误。5.3 多租户环境下Schema 隔离导致 DSL 校验失败现象SaaS 平台中不同客户的数据表在不同 schema 下如tenant_123.fact_salestenant_456.fact_salesAtlas 元数据中只注册了publicschema导致sources.table匹配失败。解决方案修改 DSLsources语法支持schema字段schema: tenant_123并在 Parser 中将table和schema拼接为qualified_name再查询 Atlas。更优雅的做法在 Atlas 中为每个租户创建独立的TypeDef用tenant_id作为分类标签。Parser 查询时带上tenant_id参数只返回该租户的 schema。编译器生成 SQL 时必须用schema.table全限定名而非裸表名避免跨租户污染。注意这个坑我们踩了两次。第一次是开发环境单租户一切正常上线后才发现EXPLAIN验证用的是publicschema 的统计信息而实际执行在tenant_123schema导致执行计划偏差。最终解决方案是EXPLAIN请求也带上search_pathtenant_123确保统计信息一致。5.4 性能瓶颈编译器在高并发下响应延迟飙升现象QPS 50 时编译器平均延迟从 200ms 升至 2000mscompiler_dsl_parse_duration_secondsP95 达到 1500ms。根因分析Rust 的yaml-rust解析器是同步阻塞的且EXPLAIN请求是 IO 密集型。当大量请求排队等待数据库连接时线程池耗尽。优化措施将 YAML 解析移到 Tokio 的spawn_blocking线程池释放主线程。EXPLAIN请求使用连接池
