六层工程体系让 AI Agent 稳定输出准确 SQL 的实战指南引言让 AI Agent 根据一句自然语言需求就输出准确的 SQL听起来像是模型能力问题但实际上是一个工程体系问题。单靠换更强的模型、调更好的 Prompt效果很快就会碰到天花板。真正能让这套系统在生产环境稳定运行的是一套由元数据、语义层、案例库、知识库、Skill 系统、校验体系六个模块组成的工程架构。本文将逐一拆解每个模块的设计思路和落地细节并介绍如何将它们串联成端到端的自动化流程。一、整体架构概览整个系统分为三层加一层校验输入层接收用户的自然语言需求处理层完成需求理解、SQL 生成等推理任务支撑层提供元数据、语义定义、案例、业务知识等事实依据校验层保障输出 SQL 的正确性与可靠性各层之间通过标准化接口通信每一层都可以独立迭代升级。二、元数据管理——Agent 理解数据的入口元数据是 Agent 认识数据资产的基石。如果元数据质量差——表名是拼音缩写、字段没有中文注释、血缘关系缺失——那么 Agent 即便推理能力再强也无法正确找到目标表和字段。企业元数据通常分为三类类别内容作用技术元数据表名、列名、数据类型、主外键告诉 Agent 有哪些表和字段业务元数据中文含义、计算口径、负责人解释字段背后的业务含义操作元数据血缘关系、更新频率、质量评分帮助 Agent 判断表的可靠性技术元数据可从数据库系统自动采集业务元数据需要人工标注或从文档中抽取操作元数据需要在数据 Pipeline 运行过程中积累。以 OpenMetadata 为例它为每个高频使用的字段提供完整标注{field:order_amount,chinese_name:订单金额,business_definition:包含运费扣除优惠券后的实付金额,calculation_formula:SUM(商品金额 运费 - 优惠券抵扣),data_type:decimal(10,2),example_query:SELECT SUM(order_amount) FROM orders WHERE create_date 2025-01-01}数据血缘则解决这个指标从哪来的问题。当用户说我要看 GMVAgent 需要通过血缘找到 GMV 最终落在哪张宽表里以及中间经过了哪些加工步骤。根据 Spider 论文的研究结论Schema Linking准确定位相关表和列是 Text-to-SQL 任务中准确率的最大瓶颈。元数据标注的质量直接决定了这一环节的上限。三、语义层——在业务语言与数据库之间架桥元数据解决了有什么的问题但用户口中说的是 GMV、获客成本、复购率而不是ws_daily_gmv或gmv_amount。语义层的作用就是在业务语言和技术实现之间搭一座桥。语义层需要做到三件事指标定义标准化将 GMV、DAU 等指标的计算逻辑封装成统一定义保证所有人查出来都是同一个数。维度统一管理确保地区在所有指标中的含义一致。自动导航 Join 路径Agent 不需要知道底层表是如何关联的语义层会自动找到正确的路径。以 MetricFlow 为例我们可以定义一个语义模型semantic_model:name:ordersentities:-name:order_idtype:primarydimensions:-name:created_attype:time-name:channeltype:categoricalmeasures:-name:order_totalagg:sum-name:order_countagg:count然后定义指标metrics:-name:revenuetype:simplemeasure:order_total-name:food_revenue_pcttype:derivedexpr:food_revenue / total_revenue定义好后Agent 生成 SQL 时就不需要自己拼 Join 和聚合逻辑了直接通过 MetricFlow 的 API 查询指标即可。Cube 则在标准 SQL 基础上增加了指标函数并提供 MCP Server 接口供 AI Agent 通过 MCP 协议直接接入。对 Agent 而言语义层解决了三个实际问题消除指标歧义、降低复杂度、保证口径一致。四、案例库——提供推理样本而非模板案例库不同于 SQL 模板库。SQL 模板只能处理固定模式的需求而真实业务需求千变万化。案例库要做的是提供从需求描述到最终 SQL 的完整推理链路包括需求是如何拆解的、选了哪些表、为什么这么写。每条案例语料应包含原始需求需求分析拆解出的指标、维度、过滤条件、隐含逻辑涉及的表最终 SQL验证结果标签案例库有四个主要来源历史需求工单和 BI 团队过去处理过的需求人工构造针对高频业务场景由分析师主动编写典型案例用户反馈用户通过 AI 系统提交需求后人工审核的结果回流错误案例Agent 写错的 SQL 同样有价值标注清楚错在哪、如何修改新需求进来后如何找到最相关的历史案例通常结合两种方式语义相似度使用 Embedding 做向量检索关键词匹配提取指标、维度和表名进行精确检索检索到的案例会作为 Few-shot Examples 放进 Prompt帮助 Agent 理解当前需求应该映射到哪些表以及应该使用什么 SQL 模式。五、知识库——告诉 Agent “为什么”案例库教 Agent怎么做知识库告诉 Agent为什么这么做。例如用户说查华东区的 GMV。如果 Agent 不知道华东区包含哪些省份它可能只查询华东这个字段值漏掉上海、江苏、浙江的数据。又如GMV 的定义在三个月前改过——之前包含未付款订单现在只计算已付款订单。如果 Agent 不知道这个变更查出来的数就会对不上。知识库主要存放五类内容业务术语表解决术语歧义如 GMV 成交总额是否含未付款订单决策记录记录口径变更历史如从 Q3 起获客成本不再包含品牌广告组织架构解决维度理解华东区 上海、江苏、浙江业务规则处理时间逻辑退款完成七天后才从 GMV 中扣除使用说明避免选错数据源某表不包含测试订单以结构化 YAML 文件管理为例terms:-term:GMVfull_name:Gross Merchandise Volumechinese_name:成交总额definition:已付款订单的商品总金额不含运费和优惠券exclusions:[未付款订单,已取消订单]related_metrics:[revenue,refund_rate]updated_at:2025-07-01owner:data-team知识库通过 API 方式接入 Agent 的工作流。当 Agent 遇到不确定的业务概念时先去知识库里查询。这样Agent 不只是在翻译需求而是在理解需求。六、Skill 系统——将能力编排成自动化流水线前面四个模块都是知识层面的东西但光有知识还不够还需要有人把这些知识串起来使用。Skill 系统就是把元数据、语义层、案例库和知识库这些散落的能力编排成可以自动执行的工作流。一个典型的 Skill 定义如下YAMLskill:name:text_to_sqlsteps:-step:demand_analysisdescription:提取核心指标、分析维度、过滤条件、时间范围、隐含逻辑-step:semantic_searchdepends_on:[demand_analysis]service:semantic_layer-step:case_searchdepends_on:[demand_analysis]service:case_library-step:metadata_querydepends_on:[demand_analysis]service:metadata-step:sql_generationdepends_on:[semantic_search,case_search,metadata_query]-step:sql_validationdepends_on:[sql_generation]每个 Step 负责一件事Step 之间有明确的依赖关系。Agent 按照这个定义一步步执行遇到问题时可以回溯到上一步重试。实际运行时Agent 通过 Function Calling 调用各个 Skill。以 Anthropic 的 Tool Use 模式为例Agent 根据任务需要自主决定调用哪个工具、传什么参数以及如何处理返回结果。七、校验体系——保障输出质量的最后防线前面几个模块解决的是怎么生成的问题校验体系解决的是怎么保证质量的问题。Agent 生成的 SQL 不能直接使用不是因为它一定会错而是因为你不知道它什么时候会错。校验分三层从自动到人工逐层递进1. AI 自动评估SQL 生成后立即运行检查包括语法检查安全性检查如禁止 DROP 等危险操作Schema 一致性检查表、字段是否存在语义一致性检查用另一个 LLM 审查生成的 SQL 是否真的回答了用户需求查询性能检查预估扫描行数、是否有全表扫描风险其中语义一致性检查最有价值能够抓住很多语法正确但逻辑错误的情况。2. 对抗审查由一个独立的 Review Agent 专门找茬检查笛卡尔积风险Join 条件缺失聚合粒度不正确数据倾斜隐患这种对抗机制能够显著提高输出质量。3. 人工核验涉及财务数据或对外报告的场景最终需要数据工程师审核一遍。人工看的不是语法而是业务逻辑是否正确以及结果是否合理。校验结果不应只有 Pass 或 Fail。每一次失败都应该回流到系统中失败案例经过标注后加入案例库新发现的业务规则加入知识库Prompt 的薄弱环节进一步加固系统的准确率就是在这个闭环里一点点提升的。八、端到端流程将以上六个模块串联起来完整的流程如下用户输入自然语言需求 ↓ 需求理解提取指标、维度、过滤条件、时间范围、隐含逻辑 ↓ 语义检索从语义层获取指标定义和维度映射 案例检索从案例库获取相似推理样本 元数据查询从元数据系统获取表结构、血缘 知识库查询补充业务规则和术语解释 ↓ SQL 生成综合以上信息生成候选 SQL ↓ AI 自动校验语法、安全、语义一致性、性能 对抗审查Review Agent 找茬 人工核验必要时 ↓ 输出最终 SQL或返回错误信息引导用户修正整个过程贯穿四个设计原则分层解耦每个模块可以独立运行、独立迭代知识驱动语义层、元数据、案例库、知识库并行检索构成 Agent 的知识底座校验前置在核心生成环节设置多重检查点持续迭代通过反馈闭环让系统越用越准确九、落地建议好消息是这六个模块都不需要从零开始造轮子。目前已有成熟的开源基础设施元数据管理OpenMetadata支持 70 数据源语义层MetricFlow、Cube提供 MCP Server 接口案例库与知识库可使用向量数据库如 Milvus、Weaviate配合 Embedding 模型构建Skill 系统可通过 LangChain、Semantic Kernel 等框架编排校验体系可基于 LLM 自身能力加规则引擎实现你需要做的是把它们串起来针对自己的业务场景做好标注、积累和校验。当然开源方案未必能满足所有诉求需要根据实际情况决定是自研还是使用开源方案。总结AI 自主需求开发不是换一个更强的模型就能解决的问题。它需要元数据管理让 Agent 能看懂数据资产需要语义层让自然语言准确映射到指标需要案例库提供推理样本需要知识库补充业务背景需要 Skill 系统编排自动化流程需要校验体系保障输出质量。六个模块协同起来才能真正实现用户提需求、Agent 出 SQL的体验。六个模块单独看都不复杂难的是把它们串成一个整体并持续打磨。希望本文能为正在构建或优化 Text-to-SQL 系统的你提供一些实际的参考。