这是 2026 年的第 39 篇文章
（本文阅读时间：约 20 分钟）
01
在高德的数据驱动运营体系中，产运团队面临大量日常取数需求，如“昨日美食行业 GMV"、“上周各城市广告消耗”等。传统路径需经历“提交需求 -BI 分析 -SQL 执行 - 返回结果”的漫长流程，耗时往往以小时甚至天计。
高德数仓覆盖交易、业财、广告、流量等 9 个业务域，涉及数千张 ODPS 表。同一术语在不同域口径迥异（如“收入”在广告域与业财域定义不同），这种复杂性使得“让 AI 写 SQL"从技术可行到业务可用之间存在巨大鸿沟。
基于 QoderWork Agent Skill，我们构建了一套 NL2SQL 智能取数系统。该系统以元数据为权威、规则为约束、LLM 为规划器、ODPS 为执行引擎，深度绑定业务数仓，具备理解业务术语、主动澄清歧义及附带口径说明的能力。
本文将复盘系统从 V1 到 V2 的架构演进及知识工程方法论，重点涵盖架构设计与演进、知识工程方法论以及核心设计原则，为企业数仓 NL2SQL 系统及 Agent Skill 架构实践提供参考。
02
2.1 V1 的设计
V1 阶段采用按业务域拆分的朴素策略，为交易、业财、广告等 8 个域分别部署独立的 QoderWork Skill，另设 1 个 odpscmd 工具 Skill 负责执行，共计 9 个 Skill。每个 Skill 自包含提示词（SKILL.md）与知识库（references/），彼此独立迭代。
该架构边界清晰，快速覆盖了约 40 张核心结果层（ADS）表，验证了核心假设：在高质量知识库与严格提示词约束下，LLM 能在企业数仓场景生成准确 SQL。然而，随着表覆盖范围从 40 张扩展至 352 张，V1 暴露出一系列结构性问题。
2.2 五个结构性问题
问题一：用户安装与选择成本高。用户需自行判断并安装对应域的 Skill，使用时手动指定。面对“收入”、“供给”等跨域术语，非技术人员难以准确路由，心智负担过重。
问题二：Skill 间路由天花板低。依赖 description 文本的语义匹配机制无法承载复杂的消歧信息，且路由过程黑盒化，无法调试或针对特定场景编写规则。
问题三：表规模扩充加剧域间冲突。随着明细层（DWD）和汇总层（DWS）表的加入，跨域关联查询成为常态。多 Skill 架构无法支持跨域知识读取，导致复杂查询失败。
问题四：维护成本指数膨胀。日期计算、SQL 安全约束等公共逻辑在 9 个文件中重复维护，同步更新困难，极易出现不一致。
问题五：后续扩展和迭代不便。新增业务域或调整域边界时，涉及 Skill 重组及用户重新安装，架构演进僵硬。
2.3 认知转折
V1 问题的根因在于Skill 间的路由决策发生在控制范围之外。当路由准确率成为瓶颈且不可控时，必须将路由逻辑收归 Skill 内部。V2 的核心命题转变为：如何在一个 Skill 内实现统一入口和智能路由，同时避免上下文窗口溢出？
03
3.1 四层架构设计
V2 并未简单合并 Skill，而是在统一 Skill 内部建立了分层架构，实现关注点分离：
- L1·域路由层：内置于 SKILL.md，通过确定性规则表提取用户意图，判定所属业务域，并在歧义时主动澄清。
- L2·知识加载层：基于路由结果，仅加载目标域的 reference 文件。单次查询仅需加载 200-400 行知识，极大节省 Token。
- L3·标准工作流层：统一定义前置检查、路由、加载、确认、生成、执行解读 6 步流程，确保质量基线一致。
- L4·公共服务层：集中管理日期计算、SQL 安全、执行协议等公共逻辑，全域共享。
3.2 为什么选确定性路由而非 RAG？
面对 352 张表，我们放弃 RAG（向量检索）而选择确定性规则，主要基于三点考量：
- 语义重叠导致 Embedding 不可靠：“收入”、“供给”等术语在不同域含义截然不同但语义相似，模糊检索极易出错。
- 有限分类可枚举：9 个域、数百张表属于有限分类问题。规则路由可调试、可追溯，能精确解释决策依据。
- 工程复杂度与收益平衡：当前规模下纯规则方案准确率已足够高，引入向量检索带来的复杂度与可解释性损失得不偿失。
3.3 两级路由详解
两级路由是 V2 的核心机制：
一级路由（域路由表）：负责跨域消歧。基于“指标意图 + 视角”进行判断，并维护易混淆术语消歧规则。例如针对“收入”，根据上下文关键词（投放 vs 结算）路由至广告域或业财域，无法判断时提供选项让用户澄清。
二级路由（域内选表）：每个域的 DOMAIN.md 定义域边界、可用表清单、问题到表的映射及选表优先级链（ADS > DWS > DWD）。例如交易域优先使用结果层总览表，仅在需要明细排查时降级至 DWD 层。
3.4 渐进式知识加载
为避免 30,000 行全量知识导致上下文溢出，V2 采用四级渐进式加载策略，由粗到细：
典型查询实际加载量控制在 200-400 行。这种设计不仅节省了 Token，更实现了“加载路径即推理路径”，便于故障定位与文档优化。
3.5 统一 6 步标准工作流
V2 定义了所有域统一遵循的 6 步流程，确保输出标准一致：
- 前置检查：识别节假日等特殊时间因素。
- 一级路由：判定业务域，触发歧义澄清。
- 二级路由：加载目标域知识，定位候选表。
- 口径确认：校验时间、指标、维度等口径歧义。
- 选表 +SQL 生成 + 自检：按优先级选表，生成 SQL 并执行 5 点自检（分区、字段、维度、JOIN 键、LIMIT）。
- 执行 + 结果解读：执行 SQL 并转化为业务语言解读，附带完整口径说明。
04
NL2SQL 系统的天花板在于知识质量。本项目中，352 张表、约 30,000 行结构化文档的建设占据了 60% 以上工作量。
4.1 表文档标准化：6 节知识卡片
每张表对应一个 Markdown 文件，遵循统一的 6 节结构（知识卡片）：
- S1·表元数据：包含全表名、层级、粒度、分区及更新频率，决定表的可用性。
- S2·字段列表：标注 KEY/DIM/IDX 前缀及中文释义，辅助模型区分分组与聚合字段。
- S3·场景映射：明确适用与不适用场景，防止选表错误。
- S4·关联方式：指明 JOIN 维度表的方式与键值。
- S5·指标口径定义：核心章节，精确定义计算公式与注意事项，严禁模型编造。
- S6·SQL 模板：提供高频场景参考 SQL，作为最佳实践引导模型生成。
4.2 元数据产出 Pipeline
采用半自动化 Pipeline 高效产出文档：
- 技术元数据拉取（自动）：批量获取 ODPS 表基础信息。
- 初版文档生成（半自动）：LLM 推断字段含义与场景，完成约 60% 内容。
- 业务知识注入（人工）：专家补充精确口径、业务规则及 SQL 模板，这是最关键环节。
- 标准化校验（自动）：检查格式规范与完整性。
4.3 知识分层与变更频率对齐
按变更频率将知识分为三层，降低维护风险：
- 静态层：表结构与字段定义，随 DDL 低频更新。
- 规则层：路由规则与选表映射，按业务需求中频调整。
- 公共层：日期指令、执行协议等，高度稳定。
4.4 AI-Friendly 标准分
建立量化评分体系，从字段覆盖率、口径完整度、SQL 模板覆盖率等维度评估知识库质量，驱动针对性迭代。
05
5.1 评测驱动迭代
维护 900+ 道测试题，自动化对比生成 SQL 与标准答案。通过错误归因分析（选表错误、语法错误、口径错误等），精准指导优化方向。
5.2 DDL 一致性监控
开发 cici_monitoring 工具，定期比对线上 ODPS 表结构与知识库文档，检测字段漂移，防止因元数据不一致导致的“沉默失败”。
5.3 用户反馈闭环
捕捉用户纠正、重复提问、对话放弃等沉默信号，结合值班 review 机制，将高频问题转化为知识库更新，问题解决率稳定在 70% 以上。
06
经过实践沉淀出五条核心设计原则：
- 确定性优于模糊性：关键决策走规则而非模型概率，确保可调试、可追溯。
- 按需加载优于全量灌入：利用少量 Token 开销换取上下文空间，知识库结构应为 LLM 加载路径服务。
- 知识分层对齐变更频率：分离动静知识，降低回归风险与维护成本。
- 标准化优于自由发挥：统一文档结构与工作流，保障多域协作下的质量基线。
- 评测驱动优于经验判断：以准确率和标准分为唯一指南针，建立共同的质量语言。
07
7.1 关键成效
截至 2026 年 4 月底，系统在多个业务方向落地。NL2SQL 准确率超 95%，智能问数场景覆盖率超 90%，取数效率相比传统流程提升 30 倍以上。实践证明，确定性路由加知识工程的路线在当前规模下高效可行，且具备低成本横向复制能力。
7.2 未解决的问题与展望
系统仍面临三大挑战：
- 跨 Skill 知识共享：取数与分析 Skill 间的知识库协同尚待解决。
- 知识库平台化管理：需从树形结构转向图状管理，实现知识的自动关联、过时检测与冲突发现。
- 端到端 Agent 评测：需建立覆盖回答清晰度、交互流畅度等维度的综合评测体系。
NL2SQL 本质上是一个知识工程问题。架构设计与知识工程才是此类系统真正的技术壁垒。
