據(jù)庫(kù)知識(shí)包：從DDL到OKF的工程實(shí)踐)
第二次讓 Agent 直接連數(shù)據(jù)庫(kù)做查詢它把訂單表和客戶表的關(guān)聯(lián)字段猜錯(cuò)了當(dāng)天晚上我收到一排告警。那一刻我才想明白把一堆CREATE TABLE丟給 Agent跟把一本沒(méi)有目錄、沒(méi)有注釋的字典丟給新來(lái)的實(shí)習(xí)生本質(zhì)沒(méi)有區(qū)別。后來(lái)我花了兩周時(shí)間寫了一個(gè) Python 編譯器把 DDL、業(yè)務(wù)術(shù)語(yǔ)、字段枚舉、關(guān)系強(qiáng)弱這些信息統(tǒng)一編譯成一份Agent 就緒的數(shù)據(jù)庫(kù) OKF 知識(shí)包。這套東西不解決“怎么寫 SQL”它解決的是“怎么讓 Agent 在寫 SQL 之前真的讀懂?dāng)?shù)據(jù)庫(kù)”。這篇文章就把這個(gè)項(xiàng)目的完整思路拆開(kāi)講為什么要從 DDL 里編譯知識(shí)包而不是直接讓 Agent 問(wèn)元數(shù)據(jù)接口、知識(shí)包內(nèi)部結(jié)構(gòu)怎么設(shè)計(jì)、編譯器流水線怎么搭、Agent 側(cè)怎么消費(fèi)以及我踩過(guò)的那些低級(jí)的坑。適合正在搭 Agent 數(shù)據(jù)助手、或者準(zhǔn)備把數(shù)據(jù)庫(kù)能力開(kāi)放給大模型工具鏈的人參考。1. 為什么 Agent 接數(shù)據(jù)庫(kù)之前先要有一份 OKF 知識(shí)包先說(shuō)一個(gè)最直接的體感。讓 Agent 調(diào)用數(shù)據(jù)庫(kù)工具時(shí)大多數(shù)實(shí)現(xiàn)就是把表名、列名、類型、主鍵外鍵這些元數(shù)據(jù)拼進(jìn) prompt或者讓 Agent 自己SHOW TABLES之后去猜。我的項(xiàng)目前三天就是這么干的效果非常糟糕。1.1 表結(jié)構(gòu)信息與業(yè)務(wù)語(yǔ)義之間的斷層數(shù)據(jù)庫(kù)表結(jié)構(gòu)天然缺三塊東西第一塊是字段的業(yè)務(wù)含義。customer_id到底是下單客戶還是收貨聯(lián)系人status字段是 0 表示正常還是 1 表示正常這類信息在 DDL 里往往只有一個(gè)字段名再看一眼類型沒(méi)了。Agent 面對(duì)這種信息缺口它只會(huì)靠大模型預(yù)訓(xùn)練時(shí)積累的“通用常識(shí)”去腦補(bǔ)而通用常識(shí)和數(shù)據(jù)倉(cāng)庫(kù)的真實(shí)業(yè)務(wù)往往不是一回事。第二塊是枚舉值和取值邏輯。很多表用 tinyint 存狀態(tài)DDL 里根本不寫0 代表什么、1 代表什么。Agent 一旦猜錯(cuò)生成的 SQL 雖然語(yǔ)法完全正確查出來(lái)的業(yè)務(wù)口徑卻是全錯(cuò)的。這類問(wèn)題比語(yǔ)法報(bào)錯(cuò)隱蔽得多因?yàn)镾QL跑得通、結(jié)果也非空但就是不對(duì)。第三塊是表與表之間的真實(shí)關(guān)系。外鍵約束寫得很清楚的庫(kù)是少數(shù)更多場(chǎng)景里兩個(gè)表靠一個(gè)名叫code的字段軟關(guān)聯(lián)業(yè)務(wù)上卻是一對(duì)多。Agent 看不到業(yè)務(wù)約束就很容易把關(guān)聯(lián)方向搞反或者在一張寬表上本來(lái)能直接過(guò)濾它偏要去 join 一張外表。1.2 直接拼 DDL 為什么不經(jīng)濟(jì)有人會(huì)說(shuō)那把 DDL 全文貼進(jìn) prompt 不就行了我也試過(guò)。一個(gè)稍微規(guī)范一點(diǎn)的庫(kù)十來(lái)張表DDL 加起來(lái)幾千行很正常。塞進(jìn)上下文之后Agent 確實(shí)能“看到”字段但注意它看到的是純物理結(jié)構(gòu)不是認(rèn)知結(jié)構(gòu)。DDL 里有大量 Agent 不需要關(guān)心的內(nèi)容存儲(chǔ)配置、索引定義、字符集、分區(qū)策略。這些內(nèi)容不僅浪費(fèi) token還會(huì)干擾它對(duì)核心語(yǔ)義的聚焦。還有一個(gè)問(wèn)題物理結(jié)構(gòu)有歧義。同一條 MySQL 的CREATE TABLE語(yǔ)句在不同版本里字段類型寫法不一樣注釋可能寫了一大段也可能完全沒(méi)有。你無(wú)法保證 Agent 每次能從這些原始文本里穩(wěn)定提取出同樣的信息。而知識(shí)包提供的是經(jīng)過(guò)清洗、歸一化、補(bǔ)全之后的確定性產(chǎn)物同一份 DDL 輸入永遠(yuǎn)編譯出同一份知識(shí)包。這樣你至少能控制 Agent 拿到手的數(shù)據(jù)庫(kù)畫像是一致的不會(huì)因?yàn)槟Ｐ托那椴煌鴮?duì)同一張表產(chǎn)生兩種理解。所以這個(gè)項(xiàng)目我給自己定的目標(biāo)是把數(shù)據(jù)庫(kù)知識(shí)的構(gòu)建從“讓模型臨場(chǎng)發(fā)揮”變成“預(yù)先編譯、按需檢索”。這也是 “Agent 就緒的數(shù)據(jù)庫(kù) OKF 知識(shí)包” 這個(gè)名字的由來(lái)——先有格式再有編譯器最后才談 Agent。2. OKF 知識(shí)包長(zhǎng)什么樣我給數(shù)據(jù)結(jié)構(gòu)定了哪些規(guī)矩OKF 是我在項(xiàng)目?jī)?nèi)部給這套知識(shí)包格式起的代號(hào)全稱是 Open Knowledge Format。它不是公開(kāi)標(biāo)準(zhǔn)而是我根據(jù)“Agent 消費(fèi)數(shù)據(jù)庫(kù)知識(shí)”這個(gè)具體場(chǎng)景定制的一套 JSON 約定。為什么不用現(xiàn)成的 schema registry 或者說(shuō)元數(shù)據(jù)模型因?yàn)槟切┠Ｐ兔嫦虻氖枪こ處煵皇敲嫦颉靶枰斫庹Z(yǔ)義的模型”。2.1 格式選型為什么是 JSON 渲染模板我一開(kāi)始考慮過(guò)直接用 Markdown 文件每一張表寫一段說(shuō)明。優(yōu)點(diǎn)是寫起來(lái)快但缺點(diǎn)是沒(méi)法程序化校驗(yàn)、沒(méi)法按字段檢索、沒(méi)法穩(wěn)定渲染成不同長(zhǎng)度的上下文。后來(lái)又試了 YAMLYAML 寫起來(lái)比 JSON 舒服但在代碼里做 schema 校驗(yàn)、嵌套校驗(yàn)時(shí)Pydantic 和 JSON 的配合最順。所以最終定的是JSON 作為知識(shí)包底層的“知識(shí)存儲(chǔ)格式”再加上一組渲染模板把 JSON 渲染成 Agent 真正讀到的文本片段。這里要區(qū)分兩個(gè)概念知識(shí)包是結(jié)構(gòu)化的底稿也就是 JSONAgent 消化的是渲染后的文本。底稿負(fù)責(zé)精確和無(wú)歧義渲染負(fù)責(zé)可讀和節(jié)省 token。你在 prompt 里給 Agent 看的永遠(yuǎn)是不超過(guò)幾百字的渲染結(jié)果而不是把整個(gè) JSON 丟過(guò)去。2.2 一張表的知識(shí)包長(zhǎng)什么樣一個(gè)最小可用的知識(shí)包大致長(zhǎng)這樣{ db: shop, version: 20250601, checksum: 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08, tables: [ { name: customers, schema: public, comment: 客戶主數(shù)據(jù)一客戶一行, fields: [ { name: id, type: bigint, nullable: false, comment: 客戶唯一標(biāo)識(shí), aliases: [customer_id, user_id], enum_values: null, sensitive: false }, { name: status, type: tinyint, nullable: true, comment: 客戶狀態(tài)枚舉, enum_values: { 0: 正常, 1: 已凍結(jié), 2: 已注銷 }, sensitive: false }, { name: email, type: varchar(128), nullable: true, comment: 登錄郵箱個(gè)人敏感信息, aliases: [mail], enum_values: null, sensitive: true } ], pk: [id] } ], relationships: [ { from: {table: orders, field: customer_id}, to: {table: customers, field: id}, cardinality: many-to-one } ], glossary: [ { term: 活躍客戶, definition: 近30天內(nèi)至少下單1次的客戶, tables: [customers, orders] } ], sample_queries: [ { scenario: 統(tǒng)計(jì)本月成交額, sql: select sum(amount) from orders where created_at date_trunc(month, current_date) } ], meta: { generated_by: okf_compiler, source_ddl: ddl/shop_20250601.sql } }這里每個(gè)字段項(xiàng)都盡量包含四個(gè)要素屬性定義、類型約束、業(yè)務(wù)注釋、候選別名。尤其aliases字段是給 Agent 用的——用戶可能會(huì)說(shuō)“客戶ID”“用戶ID”術(shù)語(yǔ)映射全部提前在知識(shí)包里做好Agent 就不用自己推斷。字段里的sensitive標(biāo)記也很重要。它不是為了阻止 Agent 使用字段而是讓 Agent 在生成 SQL 時(shí)意識(shí)到這個(gè)字段涉及隱私輸出結(jié)果時(shí)可以提示用戶脫敏。后面講 Agent 消費(fèi)時(shí)會(huì)再展開(kāi)。2.3 為什么關(guān)系必須顯式聲明只把每張表的信息做成 JSON 是不夠的Agent 經(jīng)常需要對(duì)多表 join而 join 恰恰是幻覺(jué)重災(zāi)區(qū)。我在知識(shí)包里單拎了一個(gè)relationships數(shù)組每條關(guān)系表達(dá)四類信息關(guān)聯(lián)方向、關(guān)聯(lián)字段、基數(shù)、業(yè)務(wù)約束。一開(kāi)始我以為從外鍵約束里提取關(guān)系就行結(jié)果發(fā)現(xiàn)很多線上表根本沒(méi)有外鍵兩個(gè)表之間的關(guān)聯(lián)純粹是業(yè)務(wù)約定。后來(lái)我在編譯器里加了一個(gè)補(bǔ)充輸入文件讓人維護(hù)這些說(shuō)明性的關(guān)系聲明。這是知識(shí)包區(qū)別于“自動(dòng)抓取元數(shù)據(jù)”的關(guān)鍵自動(dòng)抓取只能告訴你有什么知識(shí)包還要告訴你“為什么這兩個(gè)表能關(guān)聯(lián)”“關(guān)聯(lián)后統(tǒng)計(jì)口徑是什么”。這一層語(yǔ)義哪怕再?gòu)?qiáng)的解析器也猜不出來(lái)必須有人的輸入或已有的設(shè)計(jì)文檔參與。3. Python 編譯器的三層流水線DDL 到知識(shí)包之間發(fā)生了什么知識(shí)包的格式定了之后緊接著的問(wèn)題是怎么生成。手工維護(hù) JSON 不是不行但數(shù)據(jù)庫(kù)一變知識(shí)包就過(guò)時(shí)人很難每次都記得同步。所以我把整套流程做成了編譯器輸入是 DDL 和補(bǔ)充說(shuō)明文件輸出是知識(shí)包 JSON 和一份渲染好的上下文索引。3.1 流水線概覽編譯器內(nèi)部是一個(gè)純函數(shù)式的流水線一端進(jìn) SQL 文本另一端出知識(shí)包中間不訪問(wèn)數(shù)據(jù)庫(kù)。這么做的好處是可復(fù)現(xiàn)、可測(cè)試、不依賴環(huán)境。你只要把同一批輸入文件放進(jìn)去任何時(shí)候跑出來(lái)的知識(shí)包都一模一樣。我把流水線分成三層第一層是解析層負(fù)責(zé)把CREATE TABLE這種 DDL 拆成 AST抽取出表名、字段名、類型、可空性、默認(rèn)值、注釋、主鍵、外鍵。這一層不負(fù)責(zé)理解業(yè)務(wù)語(yǔ)義只負(fù)責(zé)把物理結(jié)構(gòu)變成中間表示。第二層是豐富層把解析結(jié)果和人工補(bǔ)充的語(yǔ)義說(shuō)明合并。比如在補(bǔ)充文件里寫著customers.status 字段枚舉0 正常 1 凍結(jié) 2 注銷編譯器就把這段文本翻譯成結(jié)構(gòu)化的enum_values掛到對(duì)應(yīng)字段上。這層還負(fù)責(zé)做歸一化字段別名統(tǒng)一小寫、全角轉(zhuǎn)半角、注釋去重等。第三層是輸出層把完整模型序列化成知識(shí)包 JSON同時(shí)用渲染模板生成面向 Agent 的文本片段最后計(jì)算整個(gè)知識(shí)包的 checksum 寫入meta字段。3.2 項(xiàng)目模塊結(jié)構(gòu)編譯器本身是一個(gè) Python 包典型布局如下okf_compiler/ ├── cli.py # 命令行入口 ├── parser_sql.py # 解析 DDL 的 token/AST 邏輯 ├── models.py # Pydantic 數(shù)據(jù)模型對(duì)應(yīng)知識(shí)包 schema ├── enrich.py # 合并人工語(yǔ)義說(shuō)明、校驗(yàn)一致性 ├── renderer.py # 渲染 Agent 可讀的上下文文本 ├── validator.py # 知識(shí)包合法性校驗(yàn) └── artifact/ └── templates/ ├── table.j2 # 單表文本模板 └── relationship.j2 # 關(guān)系文本模板為什么用 Python 而不是 Node 或者 Go原因很務(wù)實(shí)Python 生態(tài)里sqlparse、pydantic、jinja2這三個(gè)庫(kù)加起來(lái)幾乎覆蓋了解析、校驗(yàn)、渲染的全部需求。sqlparse 能粗粒度地把 SQL 拆成語(yǔ)句和 token 流雖然它不做完整的 AST 語(yǔ)義分析但對(duì)付建表語(yǔ)句已經(jīng)夠用。pydantic 能給知識(shí)包做嚴(yán)格的類型校驗(yàn)——字段類型寫錯(cuò)、枚舉值類型不匹配編譯期就會(huì)報(bào)錯(cuò)而不是等到 Agent 用的時(shí)候才暴露。jinja2 負(fù)責(zé)把結(jié)構(gòu)化數(shù)據(jù)渲染成文本模板模板里可以控制講多少細(xì)節(jié)、用多大篇幅。這里還有一個(gè)容易忽略的設(shè)計(jì)點(diǎn)編譯器必須是無(wú)狀態(tài)的。我沒(méi)有在項(xiàng)目里引入任何數(shù)據(jù)庫(kù)連接沒(méi)有在運(yùn)行時(shí)去SHOW COLUMNS。為什么不呢第一很多數(shù)據(jù)庫(kù)權(quán)限受限Agent 的賬號(hào)可能根本沒(méi)有讀元數(shù)據(jù)的權(quán)限第二DDL 文件本身就是事實(shí)來(lái)源之一如果運(yùn)行時(shí)再查一遍庫(kù)兩份事實(shí)不一致時(shí)你根本不知道以誰(shuí)為準(zhǔn)。凡是加入不確定性的環(huán)節(jié)都會(huì)讓后續(xù)排查變得困難。4. 核心代碼實(shí)戰(zhàn)從建表語(yǔ)句里蒸出知識(shí)片段接下來(lái)進(jìn)入真正能抄的部分。下面這幾段代碼就是我項(xiàng)目里最核心的編譯邏輯簡(jiǎn)略了很多錯(cuò)誤處理但骨架是完整的。4.1 解析一條 CREATE TABLE解析我首選sqlparse。它的 AST 不如商業(yè)級(jí)解析器那么深但好處是容錯(cuò)性好不會(huì)因?yàn)橐粌蓚€(gè)語(yǔ)法怪癖直接崩掉。做一個(gè) DDL 編譯器穩(wěn)定比完整更重要。import sqlparse from sqlparse.sql import IdentifierList, Identifier from sqlparse.tokens import Keyword, Name, Punctuation def extract_create_table(statements): for stmt in statements: if not stmt.get_type() CREATE: continue tokens [t for t in stmt.tokens if not t.is_whitespace] table_name None columns [] started_columns False for token in tokens: if token.match(Keyword, TABLE): # 下一個(gè)非關(guān)鍵字的 token 通常就是表名 for t in tokens: if isinstance(t, Identifier) and not table_name: table_name t.get_real_name() continue if token.match(Punctuation, (): started_columns True elif started_columns: if isinstance(token, IdentifierList): for item in token.get_identifiers(): cols _extract_column(item) if cols: columns.append(cols) elif isinstance(token, Identifier): cols _extract_column(token) if cols: columns.append(cols) if table_name: yield {table: table_name, columns: columns} def _extract_column(identifier): # 以 status tinyint 這類簡(jiǎn)單字段為主太復(fù)雜的語(yǔ)法暫時(shí)跳過(guò) tokens [t for t in identifier.tokens if not t.is_whitespace] name tokens[0].value if tokens else None type_token for t in tokens[1:]: if t.is_keyword and t.value.upper() in (NOT, NULL, DEFAULT, COMMENT, PRIMARY, KEY, UNIQUE): break type_token t.value return {name: name, type: type_token.strip().lower()}這段代碼不追求解析完美主打“常見(jiàn)建表語(yǔ)句都能被拆干凈”。我建議你設(shè)計(jì)解析邏輯時(shí)只承諾四種能力取到表名、取到字段名、取到字段類型、取到字段注釋。主鍵、外鍵、默認(rèn)值這些信息能解析出來(lái)就解析解析不出來(lái)的寧可交給人工補(bǔ)充文件也不要在解析器里硬寫一堆正則去猜。4.2 業(yè)務(wù)語(yǔ)義注入光有 DDL 遠(yuǎn)遠(yuǎn)不夠解析完只是拿到了結(jié)構(gòu)下一步要把業(yè)務(wù)術(shù)語(yǔ)掛載上去。我專門維護(hù)了一個(gè)enrich.yaml文件讓會(huì)寫 SQL 但不想動(dòng)代碼的同事也能往里加業(yè)務(wù)描述tables: customers: comment: 客戶主數(shù)據(jù)一客戶一行 fields: status: comment: 客戶狀態(tài)枚舉 enums: 0: 正常 1: 已凍結(jié) 2: 已注銷 email: aliases: [mail] sensitive: true relationships: - from: orders.customer_id to: customers.id cardinality: many-to-one note: 訂單表通過(guò) customer_id 指向客戶主數(shù)據(jù)不允許存在孤兒訂單 glossary: - term: 活躍客戶 definition: 近30天內(nèi)至少下單1次的客戶 related_tables: [customers, orders]然后是豐富層合并代碼from pydantic import BaseModel class FieldMeta(BaseModel): name: str type: str nullable: bool True comment: str | None None aliases: list[str] [] enum_values: dict[str, str] | None None sensitive: bool False class TableMeta(BaseModel): name: str schema: str | None None comment: str | None None fields: list[FieldMeta] pk: list[str] [] def merge_meta(parsed_table: dict, enrich_cfg: dict) - TableMeta: table_name parsed_table[table] cfg enrich_cfg[tables].get(table_name, {}) field_cfgs cfg.get(fields, {}) fields [] for raw_field in parsed_table[columns]: fcfg field_cfgs.get(raw_field[name], {}) fields.append( FieldMeta( nameraw_field[name], typeraw_field[type], commentfcfg.get(comment), aliasesfcfg.get(aliases, []), enum_valuesfcfg.get(enums), sensitivefcfg.get(sensitive, False), ) ) return TableMeta( nametable_name, schemacfg.get(schema), commentcfg.get(comment), fieldsfields, pkcfg.get(pk, []), )這一段干的事很樸素但我認(rèn)為這是整個(gè)項(xiàng)目里價(jià)值密度最高的一段把人類腦子里的業(yè)務(wù)約定轉(zhuǎn)成機(jī)器可讀的數(shù)據(jù)。沒(méi)這一步知識(shí)包和普通的information_schema導(dǎo)出的元數(shù)據(jù)就沒(méi)有本質(zhì)區(qū)別。4.3 渲染成 Agent 直接消費(fèi)的文本知識(shí)包里面存儲(chǔ)用 JSON但真正喂給 Agent 的是渲染后的文本。渲染模板我放在 jinja2 里保存成table.j2## Table: {{ table.name }}{{ table.schema or public }} {{ table.comment or }} 字段列表 {% for f in table.fields -%} - {{ f.name }}{{ f.comment or 暫無(wú)說(shuō)明 }}{{ f.type }}{% if not f.nullable %}非空{(diào)% else %}可空{(diào)% endif %} {% if f.enum_values %} 枚舉值 {% for k, v in f.enum_values.items() %} - {{ k }} {{ v }} {% endfor %} {% endif %} {% if f.aliases %} 別稱{{ f.aliases | join(, ) }}{% endif %} {% if f.sensitive %} 敏感字段生成 SQL 與展示結(jié)果時(shí)須提示脫敏{% endif %} {% endfor %} 關(guān)聯(lián)關(guān)系 {% for r in table.relations -%} - {{ r.from.table }}.{{ r.from.field }} - {{ r.to.table }}.{{ r.to.field }}{{ r.cardinality }} {% endfor %}渲染出來(lái)的效果就是 Agent 真正讀到的一段文本比如## Table: customerspublic 客戶主數(shù)據(jù)一客戶一行 字段列表 - id客戶唯一標(biāo)識(shí)bigint非空 - status客戶狀態(tài)枚舉tinyint可空 枚舉值 - 0 正常 - 1 已凍結(jié) - 2 已注銷 - email登錄郵箱個(gè)人敏感信息varchar(128)可空 別稱mail 敏感字段生成 SQL 與展示結(jié)果時(shí)須提示脫敏 關(guān)聯(lián)關(guān)系 - orders.customer_id - customers.idmany-to-one這段文本的核心價(jià)值在于它完全貼近“一個(gè)數(shù)據(jù)庫(kù) DBA 給新人講解業(yè)務(wù)時(shí)說(shuō)的話”而不是SHOW CREATE TABLE吐出來(lái)的冷冰冰的物理定義。5. 讓 Agent 真正用起來(lái)知識(shí)包的檢索與上下文裝配知識(shí)包編譯出來(lái)了不接進(jìn) Agent 的調(diào)用鏈路里就等于白做。我項(xiàng)目里接的方式不是全文塞 prompt而是按需檢索。Agent 需要知道哪張表的信息才把哪張表的知識(shí)片段取出來(lái)。5.1 上下文太長(zhǎng)按需檢索假設(shè)你有 20 張表渲染后的全文可能有 5000 個(gè) token。全部塞進(jìn)系統(tǒng)提示Agent 會(huì)長(zhǎng)篇大論地注意到無(wú)關(guān)表還浪費(fèi)預(yù)算。正確的做法是把每張表的知識(shí)片段作為一個(gè)獨(dú)立的“檢索單元”用戶提問(wèn)時(shí)先做一次粗粒度檢索只取最相關(guān)的三五張表。我自己用的是純 Python 實(shí)現(xiàn)的輕量檢索沒(méi)有上向量數(shù)據(jù)庫(kù)。為什么知識(shí)包本身是高度結(jié)構(gòu)化的文本關(guān)鍵詞重疊度已經(jīng)能匹配得很好用戶問(wèn)“本月活躍客戶”分詞后命中的是“活躍客戶”“客戶”“customers”這個(gè)信號(hào)足夠強(qiáng)。向量檢索適合語(yǔ)義距離遠(yuǎn)但表達(dá)相似的內(nèi)容而數(shù)據(jù)庫(kù)知識(shí)包恰恰要避免這種模糊匹配。簡(jiǎn)單方案可控、無(wú)額外服務(wù)對(duì)于中小規(guī)模的庫(kù)完全夠用。檢索的輸入輸出很像一個(gè)工具函數(shù)def retrieve_knowledge_package(query: str, index: dict, top_k: int 3) - list[str]: tokens tokenize(query) scored [] for table_name, block in index.items(): score sum(1 for t in tokens if t in block.lower()) scored.append((score, table_name, block)) scored.sort(reverseTrue, keylambda x: (x[0], len(x[1]))) return [block for _, _, block in scored[:top_k] if _ 0]這段代碼沒(méi)什么黑魔法。但它把關(guān)鍵的一件事做了讓 Agent 在收到具體任務(wù)之前已經(jīng)拿到它應(yīng)該看哪幾張表的提示。5.2 把知識(shí)包掛進(jìn)工具函數(shù)與提示詞僅僅檢索還不夠要讓 Agent 在工具調(diào)用時(shí)真正“想到”去用。我注冊(cè)給 Agent 的工具有兩個(gè)def get_table_context(table_name: str) - str: 返回指定表的業(yè)務(wù)語(yǔ)義、字段枚舉、關(guān)聯(lián)關(guān)系等知識(shí)包片段 return render_table_block(table_name) def run_sql(sql: str) - list[dict]: 執(zhí)行只讀 SQL 查詢禁止修改操作 ...在系統(tǒng)提示詞里我會(huì)寫清楚使用順序先調(diào)用get_table_context獲取相關(guān)表的上下文再基于上下文寫 SQL最后調(diào)用run_sql。這是很典型的 ReAct 模式但關(guān)鍵不在于模式本身而在于get_table_context返回的內(nèi)容質(zhì)量。如果它返回的只是字段列表Agent 依然要猜如果返回的是帶枚舉、帶別名、帶關(guān)系提醒的知識(shí)片段Agent 寫出錯(cuò)誤 join 的概率就會(huì)顯著下降。我再補(bǔ)一個(gè)經(jīng)常被忽略的細(xì)節(jié)知識(shí)包里不應(yīng)包含真實(shí)數(shù)據(jù)只能包含結(jié)構(gòu)和語(yǔ)義。真實(shí)數(shù)據(jù)可能涉及隱私而且體積不可控。知識(shí)包只做“地圖”Agent 運(yùn)行 SQL 之后拿到的結(jié)果才是“現(xiàn)場(chǎng)”。地圖和現(xiàn)場(chǎng)分離權(quán)限控制和數(shù)據(jù)安全都好做很多。6. 踩坑記錄與邊界控制什么情況下別硬上編譯器最后這部分是最想分享的。項(xiàng)目整體跑通不難但中間有不少?zèng)Q策如果重新來(lái)一遍我會(huì)做得更果斷。6.1 解析 SQL 的“80% 原則”第一個(gè)坑是過(guò)度追求解析器的完整度。我一開(kāi)始想讓解析器支持存儲(chǔ)生成列、分區(qū)表、復(fù)雜默認(rèn)表達(dá)式、索引定義結(jié)果一周時(shí)間全耗在這個(gè)上面真正的知識(shí)包結(jié)構(gòu)反而沒(méi)怎么動(dòng)。后來(lái)我把解析目標(biāo)砍到只剩四件事表名、字段名、字段類型、基礎(chǔ)注釋。凡是解析不了的直接跳過(guò)并打一條 warning在編譯日志里標(biāo)出來(lái)讓人工補(bǔ)充文件去兜底。這里分享一個(gè)判斷標(biāo)準(zhǔn)知識(shí)包的錯(cuò)誤容忍策略應(yīng)該和 Agent 的容錯(cuò)能力匹配。Agent 本身就很擅長(zhǎng)從自由文本里抓重點(diǎn)你不需要給它一個(gè) 100% 精確的 AST你只需要給它 80% 的準(zhǔn)確結(jié)構(gòu)加上 20% 的人工兜底效果就會(huì)好過(guò)追求完美解析。把精力花在補(bǔ)全業(yè)務(wù)語(yǔ)義上回報(bào)比高得多。6.2 包失效與重建策略checksum 和 CI第二個(gè)坑是知識(shí)包不同步。數(shù)據(jù)庫(kù)的 DDL 一改知識(shí)包還是舊版本Agent 拿到舊信息去查新表必然出錯(cuò)。我用兩招解決。第一招是給知識(shí)包打 checksum。編譯時(shí)把所有輸入文件拼接后算一個(gè)哈希存在知識(shí)包meta.checksum里。每次 Agent 加載知識(shí)包時(shí)先核對(duì)發(fā)現(xiàn)不對(duì)就提示“知識(shí)包已過(guò)期需要重新編譯”。這一步成本極低但能避免很多詭異的線上問(wèn)題。第二招是把編譯過(guò)程接進(jìn) CI。我現(xiàn)在的做法是數(shù)據(jù)庫(kù)的 DDL 遷移腳本一提交流水線自動(dòng)跑一次編譯器。編譯失敗或者 checksum 變化都會(huì)在合并請(qǐng)求里直接標(biāo)出來(lái)。這樣知識(shí)包始終跟隨數(shù)據(jù)庫(kù)結(jié)構(gòu)版本走而不是靠某個(gè)人想起來(lái)手動(dòng)更新。變更類型知識(shí)包是否需要重建說(shuō)明新增一張表需要新表可能被 Agent 需要新增/刪除字段需要字段列表變化修改字段注釋/枚舉需要語(yǔ)義變化是重構(gòu)核心只改索引或分區(qū)不需要Agent 不需要感知物理優(yōu)化只有數(shù)據(jù)量變化不需要結(jié)構(gòu)層知識(shí)包不存數(shù)據(jù)統(tǒng)計(jì)6.3 什么時(shí)候不要搞知識(shí)包編譯器最后一個(gè)建議可能有點(diǎn)反直覺(jué)表數(shù)量很少、結(jié)構(gòu)非常穩(wěn)定的項(xiàng)目不要上編譯器。如果是五六張表手動(dòng)寫 JSON 或 Markdown 可能只需要半天而編譯器需要寫解析邏輯、寫合并邏輯、寫渲染模板、配 CI整套下來(lái)怎么也要一兩周。我判斷是否值得搞知識(shí)包編譯器的三個(gè)條件表數(shù)量超過(guò)兩位數(shù)表結(jié)構(gòu)在持續(xù)演進(jìn)你確實(shí)要把數(shù)據(jù)庫(kù)能力開(kāi)放給 Agent 做自動(dòng)化查詢。三個(gè)條件至少滿足兩個(gè)才值得投入。如果只是給一個(gè)固定報(bào)表的數(shù)據(jù)庫(kù)接個(gè)問(wèn)答 Demo那直接把業(yè)務(wù)口徑寫成一小段提示詞塞進(jìn)系統(tǒng)提示里比做知識(shí)包高效得多。反過(guò)來(lái)如果目標(biāo)是讓 Agent 自主探索一個(gè)持續(xù)變化的數(shù)據(jù)倉(cāng)庫(kù)那么沒(méi)有知識(shí)包的 Agent 就是一臺(tái)沒(méi)有地圖的自動(dòng)駕駛車遲早撞墻。我個(gè)人的體會(huì)是這個(gè)項(xiàng)目最有價(jià)值的部分不是那幾千行 Python 代碼而是它逼著我把數(shù)據(jù)庫(kù)的“隱性知識(shí)”顯式化了。過(guò)去 DBA 腦子里那點(diǎn)東西——哪個(gè)字段是敏感字段、哪張表和哪張表能用軟關(guān)聯(lián)、字段枚舉到底什么含義——現(xiàn)在全部變成了一份可以版本管理、可以自動(dòng)校驗(yàn)、可以隨時(shí)渲染給 Agent 看的知識(shí)包。從此 Agent 學(xué)到的不是猜出來(lái)的表結(jié)構(gòu)而是這個(gè)數(shù)據(jù)庫(kù)真實(shí)運(yùn)行的業(yè)務(wù)規(guī)則。如果你也在做類似的事情建議先別急著調(diào)大模型先把數(shù)據(jù)庫(kù)知識(shí)管好后面所有環(huán)節(jié)都會(huì)輕松很多。 為Agent編譯數(shù)據(jù)庫(kù)知識(shí)包：從DDL到OKF的工程實(shí)踐
第二次讓 Agent 直接連數(shù)據(jù)庫(kù)做查詢它把訂單表和客戶表的關(guān)聯(lián)字段猜錯(cuò)了當(dāng)天晚上我收到一排告警。那一刻我才想明白把一堆CREATE TABLE丟給 Agent跟把一本沒(méi)有目錄、沒(méi)有注釋的字典丟給新來(lái)的實(shí)習(xí)生本質(zhì)沒(méi)有區(qū)別。后來(lái)我花了兩周時(shí)間寫了一個(gè) Python 編譯器把 DDL、業(yè)務(wù)術(shù)語(yǔ)、字段枚舉、關(guān)系強(qiáng)弱這些信息統(tǒng)一編譯成一份Agent 就緒的數(shù)據(jù)庫(kù) OKF 知識(shí)包。這套東西不解決“怎么寫 SQL”它解決的是“怎么讓 Agent 在寫 SQL 之前真的讀懂?dāng)?shù)據(jù)庫(kù)”。這篇文章就把這個(gè)項(xiàng)目的完整思路拆開(kāi)講為什么要從 DDL 里編譯知識(shí)包而不是直接讓 Agent 問(wèn)元數(shù)據(jù)接口、知識(shí)包內(nèi)部結(jié)構(gòu)怎么設(shè)計(jì)、編譯器流水線怎么搭、Agent 側(cè)怎么消費(fèi)以及我踩過(guò)的那些低級(jí)的坑。適合正在搭 Agent 數(shù)據(jù)助手、或者準(zhǔn)備把數(shù)據(jù)庫(kù)能力開(kāi)放給大模型工具鏈的人參考。1. 為什么 Agent 接數(shù)據(jù)庫(kù)之前先要有一份 OKF 知識(shí)包先說(shuō)一個(gè)最直接的體感。讓 Agent 調(diào)用數(shù)據(jù)庫(kù)工具時(shí)大多數(shù)實(shí)現(xiàn)就是把表名、列名、類型、主鍵外鍵這些元數(shù)據(jù)拼進(jìn) prompt或者讓 Agent 自己SHOW TABLES之后去猜。我的項(xiàng)目前三天就是這么干的效果非常糟糕。1.1 表結(jié)構(gòu)信息與業(yè)務(wù)語(yǔ)義之間的斷層數(shù)據(jù)庫(kù)表結(jié)構(gòu)天然缺三塊東西第一塊是字段的業(yè)務(wù)含義。customer_id到底是下單客戶還是收貨聯(lián)系人status字段是 0 表示正常還是 1 表示正常這類信息在 DDL 里往往只有一個(gè)字段名再看一眼類型沒(méi)了。Agent 面對(duì)這種信息缺口它只會(huì)靠大模型預(yù)訓(xùn)練時(shí)積累的“通用常識(shí)”去腦補(bǔ)而通用常識(shí)和數(shù)據(jù)倉(cāng)庫(kù)的真實(shí)業(yè)務(wù)往往不是一回事。第二塊是枚舉值和取值邏輯。很多表用 tinyint 存狀態(tài)DDL 里根本不寫0 代表什么、1 代表什么。Agent 一旦猜錯(cuò)生成的 SQL 雖然語(yǔ)法完全正確查出來(lái)的業(yè)務(wù)口徑卻是全錯(cuò)的。這類問(wèn)題比語(yǔ)法報(bào)錯(cuò)隱蔽得多因?yàn)镾QL跑得通、結(jié)果也非空但就是不對(duì)。第三塊是表與表之間的真實(shí)關(guān)系。外鍵約束寫得很清楚的庫(kù)是少數(shù)更多場(chǎng)景里兩個(gè)表靠一個(gè)名叫code的字段軟關(guān)聯(lián)業(yè)務(wù)上卻是一對(duì)多。Agent 看不到業(yè)務(wù)約束就很容易把關(guān)聯(lián)方向搞反或者在一張寬表上本來(lái)能直接過(guò)濾它偏要去 join 一張外表。1.2 直接拼 DDL 為什么不經(jīng)濟(jì)有人會(huì)說(shuō)那把 DDL 全文貼進(jìn) prompt 不就行了我也試過(guò)。一個(gè)稍微規(guī)范一點(diǎn)的庫(kù)十來(lái)張表DDL 加起來(lái)幾千行很正常。塞進(jìn)上下文之后Agent 確實(shí)能“看到”字段但注意它看到的是純物理結(jié)構(gòu)不是認(rèn)知結(jié)構(gòu)。DDL 里有大量 Agent 不需要關(guān)心的內(nèi)容存儲(chǔ)配置、索引定義、字符集、分區(qū)策略。這些內(nèi)容不僅浪費(fèi) token還會(huì)干擾它對(duì)核心語(yǔ)義的聚焦。還有一個(gè)問(wèn)題物理結(jié)構(gòu)有歧義。同一條 MySQL 的CREATE TABLE語(yǔ)句在不同版本里字段類型寫法不一樣注釋可能寫了一大段也可能完全沒(méi)有。你無(wú)法保證 Agent 每次能從這些原始文本里穩(wěn)定提取出同樣的信息。而知識(shí)包提供的是經(jīng)過(guò)清洗、歸一化、補(bǔ)全之后的確定性產(chǎn)物同一份 DDL 輸入永遠(yuǎn)編譯出同一份知識(shí)包。這樣你至少能控制 Agent 拿到手的數(shù)據(jù)庫(kù)畫像是一致的不會(huì)因?yàn)槟Ｐ托那椴煌鴮?duì)同一張表產(chǎn)生兩種理解。所以這個(gè)項(xiàng)目我給自己定的目標(biāo)是把數(shù)據(jù)庫(kù)知識(shí)的構(gòu)建從“讓模型臨場(chǎng)發(fā)揮”變成“預(yù)先編譯、按需檢索”。這也是 “Agent 就緒的數(shù)據(jù)庫(kù) OKF 知識(shí)包” 這個(gè)名字的由來(lái)——先有格式再有編譯器最后才談 Agent。2. OKF 知識(shí)包長(zhǎng)什么樣我給數(shù)據(jù)結(jié)構(gòu)定了哪些規(guī)矩OKF 是我在項(xiàng)目?jī)?nèi)部給這套知識(shí)包格式起的代號(hào)全稱是 Open Knowledge Format。它不是公開(kāi)標(biāo)準(zhǔn)而是我根據(jù)“Agent 消費(fèi)數(shù)據(jù)庫(kù)知識(shí)”這個(gè)具體場(chǎng)景定制的一套 JSON 約定。為什么不用現(xiàn)成的 schema registry 或者說(shuō)元數(shù)據(jù)模型因?yàn)槟切┠Ｐ兔嫦虻氖枪こ處煵皇敲嫦颉靶枰斫庹Z(yǔ)義的模型”。2.1 格式選型為什么是 JSON 渲染模板我一開(kāi)始考慮過(guò)直接用 Markdown 文件每一張表寫一段說(shuō)明。優(yōu)點(diǎn)是寫起來(lái)快但缺點(diǎn)是沒(méi)法程序化校驗(yàn)、沒(méi)法按字段檢索、沒(méi)法穩(wěn)定渲染成不同長(zhǎng)度的上下文。后來(lái)又試了 YAMLYAML 寫起來(lái)比 JSON 舒服但在代碼里做 schema 校驗(yàn)、嵌套校驗(yàn)時(shí)Pydantic 和 JSON 的配合最順。所以最終定的是JSON 作為知識(shí)包底層的“知識(shí)存儲(chǔ)格式”再加上一組渲染模板把 JSON 渲染成 Agent 真正讀到的文本片段。這里要區(qū)分兩個(gè)概念知識(shí)包是結(jié)構(gòu)化的底稿也就是 JSONAgent 消化的是渲染后的文本。底稿負(fù)責(zé)精確和無(wú)歧義渲染負(fù)責(zé)可讀和節(jié)省 token。你在 prompt 里給 Agent 看的永遠(yuǎn)是不超過(guò)幾百字的渲染結(jié)果而不是把整個(gè) JSON 丟過(guò)去。2.2 一張表的知識(shí)包長(zhǎng)什么樣一個(gè)最小可用的知識(shí)包大致長(zhǎng)這樣{ db: shop, version: 20250601, checksum: 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08, tables: [ { name: customers, schema: public, comment: 客戶主數(shù)據(jù)一客戶一行, fields: [ { name: id, type: bigint, nullable: false, comment: 客戶唯一標(biāo)識(shí), aliases: [customer_id, user_id], enum_values: null, sensitive: false }, { name: status, type: tinyint, nullable: true, comment: 客戶狀態(tài)枚舉, enum_values: { 0: 正常, 1: 已凍結(jié), 2: 已注銷 }, sensitive: false }, { name: email, type: varchar(128), nullable: true, comment: 登錄郵箱個(gè)人敏感信息, aliases: [mail], enum_values: null, sensitive: true } ], pk: [id] } ], relationships: [ { from: {table: orders, field: customer_id}, to: {table: customers, field: id}, cardinality: many-to-one } ], glossary: [ { term: 活躍客戶, definition: 近30天內(nèi)至少下單1次的客戶, tables: [customers, orders] } ], sample_queries: [ { scenario: 統(tǒng)計(jì)本月成交額, sql: select sum(amount) from orders where created_at date_trunc(month, current_date) } ], meta: { generated_by: okf_compiler, source_ddl: ddl/shop_20250601.sql } }這里每個(gè)字段項(xiàng)都盡量包含四個(gè)要素屬性定義、類型約束、業(yè)務(wù)注釋、候選別名。尤其aliases字段是給 Agent 用的——用戶可能會(huì)說(shuō)“客戶ID”“用戶ID”術(shù)語(yǔ)映射全部提前在知識(shí)包里做好Agent 就不用自己推斷。字段里的sensitive標(biāo)記也很重要。它不是為了阻止 Agent 使用字段而是讓 Agent 在生成 SQL 時(shí)意識(shí)到這個(gè)字段涉及隱私輸出結(jié)果時(shí)可以提示用戶脫敏。后面講 Agent 消費(fèi)時(shí)會(huì)再展開(kāi)。2.3 為什么關(guān)系必須顯式聲明只把每張表的信息做成 JSON 是不夠的Agent 經(jīng)常需要對(duì)多表 join而 join 恰恰是幻覺(jué)重災(zāi)區(qū)。我在知識(shí)包里單拎了一個(gè)relationships數(shù)組每條關(guān)系表達(dá)四類信息關(guān)聯(lián)方向、關(guān)聯(lián)字段、基數(shù)、業(yè)務(wù)約束。一開(kāi)始我以為從外鍵約束里提取關(guān)系就行結(jié)果發(fā)現(xiàn)很多線上表根本沒(méi)有外鍵兩個(gè)表之間的關(guān)聯(lián)純粹是業(yè)務(wù)約定。后來(lái)我在編譯器里加了一個(gè)補(bǔ)充輸入文件讓人維護(hù)這些說(shuō)明性的關(guān)系聲明。這是知識(shí)包區(qū)別于“自動(dòng)抓取元數(shù)據(jù)”的關(guān)鍵自動(dòng)抓取只能告訴你有什么知識(shí)包還要告訴你“為什么這兩個(gè)表能關(guān)聯(lián)”“關(guān)聯(lián)后統(tǒng)計(jì)口徑是什么”。這一層語(yǔ)義哪怕再?gòu)?qiáng)的解析器也猜不出來(lái)必須有人的輸入或已有的設(shè)計(jì)文檔參與。3. Python 編譯器的三層流水線DDL 到知識(shí)包之間發(fā)生了什么知識(shí)包的格式定了之后緊接著的問(wèn)題是怎么生成。手工維護(hù) JSON 不是不行但數(shù)據(jù)庫(kù)一變知識(shí)包就過(guò)時(shí)人很難每次都記得同步。所以我把整套流程做成了編譯器輸入是 DDL 和補(bǔ)充說(shuō)明文件輸出是知識(shí)包 JSON 和一份渲染好的上下文索引。3.1 流水線概覽編譯器內(nèi)部是一個(gè)純函數(shù)式的流水線一端進(jìn) SQL 文本另一端出知識(shí)包中間不訪問(wèn)數(shù)據(jù)庫(kù)。這么做的好處是可復(fù)現(xiàn)、可測(cè)試、不依賴環(huán)境。你只要把同一批輸入文件放進(jìn)去任何時(shí)候跑出來(lái)的知識(shí)包都一模一樣。我把流水線分成三層第一層是解析層負(fù)責(zé)把CREATE TABLE這種 DDL 拆成 AST抽取出表名、字段名、類型、可空性、默認(rèn)值、注釋、主鍵、外鍵。這一層不負(fù)責(zé)理解業(yè)務(wù)語(yǔ)義只負(fù)責(zé)把物理結(jié)構(gòu)變成中間表示。第二層是豐富層把解析結(jié)果和人工補(bǔ)充的語(yǔ)義說(shuō)明合并。比如在補(bǔ)充文件里寫著customers.status 字段枚舉0 正常 1 凍結(jié) 2 注銷編譯器就把這段文本翻譯成結(jié)構(gòu)化的enum_values掛到對(duì)應(yīng)字段上。這層還負(fù)責(zé)做歸一化字段別名統(tǒng)一小寫、全角轉(zhuǎn)半角、注釋去重等。第三層是輸出層把完整模型序列化成知識(shí)包 JSON同時(shí)用渲染模板生成面向 Agent 的文本片段最后計(jì)算整個(gè)知識(shí)包的 checksum 寫入meta字段。3.2 項(xiàng)目模塊結(jié)構(gòu)編譯器本身是一個(gè) Python 包典型布局如下okf_compiler/ ├── cli.py # 命令行入口 ├── parser_sql.py # 解析 DDL 的 token/AST 邏輯 ├── models.py # Pydantic 數(shù)據(jù)模型對(duì)應(yīng)知識(shí)包 schema ├── enrich.py # 合并人工語(yǔ)義說(shuō)明、校驗(yàn)一致性 ├── renderer.py # 渲染 Agent 可讀的上下文文本 ├── validator.py # 知識(shí)包合法性校驗(yàn) └── artifact/ └── templates/ ├── table.j2 # 單表文本模板 └── relationship.j2 # 關(guān)系文本模板為什么用 Python 而不是 Node 或者 Go原因很務(wù)實(shí)Python 生態(tài)里sqlparse、pydantic、jinja2這三個(gè)庫(kù)加起來(lái)幾乎覆蓋了解析、校驗(yàn)、渲染的全部需求。sqlparse 能粗粒度地把 SQL 拆成語(yǔ)句和 token 流雖然它不做完整的 AST 語(yǔ)義分析但對(duì)付建表語(yǔ)句已經(jīng)夠用。pydantic 能給知識(shí)包做嚴(yán)格的類型校驗(yàn)——字段類型寫錯(cuò)、枚舉值類型不匹配編譯期就會(huì)報(bào)錯(cuò)而不是等到 Agent 用的時(shí)候才暴露。jinja2 負(fù)責(zé)把結(jié)構(gòu)化數(shù)據(jù)渲染成文本模板模板里可以控制講多少細(xì)節(jié)、用多大篇幅。這里還有一個(gè)容易忽略的設(shè)計(jì)點(diǎn)編譯器必須是無(wú)狀態(tài)的。我沒(méi)有在項(xiàng)目里引入任何數(shù)據(jù)庫(kù)連接沒(méi)有在運(yùn)行時(shí)去SHOW COLUMNS。為什么不呢第一很多數(shù)據(jù)庫(kù)權(quán)限受限Agent 的賬號(hào)可能根本沒(méi)有讀元數(shù)據(jù)的權(quán)限第二DDL 文件本身就是事實(shí)來(lái)源之一如果運(yùn)行時(shí)再查一遍庫(kù)兩份事實(shí)不一致時(shí)你根本不知道以誰(shuí)為準(zhǔn)。凡是加入不確定性的環(huán)節(jié)都會(huì)讓后續(xù)排查變得困難。4. 核心代碼實(shí)戰(zhàn)從建表語(yǔ)句里蒸出知識(shí)片段接下來(lái)進(jìn)入真正能抄的部分。下面這幾段代碼就是我項(xiàng)目里最核心的編譯邏輯簡(jiǎn)略了很多錯(cuò)誤處理但骨架是完整的。4.1 解析一條 CREATE TABLE解析我首選sqlparse。它的 AST 不如商業(yè)級(jí)解析器那么深但好處是容錯(cuò)性好不會(huì)因?yàn)橐粌蓚€(gè)語(yǔ)法怪癖直接崩掉。做一個(gè) DDL 編譯器穩(wěn)定比完整更重要。import sqlparse from sqlparse.sql import IdentifierList, Identifier from sqlparse.tokens import Keyword, Name, Punctuation def extract_create_table(statements): for stmt in statements: if not stmt.get_type() CREATE: continue tokens [t for t in stmt.tokens if not t.is_whitespace] table_name None columns [] started_columns False for token in tokens: if token.match(Keyword, TABLE): # 下一個(gè)非關(guān)鍵字的 token 通常就是表名 for t in tokens: if isinstance(t, Identifier) and not table_name: table_name t.get_real_name() continue if token.match(Punctuation, (): started_columns True elif started_columns: if isinstance(token, IdentifierList): for item in token.get_identifiers(): cols _extract_column(item) if cols: columns.append(cols) elif isinstance(token, Identifier): cols _extract_column(token) if cols: columns.append(cols) if table_name: yield {table: table_name, columns: columns} def _extract_column(identifier): # 以 status tinyint 這類簡(jiǎn)單字段為主太復(fù)雜的語(yǔ)法暫時(shí)跳過(guò) tokens [t for t in identifier.tokens if not t.is_whitespace] name tokens[0].value if tokens else None type_token for t in tokens[1:]: if t.is_keyword and t.value.upper() in (NOT, NULL, DEFAULT, COMMENT, PRIMARY, KEY, UNIQUE): break type_token t.value return {name: name, type: type_token.strip().lower()}這段代碼不追求解析完美主打“常見(jiàn)建表語(yǔ)句都能被拆干凈”。我建議你設(shè)計(jì)解析邏輯時(shí)只承諾四種能力取到表名、取到字段名、取到字段類型、取到字段注釋。主鍵、外鍵、默認(rèn)值這些信息能解析出來(lái)就解析解析不出來(lái)的寧可交給人工補(bǔ)充文件也不要在解析器里硬寫一堆正則去猜。4.2 業(yè)務(wù)語(yǔ)義注入光有 DDL 遠(yuǎn)遠(yuǎn)不夠解析完只是拿到了結(jié)構(gòu)下一步要把業(yè)務(wù)術(shù)語(yǔ)掛載上去。我專門維護(hù)了一個(gè)enrich.yaml文件讓會(huì)寫 SQL 但不想動(dòng)代碼的同事也能往里加業(yè)務(wù)描述tables: customers: comment: 客戶主數(shù)據(jù)一客戶一行 fields: status: comment: 客戶狀態(tài)枚舉 enums: 0: 正常 1: 已凍結(jié) 2: 已注銷 email: aliases: [mail] sensitive: true relationships: - from: orders.customer_id to: customers.id cardinality: many-to-one note: 訂單表通過(guò) customer_id 指向客戶主數(shù)據(jù)不允許存在孤兒訂單 glossary: - term: 活躍客戶 definition: 近30天內(nèi)至少下單1次的客戶 related_tables: [customers, orders]然后是豐富層合并代碼from pydantic import BaseModel class FieldMeta(BaseModel): name: str type: str nullable: bool True comment: str | None None aliases: list[str] [] enum_values: dict[str, str] | None None sensitive: bool False class TableMeta(BaseModel): name: str schema: str | None None comment: str | None None fields: list[FieldMeta] pk: list[str] [] def merge_meta(parsed_table: dict, enrich_cfg: dict) - TableMeta: table_name parsed_table[table] cfg enrich_cfg[tables].get(table_name, {}) field_cfgs cfg.get(fields, {}) fields [] for raw_field in parsed_table[columns]: fcfg field_cfgs.get(raw_field[name], {}) fields.append( FieldMeta( nameraw_field[name], typeraw_field[type], commentfcfg.get(comment), aliasesfcfg.get(aliases, []), enum_valuesfcfg.get(enums), sensitivefcfg.get(sensitive, False), ) ) return TableMeta( nametable_name, schemacfg.get(schema), commentcfg.get(comment), fieldsfields, pkcfg.get(pk, []), )這一段干的事很樸素但我認(rèn)為這是整個(gè)項(xiàng)目里價(jià)值密度最高的一段把人類腦子里的業(yè)務(wù)約定轉(zhuǎn)成機(jī)器可讀的數(shù)據(jù)。沒(méi)這一步知識(shí)包和普通的information_schema導(dǎo)出的元數(shù)據(jù)就沒(méi)有本質(zhì)區(qū)別。4.3 渲染成 Agent 直接消費(fèi)的文本知識(shí)包里面存儲(chǔ)用 JSON但真正喂給 Agent 的是渲染后的文本。渲染模板我放在 jinja2 里保存成table.j2## Table: {{ table.name }}{{ table.schema or public }} {{ table.comment or }} 字段列表 {% for f in table.fields -%} - {{ f.name }}{{ f.comment or 暫無(wú)說(shuō)明 }}{{ f.type }}{% if not f.nullable %}非空{(diào)% else %}可空{(diào)% endif %} {% if f.enum_values %} 枚舉值 {% for k, v in f.enum_values.items() %} - {{ k }} {{ v }} {% endfor %} {% endif %} {% if f.aliases %} 別稱{{ f.aliases | join(, ) }}{% endif %} {% if f.sensitive %} 敏感字段生成 SQL 與展示結(jié)果時(shí)須提示脫敏{% endif %} {% endfor %} 關(guān)聯(lián)關(guān)系 {% for r in table.relations -%} - {{ r.from.table }}.{{ r.from.field }} - {{ r.to.table }}.{{ r.to.field }}{{ r.cardinality }} {% endfor %}渲染出來(lái)的效果就是 Agent 真正讀到的一段文本比如## Table: customerspublic 客戶主數(shù)據(jù)一客戶一行 字段列表 - id客戶唯一標(biāo)識(shí)bigint非空 - status客戶狀態(tài)枚舉tinyint可空 枚舉值 - 0 正常 - 1 已凍結(jié) - 2 已注銷 - email登錄郵箱個(gè)人敏感信息varchar(128)可空 別稱mail 敏感字段生成 SQL 與展示結(jié)果時(shí)須提示脫敏 關(guān)聯(lián)關(guān)系 - orders.customer_id - customers.idmany-to-one這段文本的核心價(jià)值在于它完全貼近“一個(gè)數(shù)據(jù)庫(kù) DBA 給新人講解業(yè)務(wù)時(shí)說(shuō)的話”而不是SHOW CREATE TABLE吐出來(lái)的冷冰冰的物理定義。5. 讓 Agent 真正用起來(lái)知識(shí)包的檢索與上下文裝配知識(shí)包編譯出來(lái)了不接進(jìn) Agent 的調(diào)用鏈路里就等于白做。我項(xiàng)目里接的方式不是全文塞 prompt而是按需檢索。Agent 需要知道哪張表的信息才把哪張表的知識(shí)片段取出來(lái)。5.1 上下文太長(zhǎng)按需檢索假設(shè)你有 20 張表渲染后的全文可能有 5000 個(gè) token。全部塞進(jìn)系統(tǒng)提示Agent 會(huì)長(zhǎng)篇大論地注意到無(wú)關(guān)表還浪費(fèi)預(yù)算。正確的做法是把每張表的知識(shí)片段作為一個(gè)獨(dú)立的“檢索單元”用戶提問(wèn)時(shí)先做一次粗粒度檢索只取最相關(guān)的三五張表。我自己用的是純 Python 實(shí)現(xiàn)的輕量檢索沒(méi)有上向量數(shù)據(jù)庫(kù)。為什么知識(shí)包本身是高度結(jié)構(gòu)化的文本關(guān)鍵詞重疊度已經(jīng)能匹配得很好用戶問(wèn)“本月活躍客戶”分詞后命中的是“活躍客戶”“客戶”“customers”這個(gè)信號(hào)足夠強(qiáng)。向量檢索適合語(yǔ)義距離遠(yuǎn)但表達(dá)相似的內(nèi)容而數(shù)據(jù)庫(kù)知識(shí)包恰恰要避免這種模糊匹配。簡(jiǎn)單方案可控、無(wú)額外服務(wù)對(duì)于中小規(guī)模的庫(kù)完全夠用。檢索的輸入輸出很像一個(gè)工具函數(shù)def retrieve_knowledge_package(query: str, index: dict, top_k: int 3) - list[str]: tokens tokenize(query) scored [] for table_name, block in index.items(): score sum(1 for t in tokens if t in block.lower()) scored.append((score, table_name, block)) scored.sort(reverseTrue, keylambda x: (x[0], len(x[1]))) return [block for _, _, block in scored[:top_k] if _ 0]這段代碼沒(méi)什么黑魔法。但它把關(guān)鍵的一件事做了讓 Agent 在收到具體任務(wù)之前已經(jīng)拿到它應(yīng)該看哪幾張表的提示。5.2 把知識(shí)包掛進(jìn)工具函數(shù)與提示詞僅僅檢索還不夠要讓 Agent 在工具調(diào)用時(shí)真正“想到”去用。我注冊(cè)給 Agent 的工具有兩個(gè)def get_table_context(table_name: str) - str: 返回指定表的業(yè)務(wù)語(yǔ)義、字段枚舉、關(guān)聯(lián)關(guān)系等知識(shí)包片段 return render_table_block(table_name) def run_sql(sql: str) - list[dict]: 執(zhí)行只讀 SQL 查詢禁止修改操作 ...在系統(tǒng)提示詞里我會(huì)寫清楚使用順序先調(diào)用get_table_context獲取相關(guān)表的上下文再基于上下文寫 SQL最后調(diào)用run_sql。這是很典型的 ReAct 模式但關(guān)鍵不在于模式本身而在于get_table_context返回的內(nèi)容質(zhì)量。如果它返回的只是字段列表Agent 依然要猜如果返回的是帶枚舉、帶別名、帶關(guān)系提醒的知識(shí)片段Agent 寫出錯(cuò)誤 join 的概率就會(huì)顯著下降。我再補(bǔ)一個(gè)經(jīng)常被忽略的細(xì)節(jié)知識(shí)包里不應(yīng)包含真實(shí)數(shù)據(jù)只能包含結(jié)構(gòu)和語(yǔ)義。真實(shí)數(shù)據(jù)可能涉及隱私而且體積不可控。知識(shí)包只做“地圖”Agent 運(yùn)行 SQL 之后拿到的結(jié)果才是“現(xiàn)場(chǎng)”。地圖和現(xiàn)場(chǎng)分離權(quán)限控制和數(shù)據(jù)安全都好做很多。6. 踩坑記錄與邊界控制什么情況下別硬上編譯器最后這部分是最想分享的。項(xiàng)目整體跑通不難但中間有不少?zèng)Q策如果重新來(lái)一遍我會(huì)做得更果斷。6.1 解析 SQL 的“80% 原則”第一個(gè)坑是過(guò)度追求解析器的完整度。我一開(kāi)始想讓解析器支持存儲(chǔ)生成列、分區(qū)表、復(fù)雜默認(rèn)表達(dá)式、索引定義結(jié)果一周時(shí)間全耗在這個(gè)上面真正的知識(shí)包結(jié)構(gòu)反而沒(méi)怎么動(dòng)。后來(lái)我把解析目標(biāo)砍到只剩四件事表名、字段名、字段類型、基礎(chǔ)注釋。凡是解析不了的直接跳過(guò)并打一條 warning在編譯日志里標(biāo)出來(lái)讓人工補(bǔ)充文件去兜底。這里分享一個(gè)判斷標(biāo)準(zhǔn)知識(shí)包的錯(cuò)誤容忍策略應(yīng)該和 Agent 的容錯(cuò)能力匹配。Agent 本身就很擅長(zhǎng)從自由文本里抓重點(diǎn)你不需要給它一個(gè) 100% 精確的 AST你只需要給它 80% 的準(zhǔn)確結(jié)構(gòu)加上 20% 的人工兜底效果就會(huì)好過(guò)追求完美解析。把精力花在補(bǔ)全業(yè)務(wù)語(yǔ)義上回報(bào)比高得多。6.2 包失效與重建策略checksum 和 CI第二個(gè)坑是知識(shí)包不同步。數(shù)據(jù)庫(kù)的 DDL 一改知識(shí)包還是舊版本Agent 拿到舊信息去查新表必然出錯(cuò)。我用兩招解決。第一招是給知識(shí)包打 checksum。編譯時(shí)把所有輸入文件拼接后算一個(gè)哈希存在知識(shí)包meta.checksum里。每次 Agent 加載知識(shí)包時(shí)先核對(duì)發(fā)現(xiàn)不對(duì)就提示“知識(shí)包已過(guò)期需要重新編譯”。這一步成本極低但能避免很多詭異的線上問(wèn)題。第二招是把編譯過(guò)程接進(jìn) CI。我現(xiàn)在的做法是數(shù)據(jù)庫(kù)的 DDL 遷移腳本一提交流水線自動(dòng)跑一次編譯器。編譯失敗或者 checksum 變化都會(huì)在合并請(qǐng)求里直接標(biāo)出來(lái)。這樣知識(shí)包始終跟隨數(shù)據(jù)庫(kù)結(jié)構(gòu)版本走而不是靠某個(gè)人想起來(lái)手動(dòng)更新。變更類型知識(shí)包是否需要重建說(shuō)明新增一張表需要新表可能被 Agent 需要新增/刪除字段需要字段列表變化修改字段注釋/枚舉需要語(yǔ)義變化是重構(gòu)核心只改索引或分區(qū)不需要Agent 不需要感知物理優(yōu)化只有數(shù)據(jù)量變化不需要結(jié)構(gòu)層知識(shí)包不存數(shù)據(jù)統(tǒng)計(jì)6.3 什么時(shí)候不要搞知識(shí)包編譯器最后一個(gè)建議可能有點(diǎn)反直覺(jué)表數(shù)量很少、結(jié)構(gòu)非常穩(wěn)定的項(xiàng)目不要上編譯器。如果是五六張表手動(dòng)寫 JSON 或 Markdown 可能只需要半天而編譯器需要寫解析邏輯、寫合并邏輯、寫渲染模板、配 CI整套下來(lái)怎么也要一兩周。我判斷是否值得搞知識(shí)包編譯器的三個(gè)條件表數(shù)量超過(guò)兩位數(shù)表結(jié)構(gòu)在持續(xù)演進(jìn)你確實(shí)要把數(shù)據(jù)庫(kù)能力開(kāi)放給 Agent 做自動(dòng)化查詢。三個(gè)條件至少滿足兩個(gè)才值得投入。如果只是給一個(gè)固定報(bào)表的數(shù)據(jù)庫(kù)接個(gè)問(wèn)答 Demo那直接把業(yè)務(wù)口徑寫成一小段提示詞塞進(jìn)系統(tǒng)提示里比做知識(shí)包高效得多。反過(guò)來(lái)如果目標(biāo)是讓 Agent 自主探索一個(gè)持續(xù)變化的數(shù)據(jù)倉(cāng)庫(kù)那么沒(méi)有知識(shí)包的 Agent 就是一臺(tái)沒(méi)有地圖的自動(dòng)駕駛車遲早撞墻。我個(gè)人的體會(huì)是這個(gè)項(xiàng)目最有價(jià)值的部分不是那幾千行 Python 代碼而是它逼著我把數(shù)據(jù)庫(kù)的“隱性知識(shí)”顯式化了。過(guò)去 DBA 腦子里那點(diǎn)東西——哪個(gè)字段是敏感字段、哪張表和哪張表能用軟關(guān)聯(lián)、字段枚舉到底什么含義——現(xiàn)在全部變成了一份可以版本管理、可以自動(dòng)校驗(yàn)、可以隨時(shí)渲染給 Agent 看的知識(shí)包。從此 Agent 學(xué)到的不是猜出來(lái)的表結(jié)構(gòu)而是這個(gè)數(shù)據(jù)庫(kù)真實(shí)運(yùn)行的業(yè)務(wù)規(guī)則。如果你也在做類似的事情建議先別急著調(diào)大模型先把數(shù)據(jù)庫(kù)知識(shí)管好后面所有環(huán)節(jié)都會(huì)輕松很多。