Agent 与数据库之间最缺的其实是一份“说明书”。最近我在做 Python 编译器实战项目时围绕“构建 Agent 就绪的数据库 OKF 知识包”这个方向反复折腾踩了不少坑也沉淀了一套自己觉得还算顺手的流程。这篇文章就把整个思路、技术拆解和实操过程完整梳理一遍覆盖我从 0 到 1 构建 OKF 知识包、让 Agent 真正理解数据库结构、并自动生成可用 SQL 的全部经历。如果你正在给 Agent 配数据库能力、做 NL2SQL 优化方案或者单纯想搞明白“知识包是什么”这篇内容应该能给你节省不少试错时间。1. 内容整体设计与思路拆解1.1 为什么 Agent 需要一份“数据库知识包”大多数人第一反应是把数据库 schema 直接丢给 Agent 不就行了表名、字段名、类型、注释都在Agent 会自己去读。但这个想法在真实业务场景里基本撑不住。原因很简单Agent 能在 prompt 里看到的 schema 摘要和它真正执行任务时需要的“语义级理解”之间存在巨大的断层。我遇到过几个典型表现。Agent 拿到用户问句“这个月各区域的客单价环比变化”会老老实实去 JOIN 订单表、区域表、日期维度表但它不知道“客单价GMV/订单数”这个计算口径在库里没有现成字段它也不知道订单表里的status字段只取paid因为撤销单和历史测试单全都混在里面。这些信息散落在接口文档、业务需求书、老同事脑子里唯独不在数据库 schema 里。Agent 没有这些背景知识就会生成一堆“语法正确、业务全错”的 SQL。所谓“Agent 就绪”就是把这些隐性知识显性化打包成 Agent 能直接读取、检索、引用的结构化文件。我构建的这个 OKF 知识包全称可以理解为“Ordered Knowledge File”的缩写它本质上是一种组织好的知识文件集合让 Agent 在生成 SQL 前先走一遍“查询知识定位 → 语义字段匹配 → 规则引用”的路径而不是凭空发挥。1.2 OKF 知识包的核心内容分层在设计知识包结构时我参考了类似 RAG 的思路但做了一点本地化调整。OKF 知识包不搞全局向量库而是围绕“单库单业务域”做分层归档。整个知识包分四层第一层是元数据层包含所有表的物理结构、字段类型、主外键关系、索引信息。这是 Agent 理解数据库的底座对应 AST 解析后导出的 schema JSON。第二层是语义层把字段名、枚举值、计算口径翻译成 Agent 能推理的业务术语。比如order_amt字段的语义描述是“订单实际支付金额含运费不含退款”状态值01/02/03分别对应“待支付/已支付/已取消”。第三层是行为模式层记录“什么场景下应该查哪张表、走什么 JOIN、加什么 WHERE 条件”相当于把资深数据分析师的查询习惯固化成 few-shot 样例。第四层是策略约束层写入权限边界、数据脱敏规则、时效性要求等硬性限制告诉 Agent“哪些列不能直接返回原始值”“哪些查询必须经过审批”。每一层都有独立的 markdown 或 JSON 文件承载最终通过一个目录索引文件okf.yaml把它们串起来。Agent 启动后先加载索引按需拉取各层文件而不是把几千行 schema 一次性塞进上下文这样既省 token也降低干扰。1.3 为什么用“Python 编译器”来构建知识包标题里有个关键词是“Python 编译器实战”这里需要解释清楚这个项目不是给 Python 写编译器而是利用编译器的经典前端技术——词法分析、语法分析、AST——去“编译”数据库结构把隐性的 schema 信息转换为显性的知识包文件。为什么不用简单的 ORM 反射或者写一堆 SQL query 直接查information_schema因为在复杂业务库里表名和字段名经常是缩写字段注释有一半是过期的类型映射五花八门既有decimal(10,2)也有varchar存数字。单纯反射拿到的是一堆“物理事实”缺的是“语义加工”。编译器思维恰好能解决这个问题——先把 schema 文本解析成 AST再在 AST 上做语义分析、规则匹配、注解注入最后多目标准确输出。用 Python 来做这件事也有实际考量生态成熟SQL 解析有现成的解析器数据类库齐全写原型快更重要的是后续想把这一套转成 Agent 工具函数时Python 可以直接被 LangChain 或自建的 Agent Runtime 加载不需要跨语言桥接。2. 技术拆解解析、规约与知识生成2.1 整体流程和数据流设计先把整个工具链的数据流画出来我这里不画图用文字描述MySQL/Oracle 元数据 → Python 脚本抓取 → 文本化 schema 文件 → SQL 解析器生成 AST → 语义规约与规则引擎 → OKF 各层知识文件 → 校验器验证结构 → 发布到 Agent 知识目录。这其中最关键的一步是“SQL 解析器生成 AST”。我试过直接拿正则去匹配建表语句结论是不能用。生产环境的建表语句动辄几百行字段定义里嵌着DEFAULT、COMMENT、ON UPDATE索引语句有各种前缀单靠正则写出来就是一个永远修不完的补丁系统。换用成熟的 SQL 解析器后AST 的结构非常规整后续的所有规则匹配都建立在树节点之上编程体验完全不一样。2.2 建表 AST 解析及结构对象设计以 MySQL 为例解析完一条建表语句后AST 会呈现出层次分明的结构。我封装了一个SchemaExtractor类来做遍历核心逻辑就是递归遍历 AST顺藤摸瓜地把表信息和字段信息抽出来。# schema_extractor.py (结构示意) from sqlparse import parse from sqlparse.sql import Identifier, IdentifierList, Parenthesis, TokenList def extract_create_table(sql_text: str): statements parse(sql_text) for stmt in statements: if stmt.get_type() ! CREATE: continue # 提取表名 table_name None token stmt.token_first() # ... 遍历 token 找到 CREATE TABLE 之后的主标识符 # 进入字段括号域 columns [] for token in stmt.tokens: if isinstance(token, Parenthesis): inside token.as_token_list() # 逐 token 拆字段名、类型、注释 # ... return {table: table_name, columns: columns, raw_ast: stmt}这一步值得说的细节是注释提取不能只信 COMMENT 关键字。MySQL 的表注释可以写在外层字段注释写在类型后面但实际业务表里很多注释是写在字段名里的比如pay_status这样的名字。我写的规则引擎会在 AST 层同时检查字段名子串、COMMENT 节、以及枚举 SHOW 语句三条路把可能的语义信息全部拖出来然后让后续的 LLM 注解环节去综合判断。2.3 语义标签与归一化处理结构解析只是第一步之后的核心是“归一化”。同一个字段在不同表里存在多种叫法create_time、created_at、gmt_create同一个语义概念在库里分散在多张表。规则引擎需要基于定义好的“语义字典”做归一化映射。# normalize.py (伪代码展示语义归一化逻辑) SEMANTIC_DICT { 时间类型: [create_time, created_at, gmt_create, submit_time], 金额类型: [amount, amt, total_fee, pay_money], 状态类型: [status, state, flag, status_code], } def normalize_column(col_name: str) - str: for semantic_type, aliases in SEMANTIC_DICT.items(): if col_name.lower() in aliases: return semantic_type # 额外走子串匹配如 pb_amt_score 命中 amt for semantic_type, aliases in SEMANTIC_DICT.items(): for alias in aliases: if alias in col_name.lower(): return semantic_type return 未识别归一化结果最终写入 OKF 语义层格式统一为原始字段名 : 语义类型 : 业务解释三元组这样 Agent 做查询意图映射时就不必穷举物理字段名面向语义层提问即可。2.4 类型推导与 Agent 可执行的类型系统原始 schema 字段类型五花八门bigint、decimal(10,2)、timestamp、jsonAgent 如果直接看到这些原生类型并不能很好判断“这个字段怎么参与运算”。我在类型层面加了一层“业务类型系统”把物理类型抽象成四类业务类型category枚举型对应状态类、渠道类字段适合 GROUP BY不适合数值聚合。metric指标型对应金额、数量、比率可直接做 SUM/AVG但要注意口径说明。time时间维度可用于趋势分析、周期对比。entity实体型如用户 ID、订单号适合关联查询不适合直接聚合。这个抽象映射写在 OKF 语义层的元信息里相当于给 Agent 配了一张“字段使用说明书”。Agent 在生成 SQL 时比如看到 “查询各渠道订单总量” 就会知道channel是 category 型order_id是 entity 型不会傻乎乎地SELECT SUM(order_id)。2.5 运行环境与依赖选择如果你打算把这个工具跑起来建议环境是 Python 3.10解析层用一个成熟的 SQL 解析库YAML 读写用pyyamlJSON Schema 校验用jsonschema。整个项目的依赖不算重大概就是四五个库。我没有用重型数据处理框架因为知识包构建是“离线批处理”每次库结构变更后跑一次即可性能不敏感重点是要稳、可解释。3. 核心细节解析与实操要点3.1 多表关系的自动提取与显式注入抽取完单表字段后多表关系是下一个必须处理的核心。Agent 做关联查询时如果不知道 JOIN 路径就会在十几张表里瞎猜。我从 AST 里不只解析建表语句还会解析外键约束语句和那堆天天被人手工维护的关联维表 SQL。举个例子order_info里有user_iduser_profile里有user_id但建表时没有声明外键。机器很难自己发现这层关系但业务规则知道。我在一个 CSV 配置文件里显式维护了一张“关联声明表”格式是source_table, source_column, target_table, target_column, relation_type order_info, user_id, user_profile, user_id, one_to_one order_info, goods_id, goods_info, goods_id, many_to_one规则引擎把这张表读进来合入 OKF 元数据层的relationships节点。正是因为有了它Agent 生成 JOIN 子句时才不会全表猜。我的经验是这个配置文件一定要人工维护不建议纯自动推导因为自动外键识别只覆盖少数库而且会产生大量冗余 JOIN 关系反而不利于 Agent 生成简洁 SQL。3.2 知识包文件的组织布局整个 OKF 知识包以目录形式存放在仓库里底层结构如下okf_package/ ├── okf.yaml # 包索引与版本号 ├── metadata/ │ ├── schema_full.json # 全量表结构 AST JSON │ ├── schema_ddl.sql # 原始建表 DDL 备份 │ └── relationships.yaml # 关联关系声明 ├── semantic/ │ ├── column_glossary.yaml # 字段名-语义名-口径 │ ├── enum_values.yaml # 枚举值业务含义 │ └── metrics.yaml # 指标计算口径表 ├── patterns/ │ ├── query_templates.md # 高频查询模板 │ └── few_shot_examples.md # 少样本示例(问句-SQL) └── policies/ ├── access_control.yaml # 权限控制与字段脱敏 └── query_rules.yaml # 查询改写规则索引文件okf.yaml是 Agent 最先读取的入口里面记录包版本、生成时间、包含哪些文件、每份文件的作用摘要、还有一条deprecated_fields列表专门存放已下线字段避免 Agent 踩进旧字段的坑。3.3 从 AST 到知识包一份代码实现样例只讲思路不给代码等于没讲。我摘一段项目里相对核心的知识包生成逻辑它的作用是把 schema 解析结果 语义归一化结果 关联关系合并最终输出semantic/column_glossary.yaml。import yaml from schema_extractor import extract_create_table from normalize import normalize_column METADATA load_meta_schema() # 从数据库同步 DDL RELATIONSHIPS load_relations_yaml(relationships.yaml) ENUM_OVERRIDE load_enum_yaml(manual_enum.yaml) def build_column_glossary(): glossary {} for table_schema in METADATA[tables]: table_name table_schema[table_name] table_comment table_schema.get(comment, ) glossary[table_name] { table_comment: table_comment, columns: {} } for col in table_schema[columns]: semantic_type normalize_column(col[name]) col_comment col.get(comment, ) manual_note ENUM_OVERRIDE.get( f{table_name}.{col[name]}, ) glossary[table_name][columns][col[name]] { type: col[type], business_type: semantic_type, comment: col_comment, manual_note: manual_note, nullable: col[nullable] } return glossary if __name__ __main__: glossary build_column_glossary() with open(okf_package/semantic/column_glossary.yaml, w) as f: yaml.safe_dump(glossary, f, allow_unicodeTrue, sort_keysFalse)这段代码跑完之后产出文件里每一列都有了“物理类型 业务类型 注释 人工补充说明”四件套这四件套就是后续 Agent 生成 SQL 时的关键参考。我建议在输出前再加一个“唯一性校验”要求一个表内不能出现两列归一化后业务类型相同且注释为空的情况若出现就强制报错逼着人工补注释。这个校验曾在实际项目中帮我拦住过 17 个漏注释字段。3.4 人工与自动的分工知识包不是全自动产物整个构建过程中最容易产生的误解是“一切都能自动化”。我的实践结论是结构层可以全自动语义层必须人机协同。AST 解析、类型归一化、YAML 序列化都是程序干的活但给字段写业务口径、给枚举值标注“哪些状态代表有效订单”、给查询模板挑选高质量样例这些必须有懂业务的人参与。我建立了一个“三阶段确认”流程第一阶段编译器自动输出草稿包第二阶段业务分析师用 diff 工具逐个审查语义描述第三阶段把审查通过的包放到测试 Agent 环境里跑 50 条黄金查询准确率达到目标后发布正式版本。整个过程 12 周迭代一轮比纯靠 DBA 手工写维护文档要快得多。4. 实操过程与核心环节实现4.1 完整实操步骤速查表整个操作流程如果用表格概括大致是下面这 8 步。每一步后面我会单独展开讲解关键点。步骤工作内容输入输出1元数据采集数据库连接信息raw DDL 文件夹2DDL 解析raw DDL 文件夹schema AST JSON3语义归一化schema AST JSON、语义字典column_glossary.yaml4关系抽取与注入schema AST、关联声明 CSVrelationships.yaml5枚举值整理数据库数据字典、人工确认enum_values.yaml6查询模板沉淀历史慢查询、业务方需求query_templates.md7策略与权限注入安全团队规范access_control.yaml8生成 okf.yaml 索引以上所有文件完整 OKF 知识包4.2 元数据采集环节要注意注释同步这一步是地基。由于生产库普遍存在“建表语句的注释滞后于真实业务”的问题我建议不要只抓一次 DDL 就完事而是定时通过数据字典视图抓取最新列注释并与上一次的 schema JSON 做 diff发现有注释变化的列自动打上need_human_review标记。这一招帮我提前发现过几次“业务字段含义悄悄变化但文档没人更新”的情况。元数据采集的脚本可以做成定时任务每周一凌晨跑一次跑完把 diff 输出到一个changelog.md里作为 Agent 上下文更新的依据。4.3 语义归一化环节实战参数选择语义归一化不是简单做映射表就结束它的参数选择直接影响 Agent 的命中率。我调过几个关键项值得拿出来说词形还原开关字段名里user_name和username必须归一化到同一个语义概念。开掉_分隔符后做子串匹配比单纯做完整匹配召回高很多。忽略前缀表某些表有业务前缀如tmp_、test_、bak_如果参与归一化会和正式表混淆。这会把这些前缀作为“忽略词”。人工覆盖优先级最高任何自动归一化的结果一旦命中人工维护的 overrides 表直接以人工结果为准程序不做二次判断。这样可以避免自动逻辑把“存量表改名”搞混乱。举个例子我在一个模拟项目里遇到过is_deleted字段自动归一化会把它识别成“布尔状态”但实际上这个字段在业务里的语义是“逻辑删除标记”意味着查询默认要过滤is_deleted 0。在 overrides 表里手动把它标为 “soft_delete_flag”并注入到 Agent 的默认过滤条件模板中效果立刻就不一样了Agent 生成的 SQL 不再需要每次 pick 时猜是否要过滤。4.4 枚举值整理构造枚举值词表Agent 写 SQL 时最头疼的两类问题分别是枚举字段的取值不敢硬编码怕记错代码含义以及不知道代码里哪些值是有效状态。我把枚举值整理成一份三层结构存到enum_values.yamlorder_info: status: valid_values: [02, 03] invalid_values: [01, 04, 99] mappings: 01: 待支付 02: 已支付 03: 已完成 04: 已取消 99: 异常单 default_filter: AND status IN (02,03)这里default_filter是神来之笔。有了这个字段Agent 生成 SQL 时可以直接从知识包引用默认过滤条件而不是从零推理。我一直觉得与其让 Agent 自己在几十个代码值里瞎折腾不如把“有效状态”直接写成查询片段塞给它这样既省 token 又提升准确率。4.5 查询模板沉淀让知识包有“经验”的味道知识包里最“值钱”的部分其实是patterns/query_templates.md。它不是随便找几条 SQL 拼凑而成而是我对大量历史慢查询和业务座席手工报表做聚类之后筛出来的 TOP 20 高频分析模式。每个模板包含三部分模板名称、适用问句示例、可参数化的 SQL 骨架。## 模版: 区域销售月环比 适用问句: 请对比华东/华南/华北三个区域本月的销售额环比 参数表: region_list, start_date, end_date, pct_change_method SQL骨架: SELECT region, SUM(amount) AS total_amount, ROUND( (SUM(amount) - LAG(SUM(amount)) OVER(PARTITION BY region ORDER BY month)) / LAG(SUM(amount)) OVER(PARTITION BY region ORDER BY month), 4 ) AS pct_change FROM orders o JOIN region_dim r ON o.region_id r.id WHERE region IN (region_list) AND month BETWEEN start_date AND end_date GROUP BY region, month;沉淀模板的价值在于Agent 遇到相似问题时不需要从零拼 SQL而是检索模板后做参数填充。实测下来20 条模板能覆盖业务方 60%70% 的常见分析请求剩下的复杂定制查询才需要 Agent 现场组装。这也是 OKF 知识包名副其实“Agent 就绪”的底气所在它已经预置了“能力”。4.6 策略约束与安全Agent 不能啥都查权限与脱敏策略如果在知识包里被忽略后面一定会出事。我在策略层做了几件很具体的事明文手机号、身份证字段标记为sensitive_level: highAgent 生成 SQL 时自动拼接脱敏函数或提示“该查询需申请审批”。大表查询默认限制每次返回行数不超过 1000 行并强制要求必须带 WHERE 条件或 LIMIT 子句。跨天全表扫描行为被标记为“高风险”如果 Agent 生成的 SQL 尝试触达这些模式会先返回一条提示让用户确认。这些策略不是摆设它们真正做到了“知识包即约束”。Agent 在生成阶段就会受知识包内容影响而不是等 SQL 执行引擎层去拦截。我的体会是把约束前置到 Agent 知识层比事后在数据库端做 SQL 审核要平滑得多。5. 常见问题与排查技巧实录5.1 常见问题速查表做这个项目的过程中我踩过的坑基本可以归为下面几类整理成速查表供你照着排查。现象可能原因解决方式知识包里字段注释大量为空元数据采集时注释字段提取失败检查采集 SQL 是否漏掉COLUMN_COMMENT或者源库表注释本身就没维护归一化把所有字段都识别成“未识别”语义字典过小或词形处理遗漏扩充语义字典加子串匹配人工补充 overridesAgent 生成的 SQL 频繁 JOIN 多余表关系声明文件里存在冗余关联精简 relationships.yaml只保留高频路径枚举值硬编码在 Agent 上下文里消失知识包加载时未正确读取 enum_values.yaml检查包索引是否把 semantic 目录挂载全生成的 SQL 带SELECT *模板缺少字段白名单约束在 query_rules.yaml 中写明“禁止 SELECT *必须列出字段”知识包版本更新后 Agent 行为突然变化缓存未清理或索引版本未递增版本号 包加载时校验 content hash5.2 排查技巧如何定位“Agent 为啥生成了错误 SQL”定位 Agent 生成错误 SQL 的问题我的排查顺序是这样的先复现 Agent 的输入输出链路把它加载知识包的原始数据 dump 出来接着对比“知识包中到底有哪些字段说明”和“生成 SQL 用了哪些字段”找到对应不上的字段最后给该字段补一条人工注解或调整语义归一化结果重新生成包。这中间最可能出现的问题是Agent 从上下文里检索到的字段描述不完整只看列名就急着自己猜。解决办法是把 OKF 语义层做成“字段级描述必须包含注释、业务类型、有效值三选一”缺一项就报 warning。如果某项缺失Agent 决策时就会拿残缺信息硬撑这是所有错误 SQL 的共同源头。5.3 独家避坑技巧分享最后分享三个我自己特有价值的避坑经验。一是知识包与数据库结构变更必须联动版本号。我一开始没做包版本管理结果某次数据库里加了新表Agent 还在用旧知识包导致新表相关查询全部失败。后来在okf.yaml里强约束每次变更递增版本号并让 Agent 启动时检查版本新鲜度。这一步看起来简单却是知识包治理工程里最重要的一环。二是查询模板里的 SQL 骨架必须经过真实环境验证。我早期手工整理模板时有些 SQL 骨架在测试环境能跑但到了生产环境因为分区键变化、字段权限不同、数据量大小导致执行计划不一样性能差很多。所以现在每次发布模板前都会把模板跑一遍生产计划 EXPLAIN 看耗时超过阈值的直接打回。三是想办法把 DBA 的经验“翻译”进知识包而不是让 DBA 成为 Agent 的接口人。做过几年业务数据库的人心里都有很多不成文的规则比如“订单表千万级查询一定要带时间范围”“状态字段不要用等号匹配要用 IN 包含有效集”。这些规则如果不在知识包里沉淀Agent 永远学不会一旦写进去了Agent 的表现会立刻上一个台阶。我认为这才是“知识包”项目的真正内核不是搞一堆 JSON 文件而是把行业里散落在人脑里的规则结构化、机器可读化。6. 从构建到维护知识包的持续迭代思路6.1 知识包的生命周期管理知识包并不是一次性交付物它跟数据库一样有自己的生命周期。我在项目里设计了三个赛道触发式更新DDL 变更时自动触发、周期式复盘每周分析 Agent 历史查询准确率刷新模板、人工修正业务口径调整时手动改语义文件。三者合并保证知识包永远与真实库结构同步也永远在向更高质量演进。6.2 评价知识包质量的量化指标如果只用一句话来评价知识包做得好不好我建议盯住“Agent 一次生成 SQL 可执行且业务口径正确率”这个指标。我给自己定的及格线是 90%优秀线是 97%。围绕这个指标再拆出子指标模板覆盖率、字段描述覆盖率、枚举值覆盖率和 join 路径命中率。每项覆盖率的下降点就是知识包需要补强的地方。有了这套量化体系后续所有改进都有了抓手而不是凭感觉调包。总结来说构建 Agent 就绪的数据库 OKF 知识包表面上是个工程任务实际是把数据库从“物理存储层”提升到“语义理解层”的系统工程。Python 编译器在其中扮演的是骨架生成器真正的灵魂是那些能反映业务规则、口径、约束的知识注入。从我个人的实操来看一旦知识包做得足够扎实Agent 在数据库领域的能力表现是质的飞跃它终于不再像一个只会套模板的实习生而像一个熟悉表结构、懂业务口径的数据分析师。这个方向的空间还很大后续我也会继续迭代模板自动生成、知识包自检这几块能力让知识包本身变得越来越“聪明”。