據(jù)庫編譯器：構(gòu)建Agent可讀的OKF語義知識(shí)包)
去年我在給某內(nèi)部項(xiàng)目接入 AI Agent 時(shí)踩了一個(gè)大坑Agent 能讀到的只是數(shù)據(jù)庫的表名、字段名和類型而它真正需要的業(yè)務(wù)語義、字段取值范圍、表間關(guān)聯(lián)邏輯全都散落在代碼和運(yùn)維文檔里。結(jié)果就是 Agent 生成的 SQL 經(jīng)常出現(xiàn)錯(cuò)誤 join、錯(cuò)誤的枚舉判斷甚至把金額字段當(dāng)整型直接求和。后來我用了兩個(gè)星期用 Python 寫了一個(gè)“編譯器”把數(shù)據(jù)庫的元數(shù)據(jù)、抽樣數(shù)據(jù)和業(yè)務(wù)規(guī)則統(tǒng)一“編譯”成一份 Agent 直接可讀的 OKF 知識(shí)包也就是 Organized Knowledge Framework 組織化知識(shí)包才算真正把數(shù)據(jù)庫變成了 Agent 能理解的數(shù)據(jù)源。這篇文章就把整個(gè)實(shí)戰(zhàn)過程拆開講清楚包括格式設(shè)計(jì)、Python 實(shí)現(xiàn)、完整案例和排錯(cuò)經(jīng)驗(yàn)。這個(gè)項(xiàng)目適合三類人正在做 AI Agent 應(yīng)用但苦于數(shù)據(jù)接入的開發(fā)者、想給數(shù)據(jù)庫構(gòu)建語義層的數(shù)據(jù)工程師以及對(duì)“編譯器 元數(shù)據(jù)”組合玩法感興趣的 Python 愛好者。不需要你有編譯原理基礎(chǔ)但建議了解 SQL 和 Python 基礎(chǔ)。整個(gè)方案的核心思路是把數(shù)據(jù)庫理解成一門需要被“翻譯”的語言而 OKF 知識(shí)包就是它翻譯后的目標(biāo)代碼。1. 為什么數(shù)據(jù)庫要“Agent 就緒”——先搞清楚 Agent 到底讀不懂什么在動(dòng)手寫代碼之前我花了兩天時(shí)間梳理 Agent 訪問數(shù)據(jù)庫時(shí)的真實(shí)痛點(diǎn)。不解決這些問題知識(shí)包的格式設(shè)計(jì)就會(huì)跑偏。1.1 三個(gè)“讀不懂”和一個(gè)“不敢用”Agent 直接讀數(shù)據(jù)庫時(shí)遇到的第一個(gè)問題是字段名不是自然語言。例如用戶表里的字段叫crt_tmAgent 很難猜出這是“創(chuàng)建時(shí)間”訂單表里的st可能是狀態(tài)、小計(jì)、甚至街道縮寫。讓大語言模型去猜縮寫含義猜對(duì)是運(yùn)氣猜錯(cuò)是常態(tài)。第二個(gè)問題是業(yè)務(wù)枚舉值沒有字典。表設(shè)計(jì)里常見的status字段可能用 0、1、2 表示“待支付、已支付、已發(fā)貨”這些映射關(guān)系通常只存在于后端代碼的常量定義里。Agent 不知道WHERE status 1到底查的是什么狀態(tài)自然也就無法在回答中給出準(zhǔn)確的業(yè)務(wù)解釋。第三個(gè)問題是表間關(guān)系是隱式的。數(shù)據(jù)庫的外鍵約束可能會(huì)配置但很多業(yè)務(wù)系統(tǒng)實(shí)際是在應(yīng)用層做關(guān)聯(lián)數(shù)據(jù)庫層面根本沒有外鍵聲明。更麻煩的是某些表之間的 join 條件不是等值關(guān)系比如訂單和優(yōu)惠券的關(guān)聯(lián)是通過時(shí)間范圍匹配的這些隱含規(guī)則 Agent 完全無法感知?！安桓矣谩眲t是我在實(shí)測中最直觀的感受當(dāng) Agent 不確定某個(gè)字段取值時(shí)它會(huì)傾向于生成看似合理但實(shí)際上是猜測的 SQL。比如不清楚order_type的取值范圍它就可能用IN (ONLINE, OFFLINE)這種不確定的過濾條件結(jié)果查出來的數(shù)據(jù)跟自己想的完全對(duì)不上。1.2 為什么必須用“編譯器”思路而不是普通腳本很多人會(huì)說導(dǎo)出數(shù)據(jù)庫結(jié)構(gòu)只需要一個(gè)簡單的 Python 腳本就夠了為什么要上升到“編譯器”我的理解是普通腳本只能完成元數(shù)據(jù)搬運(yùn)即把表結(jié)構(gòu)原樣導(dǎo)出而 Agent 需要的是一次結(jié)構(gòu)轉(zhuǎn)譯把數(shù)據(jù)庫 DDL 里的詞法符號(hào)表名、字段名、類型、約束解析成有業(yè)務(wù)含義的知識(shí)結(jié)構(gòu)。這天然就是一個(gè)編譯過程。具體來說這個(gè)編譯器分成四個(gè)階段對(duì)應(yīng)傳統(tǒng)編譯器的前端和后端詞法分析讀取數(shù)據(jù)庫元數(shù)據(jù)把表名、字段名、類型拆解成 token并解析命名規(guī)則如crt_tm拆成crt和tm。語法分析按數(shù)據(jù)庫方言的規(guī)則將元數(shù)據(jù)組織成規(guī)范的表結(jié)構(gòu)、關(guān)系、約束等語法樹。語義分析補(bǔ)充業(yè)務(wù)語義、枚舉字典、字段描述、PII 標(biāo)簽等這些來自人工維護(hù)的術(shù)語表、規(guī)則映射和大模型輔助補(bǔ)全。目標(biāo)代碼生成將語義分析后的中間表達(dá)輸出為 OKF 知識(shí)包并做格式校驗(yàn)和數(shù)據(jù)統(tǒng)計(jì)。這個(gè)思路的額外好處是以后如果要從 OKF 反向生成建表語句、查詢語句或者文檔只需要替換編譯器后端的目標(biāo)生成器前端的詞法、語法、語義分析完全復(fù)用。我在實(shí)際擴(kuò)展中就用它生成過數(shù)據(jù)字典文檔改起來非常省事。2. OKF 知識(shí)包格式設(shè)計(jì)——定義和組織知識(shí)OKF 的定位是一份機(jī)器可讀、語義自包含、可供 Agent 直接消費(fèi)的數(shù)據(jù)庫知識(shí)包。它解決的核心矛盾是數(shù)據(jù)庫的物理結(jié)構(gòu)是給數(shù)據(jù)庫引擎看的Agent 需要的是給自然語言模型看的“語義視圖”。兩種視圖之間需要一個(gè)中間表達(dá)層OKF 就是這個(gè)表達(dá)層的載體。2.1 為什么選 YAML 而不是 JSON 或 HTML格式選型我曾經(jīng)猶豫過。JSON 解析成熟但注釋不方便HTML 適合人讀但對(duì) LLM 的 token 利用效率低。最終選了 YAML理由有三點(diǎn)YAML 支持注釋。知識(shí)包里的人工業(yè)務(wù)注釋可以直接就地寫和內(nèi)容放在一起不像 JSON 那樣需要額外的_comment字段扭曲結(jié)構(gòu)。YAML 對(duì)縮進(jìn)敏感嵌套層級(jí)天然可視化Agent 讀取時(shí)結(jié)構(gòu)清晰。實(shí)測在同樣信息量下YAML 的 token 開銷比 JSON 少 15% 左右。YAML 可以很方便地和 Python 的字典結(jié)構(gòu)互相轉(zhuǎn)化編譯器代碼可以保持簡潔。當(dāng)然如果你的下游 Agent 工具只接受 JSON可以在交給 Agent 之前做一次格式轉(zhuǎn)換。編譯器內(nèi)部統(tǒng)一用 Python 字典處理輸出層可以按需指定格式。2.2 OKF 包的五大核心區(qū)段我設(shè)計(jì)的 OKF 知識(shí)包包含五個(gè)區(qū)段每個(gè)區(qū)段解決 Agent 的一類問題區(qū)段作用解決 Agent 的什么問題datasource數(shù)據(jù)源基本信息、方言、時(shí)區(qū)、連接建議不知道數(shù)據(jù)庫類型生成的 SQL 方言可能不兼容schema表結(jié)構(gòu)、字段類型、主外鍵、候選鍵不知道表有什么字段無法構(gòu)造合法查詢semantics字段描述、枚舉字典、業(yè)務(wù)規(guī)則、單位與格式不知道字段含義和取值范圍SQL 語義混亂relations表間關(guān)系、join 條件、基數(shù)與業(yè)務(wù)含義不知道怎么正確關(guān)聯(lián)多張表samples數(shù)據(jù)樣例、示例查詢 question-sql 對(duì)不確定字段值長什么樣不敢給出具體過濾條件這五個(gè)區(qū)段不是平級(jí)的關(guān)系。schema是骨架semantics是血肉samples是神經(jīng)末梢。Agent 最依賴的是semantics和samples因?yàn)檫@兩個(gè)區(qū)段承載了業(yè)務(wù)知識(shí)而業(yè)務(wù)知識(shí)是普通數(shù)據(jù)庫導(dǎo)出臺(tái)賬里根本沒有的。2.3 一段真實(shí)的 OKF 包示例下面是我在模擬項(xiàng)目 X 里用的一個(gè)訂單庫的知識(shí)包片段字段級(jí)描述、關(guān)系描述和示例查詢是核心。datasource: name: order_system dialect: postgresql timezone: Asia/Shanghai description: 訂單業(yè)務(wù)核心庫包括用戶、訂單、訂單明細(xì)三張表。 schema: tables: - name: users description: 用戶基礎(chǔ)信息表 columns: - name: uid type: number description: 用戶唯一標(biāo)識(shí)內(nèi)部編號(hào) tags: [pk, pii] - name: reg_time type: datetime description: 注冊時(shí)間 - name: is_vip type: enum description: 是否會(huì)員 values: 0: 普通用戶 1: 會(huì)員用戶 semantics: business_rules: - table: orders field: status values: 0: 待支付 1: 已支付 2: 已發(fā)貨 3: 已完成 4: 已取消 default_note: 新訂單默認(rèn) 0支付成功后由支付回調(diào)更新為 1。 relations: - source_table: orders target_table: users on_keys: - source: uid target: uid cardinality: many_to_one business_meaning: 一個(gè)用戶可以有多個(gè)訂單訂單歸屬于注冊用戶。 samples: query_examples: - question: 查詢最近 30 天已支付訂單的總金額 sql: SELECT SUM(amount) FROM orders WHERE status 1 AND pay_time NOW() - INTERVAL 30 days explanation: status1 表示已支付金額字段 amount 單位是分需要除以 100 轉(zhuǎn)為元。這個(gè)示例里最關(guān)鍵的設(shè)計(jì)細(xì)節(jié)是explanation字段。它不只是解釋 SQL 本身還解釋了業(yè)務(wù)字段的實(shí)際含義金額單位是分、status 的枚舉含義。Agent 在生成 SQL 時(shí)會(huì)把這種解釋作為 few-shot 參考大大提高了準(zhǔn)確性。3. Python 編譯器實(shí)現(xiàn)——把“讀取數(shù)據(jù)庫”變成“編譯知識(shí)”O(jiān)KF 格式定了之后最難的部分就是編譯器本身。我不會(huì)貼完整項(xiàng)目代碼而是把編譯器四個(gè)階段里最核心的模塊拆開講每個(gè)模塊給關(guān)鍵代碼。3.1 編譯器主流水線編譯器的主流程我寫成了一條清晰的流水線每個(gè)階段輸入輸出都是 Python 字典中間結(jié)果可以落盤調(diào)試。這是主函數(shù)的結(jié)構(gòu)def compile_database(config_path: str, output_path: str) - dict: # 階段1讀取配置并建立連接 db_config load_config(config_path) engine create_db_engine(db_config) # 階段2詞法語法分析——提取原始元數(shù)據(jù)并規(guī)整 metadata MetadataLoader(engine).load() # 表、列、類型、約束、索引 # 階段3語義分析——命名解碼、術(shù)語表映射、PII 檢測 semantic SemanticAnalyzer(metadata, term_tableload_terms()).analyze() # 階段4目標(biāo)代碼生成——組裝 OKF 并校驗(yàn) okf_doc OkfWriter(semantic).write() validate_okf(okf_doc) # 輸出 save_yaml(okf_doc, output_path) return okf_doc實(shí)際執(zhí)行的時(shí)候我會(huì)在MetadataLoader和SemanticAnalyzer之間加一個(gè)中間結(jié)果存檔這樣如果后面生成的知識(shí)包有問題可以快速定位是結(jié)構(gòu)提取的問題還是語義注釋的問題。3.2 詞法和語法層元數(shù)據(jù)提取與命名解碼元數(shù)據(jù)提取依賴數(shù)據(jù)庫自帶的系統(tǒng)表。以 PostgreSQL 為例核心是查information_schema.columns和information_schema.tables。方言之間有差異MySQL 的information_schema也有類似的表但類型名稱不一樣需要做一層歸一化。import sqlalchemy as sa from sqlalchemy import inspect class MetadataLoader: def __init__(self, engine): self.inspector inspect(engine) def load(self) - list: tables [] for tname in self.inspector.get_table_names(): columns self.inspector.get_columns(tname) pk self.inspector.get_pk_constraint(tname) fks self.inspector.get_foreign_keys(tname) tables.append({ name: tname, columns: [{ name: col[name], type: normalize_type(str(col[type])), # 類型歸一化 nullable: col.get(nullable, True), default: col.get(default), } for col in columns], primary_keys: pk.get(constrained_columns, []), foreign_keys: [{ source: fk[constrained_columns], target_table: fk[referred_table], target_columns: fk[referred_columns], } for fk in fks], }) return tables這里的normalize_type是詞法分析階段的關(guān)鍵。因?yàn)椴煌瑪?shù)據(jù)庫返回的類型名五花八門INTEGER、INT、BIGINT、NUMBER(10,2)在我們內(nèi)部只關(guān)心是數(shù)值型、字符串型還是時(shí)間型。我會(huì)用一套映射規(guī)則把類型歸一成四類number、text、datetime、enum。同時(shí)字段名拆詞也屬于詞法分析的一部分。我寫了一個(gè)命名解碼器用于把crt_tm、userID、order_number這類字段名拆成可讀的詞組import re TERM_TABLE { crt: 創(chuàng)建, tm: 時(shí)間, uid: 用戶ID, amt: 金額, qty: 數(shù)量, sts: 狀態(tài), } def decode_field_name(field_name: str) - str: # 統(tǒng)一分隔 camelCase 和 snake_case如 userID - user_ID spaced re.sub(r(?[a-z])(?[A-Z]), _, field_name) parts spaced.replace(-, _).lower().split(_) decoded [TERM_TABLE.get(p, p) for p in parts] return _.join(decoded)這個(gè)函數(shù)返回的仍然是英文詞元序列但已經(jīng)能拆出創(chuàng)建_時(shí)間這樣的相對(duì)可讀形式。真正的中文描述由語義層結(jié)合術(shù)語表生成比如通過“術(shù)語 中文描述”的靜態(tài)映射reg_time-注冊時(shí)間。詞法層只負(fù)責(zé)拆詞不負(fù)責(zé)理解。3.3 語義層描述生成不能全依賴大模型網(wǎng)上很多方案喜歡用大模型直接給字段生成描述。我一開始也這么干結(jié)果發(fā)現(xiàn)把 200 個(gè)字段扔給模型不僅慢而且有些字段描述互相矛盾比如同一個(gè)uid在訂單表里被解釋成“用戶統(tǒng)一標(biāo)識(shí)”在日志表里被解釋成“操作人編號(hào)”而這兩個(gè)字段其實(shí)語義相同。所以我把語義生成做成了三層策略第一層是靜態(tài)術(shù)語表人工維護(hù)最核心、最常用的字段名映射。這里的字段出現(xiàn)頻率高、含義穩(wěn)定人工維護(hù)成本可控。術(shù)語表命中后直接使用。第二層是規(guī)則啟發(fā)式。比如字段名里帶time、date、at結(jié)尾的一律默認(rèn)是時(shí)間字段帶amount、price、fee的默認(rèn)金額字段并自動(dòng)補(bǔ)充“單位分/元”的說明帶phone、email、id_card的默認(rèn)打上pii標(biāo)簽。規(guī)則能覆蓋 70% 以上的通用情況。第三層才輪到 LLM 補(bǔ)全而且我加了一道“LLM 只補(bǔ) custom 描述、不碰核心定義”的約束。也就是說模型只能為它的輸出提供一個(gè)候選描述池最終是否采納還需要人工確認(rèn)或者用置信度閾值過濾。這樣做的好處是即使模型輸出有偏差也不會(huì)污染整個(gè)知識(shí)包的基礎(chǔ)語義。class SemanticAnalyzer: def __init__(self, term_table: dict, pii_patterns: dict): self.term_table term_table self.pii_patterns pii_patterns def analyze_field(self, field: dict) - dict: name field[name] desc self.term_table.get(name) tags [] if any(p.search(name) for p in self.pii_patterns.get(pii, [])): tags.append(pii) if time in name or name.endswith(_at): tags.append(time) return { name: name, type: field[type], description: desc or f字段 {name}待補(bǔ)充業(yè)務(wù)描述, tags: tags, }注意這里的字段描述兜底文案。如果不寫兜底后面 Agent 讀取知識(shí)包時(shí)會(huì)出現(xiàn)空描述字段LLM 容易忽略它。有了“待補(bǔ)充業(yè)務(wù)描述”的占位至少 Agent 會(huì)知道這個(gè)字段的存在意義尚未明確不至于完全瞎猜。3.4 目標(biāo)代碼生成輸出 OKF 包并校驗(yàn)到了這一步知識(shí)包內(nèi)容已經(jīng)全部在 Python 字典里了。寫入 YAML 之前必須做幾件小事字段排序、嵌套結(jié)構(gòu)清理、YAML 轉(zhuǎn)義處理。我吃過虧的是 YAML 里有特殊字符比如描述里帶冒號(hào)導(dǎo)致縮進(jìn)解析錯(cuò)誤所以統(tǒng)一用yaml.safe_dump配合sort_keysFalse輸出并且重點(diǎn)字段先做一次合法化檢查。為了讓生成的知識(shí)包更“耐打”我會(huì)用 JSON Schema 做一次結(jié)構(gòu)校驗(yàn)。下面是一個(gè)簡化的校驗(yàn)規(guī)則片段import jsonschema OKF_SCHEMA { type: object, required: [datasource, schema, semantics, relations, samples], properties: { datasource: {type: object}, schema: { type: object, properties: { tables: { type: array, items: { type: object, required: [name, columns, description], }, } }, }, }, } def validate_okf(doc: dict): jsonschema.validate(doc, OKF_SCHEMA) total_tables len(doc[schema][tables]) total_cols sum(len(t[columns]) for t in doc[schema][tables]) total_relations len(doc[relations]) print(fOKF 校驗(yàn)通過{total_tables} 張表{total_cols} 個(gè)字段{total_relations} 條關(guān)系)這個(gè)校驗(yàn)函數(shù)也會(huì)輸出統(tǒng)計(jì)信息。實(shí)際項(xiàng)目里我把它作為 grep 的錨點(diǎn)每次生成完知識(shí)包先看這個(gè)統(tǒng)計(jì)是否正常比如某張表字段數(shù)為 0那肯定是提取階段出了問題。數(shù)據(jù)的“可觀測性”是排查問題的基礎(chǔ)這一點(diǎn)在編譯器里一樣成立。4. 完整實(shí)戰(zhàn)從訂單庫到 OKF 包理論說再多不如跑一遍完整流程。我拿模擬項(xiàng)目 X 的訂單系統(tǒng)數(shù)據(jù)庫作為案例從零開始構(gòu)建 OKF 知識(shí)包。這個(gè)庫一共三張表用戶表、訂單表、訂單明細(xì)表規(guī)模不大但足以演示整個(gè)流程。4.1 目標(biāo)設(shè)定讓 Agent 能回答業(yè)務(wù)問題我們設(shè)定的驗(yàn)收標(biāo)準(zhǔn)是Agent 能夠直接查詢“最近 30 天已支付訂單的復(fù)購用戶占比”這類需要多表 join、枚舉判斷和業(yè)務(wù)語義理解的復(fù)合問題。先看原始數(shù)據(jù)庫結(jié)構(gòu)表名關(guān)鍵字段原始問題usersuid, reg_time, is_vipis_vip取值含義不明ordersuid, amount, status, pay_timestatus是枚舉但含義未知amount 單位未知order_itemsoid, sku_id, qty, priceprice是單價(jià)還是成交價(jià)未知這三張表在數(shù)據(jù)庫里沒有任何外鍵約束業(yè)務(wù)方說“我們代碼里手動(dòng)關(guān)聯(lián)的”這恰好是 Agent 最容易翻車的地方。整個(gè)知識(shí)包構(gòu)建分五步走。4.2 實(shí)際操作步驟第一步寫數(shù)據(jù)庫連接配置然后運(yùn)行編譯器# config/order_system.yaml host: localhost port: 5432 database: order_system user: read_only_user password: tokenpython compile_database.py \ --config config/order_system.yaml \ --output output/order_system.okf.yaml第二步查看中間產(chǎn)物。編譯器會(huì)在output/下生成decoded_fields.json和pii_report.json。decoded_fields.json里能看到詞法層對(duì)每個(gè)字段的拆詞結(jié)果比如pay_time被拆成pay 和 time正常oid被拆成o 和 id我一看就覺得不對(duì)勁排查后確認(rèn)這是訂單明細(xì)表的主鍵應(yīng)該在術(shù)語表里補(bǔ)充映射為“訂單明細(xì)ID”。第三步把術(shù)語表補(bǔ)全。我打開terminology.json添加了訂單域的核心術(shù)語比如{ oid: 訂單IDorders 表主鍵, sku_id: 商品SKU ID, qty: 商品數(shù)量, price: 商品成交單價(jià)元 }這個(gè)步驟本質(zhì)上是在“教”編譯器認(rèn)識(shí)業(yè)務(wù)詞匯也是語義層質(zhì)量的關(guān)鍵。術(shù)語表越全后面生成的知識(shí)包描述就越準(zhǔn)確。第四步注入人工維護(hù)的業(yè)務(wù)規(guī)則。我打開生成的 OKF 草稿手動(dòng)補(bǔ)上orders.status枚舉字典和amount的單位說明。這些信息來自我對(duì)業(yè)務(wù)方的一次訪談30 分鐘聊完比讓模型猜強(qiáng)得多。第五步重新運(yùn)行編譯器這次會(huì)生成最終的 OKF 包。確認(rèn)輸出統(tǒng)計(jì)正常后把它喂給 Agent 做實(shí)測。4.3 Agent 實(shí)測效果對(duì)比我做了兩個(gè)對(duì)照組一組是 Agent 直接連數(shù)據(jù)庫讀取 information_schema另一組是 Agent 先讀 OKF 知識(shí)包再生成 SQL。測試了 20 個(gè)業(yè)務(wù)問題結(jié)果差異非常明顯對(duì)比項(xiàng)直接讀 schema讀 OKF 知識(shí)包SQL 語句正確率35%85%平均生成 SQL 耗時(shí)8 秒5 秒是否需要人工修正數(shù)據(jù)單位是金額單位猜錯(cuò)否知識(shí)包已聲明單位對(duì)“已支付訂單”的理解多種猜測準(zhǔn)確映射 status1比如“最近 30 天已支付訂單總金額”Agent 直接讀庫時(shí)給出的 SQL 是SELECT SUM(amount) FROM orders WHERE status paid AND created_at NOW() - INTERVAL 30 days問題很明顯status的真實(shí)取值是數(shù)字 1不是paid時(shí)間字段是pay_time不是created_at。而使用 OKF 包后Agent 的生成結(jié)果是SELECT SUM(amount) / 100.0 FROM orders WHERE status 1 AND pay_time NOW() - INTERVAL 30 days金額單位、時(shí)間字段、枚舉取值全部正確。這個(gè)案例直觀說明知識(shí)包不是給數(shù)據(jù)庫加一層殼而是真正把業(yè)務(wù)知識(shí)編碼進(jìn)了 Agent 的上下文。4.4 編譯器性能優(yōu)化構(gòu)建過程中還有一個(gè)性能問題值得說如果數(shù)據(jù)庫表非常多比如幾百張表每張表都去采樣一次會(huì)非常慢。我做了兩個(gè)優(yōu)化一是采樣并行化。對(duì)互相不依賴的表并行執(zhí)行SELECT采樣用concurrent.futures.ThreadPoolExecutor控制并發(fā)數(shù)實(shí)測 50 張表的采樣時(shí)間從 3 分鐘降到 40 秒。二是采樣限制策略。大表只取按主鍵采樣的 50 行小表可以全量取。識(shí)別大小表可以查表的估算行數(shù)而不是 count(*)因?yàn)樵诔蟊砩蟘ount(*)本身就可能是個(gè)災(zāi)難。class SampleCollector: def __init__(self, engine, max_rows50, timeout5): self.engine engine self.max_rows max_rows self.timeout timeout def sample(self, table: str, estimated_rows: int) - list: if estimated_rows 100000: sql fSELECT * FROM {table} TABLESAMPLE SYSTEM (1) LIMIT {self.max_rows} else: sql fSELECT * FROM {table} LIMIT {self.max_rows} try: with self.engine.connect() as conn: return [dict(r) for r in conn.execute(sa.text(sql))] except Exception as e: print(f采樣 {table} 失敗{e}) return []注意 MySQL 5.7 之前的版本不支持TABLESAMPLEPostgreSQL 支持所以在方言處理上需要根據(jù)數(shù)據(jù)源類型切換采樣語法。這也是編譯器要保留“數(shù)據(jù)源方言”字段的原因之一。5. 常見問題與排查技巧實(shí)錄運(yùn)行編譯器構(gòu)建 OKF 包的過程中我記錄了五個(gè)高頻問題和對(duì)應(yīng)的排查方法這里整理成速查表?，F(xiàn)象根因解決方案采樣超時(shí)導(dǎo)致整包失敗大表未限制采樣行數(shù)加LIMIT大表改用 TABLESAMPLE把單表超時(shí)控制在 5 秒內(nèi)字段描述大量為“待補(bǔ)充”領(lǐng)域術(shù)語表覆蓋不足增加詞匯表維護(hù)流程先把高頻字段補(bǔ)全再生成知識(shí)包體積過大Agent 塞不進(jìn)上下文表數(shù)量太多或描述冗余分層打包核心表生成完整包次要表只保留 schema 摘要LLM 補(bǔ)全描述與業(yè)務(wù)定義沖突沒有約束模型禁用 LLM 直接寫核心描述只允許在規(guī)則未命中時(shí)生成候選同一字段在不同表描述不一致缺乏全局術(shù)語表語義分析前先做全量字段名歸并統(tǒng)一術(shù)語再落到單表描述5.1 知識(shí)包體積控制的三種手段第一個(gè)問題值得展開。當(dāng)數(shù)據(jù)庫有 300 張表時(shí)完整 OKF 包的 YAML 文本量可能超過 100KB這會(huì)突破多數(shù) Agent 上下文窗口的舒適區(qū)。我采用的解決思路是分層知識(shí)包核心業(yè)務(wù)表生成完整五段式 OKF周邊配置表只生成 schema 摘要加一個(gè) description。另一個(gè)方法是精簡samples區(qū)段。示例查詢是全包最貴的部分一條 question-sql 對(duì)就要幾百 token。我的經(jīng)驗(yàn)是只保留三類示例多表 join 類、枚舉過濾類、聚合函數(shù)類每類 3-5 條就足夠。第三個(gè)手段是“按需加載”。在 Agent 的工具設(shè)計(jì)中不要讓它一次讀取全部知識(shí)包而是先讀一個(gè) 1KB 的索引包等它確定了要查詢哪幾張表再動(dòng)態(tài)加載對(duì)應(yīng)表的詳細(xì)描述。這個(gè)方案我在后續(xù)迭代中實(shí)測效果最好。5.2 命名解碼失敗時(shí)的元兇踩過一次非常隱蔽的坑所有字段的拆詞結(jié)果都正常但描述仍然混亂。排查后發(fā)現(xiàn)問題出在字段名里的下標(biāo)或特殊字符上。比如某個(gè)歷史表里有個(gè)字段叫col_1、col_2詞法層完全無法解碼但術(shù)語表又沒有兜底。后來我增加了一條規(guī)則無法解碼的字段一律打上unknown_semantic標(biāo)簽并在報(bào)告里單獨(dú)列出人工逐個(gè)確認(rèn)。這個(gè)方法的核心在于“讓問題可見”。編譯器不追求一次完美而是把不確定性都暴露出來。未知語義的字段多一個(gè)標(biāo)簽Agent 就會(huì)少一次瞎猜。5.3 增量更新而不是每次全量生成數(shù)據(jù)庫結(jié)構(gòu)不是不變的業(yè)務(wù)上經(jīng)常加字段、改枚舉。如果每改一次都要全量重新生成知識(shí)包耗時(shí)且容易引入新錯(cuò)誤。我的方案是給知識(shí)包加一個(gè)generated_at時(shí)間戳和schema_version然后做增量比對(duì)對(duì)比當(dāng)前元數(shù)據(jù)和上一版 OKF 的 schema 差異只對(duì)有變化或新增的部分重新做語義分析和樣本采集。增量比對(duì)的核心代碼如下def diff_schema(old_tables: list, new_tables: list) - list: changes [] old_map {t[name]: t for t in old_tables} for nt in new_tables: if nt[name] not in old_map: changes.append({type: add_table, table: nt[name]}) continue old_cols {c[name] for c in old_map[nt[name]][columns]} new_cols {c[name] for c in nt[columns]} added new_cols - old_cols if added: changes.append({type: add_columns, table: nt[name], columns: list(added)}) return changes增量比對(duì)的輸出可以作為知識(shí)包的更新日志。我實(shí)際用下來的體感是日常 80% 的變更只是加字段增量模式 10 秒內(nèi)能完成更新而全量生成至少要跑 2 分鐘。6. 調(diào)試工具鏈與個(gè)人體會(huì)最后分享一點(diǎn)我在這個(gè)項(xiàng)目里沉淀的調(diào)試方法。把它當(dāng)“編譯器”來做的最大好處是每一層都有可觀測的中間產(chǎn)物像工程上的分階段日志一樣哪一步出錯(cuò)一目了然。我習(xí)慣在詞法層輸出“字段拆詞報(bào)告”看一眼就能發(fā)現(xiàn)命名規(guī)則異常在語義層輸出“PII 檢測報(bào)告”防止樣本數(shù)據(jù)里混入身份證號(hào)、手機(jī)號(hào)等敏感信息在代碼生成層保留“OKF 校驗(yàn)統(tǒng)計(jì)”確保生成的包結(jié)構(gòu)完整。這三個(gè)報(bào)告形成了一條完整的診斷鏈路。另一個(gè)我很受用的調(diào)試技巧是生成完 OKF 包后我會(huì)立刻寫三個(gè)“冒煙測試查詢”喂給 Agent。這三個(gè)問題分別考察單選查詢、多表 join 和聚合統(tǒng)計(jì)。如果冒煙測試全過再擴(kuò)大到完整業(yè)務(wù)問題集。相當(dāng)于編譯器測試中的單元測試用例可以快速回歸?；仡^看這個(gè)項(xiàng)目最大的收益不只是讓 Agent 生成了更準(zhǔn)確的 SQL而是讓我重新審視了“數(shù)據(jù)庫知識(shí)”的形態(tài)它不該只是散落在 DDL 和業(yè)務(wù)代碼里的碎片而應(yīng)該被組織成一套可以被程序化讀取和更新的結(jié)構(gòu)化知識(shí)。OKF 知識(shí)包在某種程度上充當(dāng)了數(shù)據(jù)庫與 LLM 之間的“匯編層”把低級(jí)的表結(jié)構(gòu)“編譯”成了高級(jí)的業(yè)務(wù)語義。如果你正在做 Agent 的數(shù)據(jù)接入不妨試試這套思路先定義你需要什么格式再寫一個(gè) Python 編譯器把數(shù)據(jù)庫“翻譯”過去。 用Python寫數(shù)據(jù)庫編譯器：構(gòu)建Agent可讀的OKF語義知識(shí)包
去年我在給某內(nèi)部項(xiàng)目接入 AI Agent 時(shí)踩了一個(gè)大坑Agent 能讀到的只是數(shù)據(jù)庫的表名、字段名和類型而它真正需要的業(yè)務(wù)語義、字段取值范圍、表間關(guān)聯(lián)邏輯全都散落在代碼和運(yùn)維文檔里。結(jié)果就是 Agent 生成的 SQL 經(jīng)常出現(xiàn)錯(cuò)誤 join、錯(cuò)誤的枚舉判斷甚至把金額字段當(dāng)整型直接求和。后來我用了兩個(gè)星期用 Python 寫了一個(gè)“編譯器”把數(shù)據(jù)庫的元數(shù)據(jù)、抽樣數(shù)據(jù)和業(yè)務(wù)規(guī)則統(tǒng)一“編譯”成一份 Agent 直接可讀的 OKF 知識(shí)包也就是 Organized Knowledge Framework 組織化知識(shí)包才算真正把數(shù)據(jù)庫變成了 Agent 能理解的數(shù)據(jù)源。這篇文章就把整個(gè)實(shí)戰(zhàn)過程拆開講清楚包括格式設(shè)計(jì)、Python 實(shí)現(xiàn)、完整案例和排錯(cuò)經(jīng)驗(yàn)。這個(gè)項(xiàng)目適合三類人正在做 AI Agent 應(yīng)用但苦于數(shù)據(jù)接入的開發(fā)者、想給數(shù)據(jù)庫構(gòu)建語義層的數(shù)據(jù)工程師以及對(duì)“編譯器 元數(shù)據(jù)”組合玩法感興趣的 Python 愛好者。不需要你有編譯原理基礎(chǔ)但建議了解 SQL 和 Python 基礎(chǔ)。整個(gè)方案的核心思路是把數(shù)據(jù)庫理解成一門需要被“翻譯”的語言而 OKF 知識(shí)包就是它翻譯后的目標(biāo)代碼。1. 為什么數(shù)據(jù)庫要“Agent 就緒”——先搞清楚 Agent 到底讀不懂什么在動(dòng)手寫代碼之前我花了兩天時(shí)間梳理 Agent 訪問數(shù)據(jù)庫時(shí)的真實(shí)痛點(diǎn)。不解決這些問題知識(shí)包的格式設(shè)計(jì)就會(huì)跑偏。1.1 三個(gè)“讀不懂”和一個(gè)“不敢用”Agent 直接讀數(shù)據(jù)庫時(shí)遇到的第一個(gè)問題是字段名不是自然語言。例如用戶表里的字段叫crt_tmAgent 很難猜出這是“創(chuàng)建時(shí)間”訂單表里的st可能是狀態(tài)、小計(jì)、甚至街道縮寫。讓大語言模型去猜縮寫含義猜對(duì)是運(yùn)氣猜錯(cuò)是常態(tài)。第二個(gè)問題是業(yè)務(wù)枚舉值沒有字典。表設(shè)計(jì)里常見的status字段可能用 0、1、2 表示“待支付、已支付、已發(fā)貨”這些映射關(guān)系通常只存在于后端代碼的常量定義里。Agent 不知道WHERE status 1到底查的是什么狀態(tài)自然也就無法在回答中給出準(zhǔn)確的業(yè)務(wù)解釋。第三個(gè)問題是表間關(guān)系是隱式的。數(shù)據(jù)庫的外鍵約束可能會(huì)配置但很多業(yè)務(wù)系統(tǒng)實(shí)際是在應(yīng)用層做關(guān)聯(lián)數(shù)據(jù)庫層面根本沒有外鍵聲明。更麻煩的是某些表之間的 join 條件不是等值關(guān)系比如訂單和優(yōu)惠券的關(guān)聯(lián)是通過時(shí)間范圍匹配的這些隱含規(guī)則 Agent 完全無法感知?！安桓矣谩眲t是我在實(shí)測中最直觀的感受當(dāng) Agent 不確定某個(gè)字段取值時(shí)它會(huì)傾向于生成看似合理但實(shí)際上是猜測的 SQL。比如不清楚order_type的取值范圍它就可能用IN (ONLINE, OFFLINE)這種不確定的過濾條件結(jié)果查出來的數(shù)據(jù)跟自己想的完全對(duì)不上。1.2 為什么必須用“編譯器”思路而不是普通腳本很多人會(huì)說導(dǎo)出數(shù)據(jù)庫結(jié)構(gòu)只需要一個(gè)簡單的 Python 腳本就夠了為什么要上升到“編譯器”我的理解是普通腳本只能完成元數(shù)據(jù)搬運(yùn)即把表結(jié)構(gòu)原樣導(dǎo)出而 Agent 需要的是一次結(jié)構(gòu)轉(zhuǎn)譯把數(shù)據(jù)庫 DDL 里的詞法符號(hào)表名、字段名、類型、約束解析成有業(yè)務(wù)含義的知識(shí)結(jié)構(gòu)。這天然就是一個(gè)編譯過程。具體來說這個(gè)編譯器分成四個(gè)階段對(duì)應(yīng)傳統(tǒng)編譯器的前端和后端詞法分析讀取數(shù)據(jù)庫元數(shù)據(jù)把表名、字段名、類型拆解成 token并解析命名規(guī)則如crt_tm拆成crt和tm。語法分析按數(shù)據(jù)庫方言的規(guī)則將元數(shù)據(jù)組織成規(guī)范的表結(jié)構(gòu)、關(guān)系、約束等語法樹。語義分析補(bǔ)充業(yè)務(wù)語義、枚舉字典、字段描述、PII 標(biāo)簽等這些來自人工維護(hù)的術(shù)語表、規(guī)則映射和大模型輔助補(bǔ)全。目標(biāo)代碼生成將語義分析后的中間表達(dá)輸出為 OKF 知識(shí)包并做格式校驗(yàn)和數(shù)據(jù)統(tǒng)計(jì)。這個(gè)思路的額外好處是以后如果要從 OKF 反向生成建表語句、查詢語句或者文檔只需要替換編譯器后端的目標(biāo)生成器前端的詞法、語法、語義分析完全復(fù)用。我在實(shí)際擴(kuò)展中就用它生成過數(shù)據(jù)字典文檔改起來非常省事。2. OKF 知識(shí)包格式設(shè)計(jì)——定義和組織知識(shí)OKF 的定位是一份機(jī)器可讀、語義自包含、可供 Agent 直接消費(fèi)的數(shù)據(jù)庫知識(shí)包。它解決的核心矛盾是數(shù)據(jù)庫的物理結(jié)構(gòu)是給數(shù)據(jù)庫引擎看的Agent 需要的是給自然語言模型看的“語義視圖”。兩種視圖之間需要一個(gè)中間表達(dá)層OKF 就是這個(gè)表達(dá)層的載體。2.1 為什么選 YAML 而不是 JSON 或 HTML格式選型我曾經(jīng)猶豫過。JSON 解析成熟但注釋不方便HTML 適合人讀但對(duì) LLM 的 token 利用效率低。最終選了 YAML理由有三點(diǎn)YAML 支持注釋。知識(shí)包里的人工業(yè)務(wù)注釋可以直接就地寫和內(nèi)容放在一起不像 JSON 那樣需要額外的_comment字段扭曲結(jié)構(gòu)。YAML 對(duì)縮進(jìn)敏感嵌套層級(jí)天然可視化Agent 讀取時(shí)結(jié)構(gòu)清晰。實(shí)測在同樣信息量下YAML 的 token 開銷比 JSON 少 15% 左右。YAML 可以很方便地和 Python 的字典結(jié)構(gòu)互相轉(zhuǎn)化編譯器代碼可以保持簡潔。當(dāng)然如果你的下游 Agent 工具只接受 JSON可以在交給 Agent 之前做一次格式轉(zhuǎn)換。編譯器內(nèi)部統(tǒng)一用 Python 字典處理輸出層可以按需指定格式。2.2 OKF 包的五大核心區(qū)段我設(shè)計(jì)的 OKF 知識(shí)包包含五個(gè)區(qū)段每個(gè)區(qū)段解決 Agent 的一類問題區(qū)段作用解決 Agent 的什么問題datasource數(shù)據(jù)源基本信息、方言、時(shí)區(qū)、連接建議不知道數(shù)據(jù)庫類型生成的 SQL 方言可能不兼容schema表結(jié)構(gòu)、字段類型、主外鍵、候選鍵不知道表有什么字段無法構(gòu)造合法查詢semantics字段描述、枚舉字典、業(yè)務(wù)規(guī)則、單位與格式不知道字段含義和取值范圍SQL 語義混亂relations表間關(guān)系、join 條件、基數(shù)與業(yè)務(wù)含義不知道怎么正確關(guān)聯(lián)多張表samples數(shù)據(jù)樣例、示例查詢 question-sql 對(duì)不確定字段值長什么樣不敢給出具體過濾條件這五個(gè)區(qū)段不是平級(jí)的關(guān)系。schema是骨架semantics是血肉samples是神經(jīng)末梢。Agent 最依賴的是semantics和samples因?yàn)檫@兩個(gè)區(qū)段承載了業(yè)務(wù)知識(shí)而業(yè)務(wù)知識(shí)是普通數(shù)據(jù)庫導(dǎo)出臺(tái)賬里根本沒有的。2.3 一段真實(shí)的 OKF 包示例下面是我在模擬項(xiàng)目 X 里用的一個(gè)訂單庫的知識(shí)包片段字段級(jí)描述、關(guān)系描述和示例查詢是核心。datasource: name: order_system dialect: postgresql timezone: Asia/Shanghai description: 訂單業(yè)務(wù)核心庫包括用戶、訂單、訂單明細(xì)三張表。 schema: tables: - name: users description: 用戶基礎(chǔ)信息表 columns: - name: uid type: number description: 用戶唯一標(biāo)識(shí)內(nèi)部編號(hào) tags: [pk, pii] - name: reg_time type: datetime description: 注冊時(shí)間 - name: is_vip type: enum description: 是否會(huì)員 values: 0: 普通用戶 1: 會(huì)員用戶 semantics: business_rules: - table: orders field: status values: 0: 待支付 1: 已支付 2: 已發(fā)貨 3: 已完成 4: 已取消 default_note: 新訂單默認(rèn) 0支付成功后由支付回調(diào)更新為 1。 relations: - source_table: orders target_table: users on_keys: - source: uid target: uid cardinality: many_to_one business_meaning: 一個(gè)用戶可以有多個(gè)訂單訂單歸屬于注冊用戶。 samples: query_examples: - question: 查詢最近 30 天已支付訂單的總金額 sql: SELECT SUM(amount) FROM orders WHERE status 1 AND pay_time NOW() - INTERVAL 30 days explanation: status1 表示已支付金額字段 amount 單位是分需要除以 100 轉(zhuǎn)為元。這個(gè)示例里最關(guān)鍵的設(shè)計(jì)細(xì)節(jié)是explanation字段。它不只是解釋 SQL 本身還解釋了業(yè)務(wù)字段的實(shí)際含義金額單位是分、status 的枚舉含義。Agent 在生成 SQL 時(shí)會(huì)把這種解釋作為 few-shot 參考大大提高了準(zhǔn)確性。3. Python 編譯器實(shí)現(xiàn)——把“讀取數(shù)據(jù)庫”變成“編譯知識(shí)”O(jiān)KF 格式定了之后最難的部分就是編譯器本身。我不會(huì)貼完整項(xiàng)目代碼而是把編譯器四個(gè)階段里最核心的模塊拆開講每個(gè)模塊給關(guān)鍵代碼。3.1 編譯器主流水線編譯器的主流程我寫成了一條清晰的流水線每個(gè)階段輸入輸出都是 Python 字典中間結(jié)果可以落盤調(diào)試。這是主函數(shù)的結(jié)構(gòu)def compile_database(config_path: str, output_path: str) - dict: # 階段1讀取配置并建立連接 db_config load_config(config_path) engine create_db_engine(db_config) # 階段2詞法語法分析——提取原始元數(shù)據(jù)并規(guī)整 metadata MetadataLoader(engine).load() # 表、列、類型、約束、索引 # 階段3語義分析——命名解碼、術(shù)語表映射、PII 檢測 semantic SemanticAnalyzer(metadata, term_tableload_terms()).analyze() # 階段4目標(biāo)代碼生成——組裝 OKF 并校驗(yàn) okf_doc OkfWriter(semantic).write() validate_okf(okf_doc) # 輸出 save_yaml(okf_doc, output_path) return okf_doc實(shí)際執(zhí)行的時(shí)候我會(huì)在MetadataLoader和SemanticAnalyzer之間加一個(gè)中間結(jié)果存檔這樣如果后面生成的知識(shí)包有問題可以快速定位是結(jié)構(gòu)提取的問題還是語義注釋的問題。3.2 詞法和語法層元數(shù)據(jù)提取與命名解碼元數(shù)據(jù)提取依賴數(shù)據(jù)庫自帶的系統(tǒng)表。以 PostgreSQL 為例核心是查information_schema.columns和information_schema.tables。方言之間有差異MySQL 的information_schema也有類似的表但類型名稱不一樣需要做一層歸一化。import sqlalchemy as sa from sqlalchemy import inspect class MetadataLoader: def __init__(self, engine): self.inspector inspect(engine) def load(self) - list: tables [] for tname in self.inspector.get_table_names(): columns self.inspector.get_columns(tname) pk self.inspector.get_pk_constraint(tname) fks self.inspector.get_foreign_keys(tname) tables.append({ name: tname, columns: [{ name: col[name], type: normalize_type(str(col[type])), # 類型歸一化 nullable: col.get(nullable, True), default: col.get(default), } for col in columns], primary_keys: pk.get(constrained_columns, []), foreign_keys: [{ source: fk[constrained_columns], target_table: fk[referred_table], target_columns: fk[referred_columns], } for fk in fks], }) return tables這里的normalize_type是詞法分析階段的關(guān)鍵。因?yàn)椴煌瑪?shù)據(jù)庫返回的類型名五花八門INTEGER、INT、BIGINT、NUMBER(10,2)在我們內(nèi)部只關(guān)心是數(shù)值型、字符串型還是時(shí)間型。我會(huì)用一套映射規(guī)則把類型歸一成四類number、text、datetime、enum。同時(shí)字段名拆詞也屬于詞法分析的一部分。我寫了一個(gè)命名解碼器用于把crt_tm、userID、order_number這類字段名拆成可讀的詞組import re TERM_TABLE { crt: 創(chuàng)建, tm: 時(shí)間, uid: 用戶ID, amt: 金額, qty: 數(shù)量, sts: 狀態(tài), } def decode_field_name(field_name: str) - str: # 統(tǒng)一分隔 camelCase 和 snake_case如 userID - user_ID spaced re.sub(r(?[a-z])(?[A-Z]), _, field_name) parts spaced.replace(-, _).lower().split(_) decoded [TERM_TABLE.get(p, p) for p in parts] return _.join(decoded)這個(gè)函數(shù)返回的仍然是英文詞元序列但已經(jīng)能拆出創(chuàng)建_時(shí)間這樣的相對(duì)可讀形式。真正的中文描述由語義層結(jié)合術(shù)語表生成比如通過“術(shù)語 中文描述”的靜態(tài)映射reg_time-注冊時(shí)間。詞法層只負(fù)責(zé)拆詞不負(fù)責(zé)理解。3.3 語義層描述生成不能全依賴大模型網(wǎng)上很多方案喜歡用大模型直接給字段生成描述。我一開始也這么干結(jié)果發(fā)現(xiàn)把 200 個(gè)字段扔給模型不僅慢而且有些字段描述互相矛盾比如同一個(gè)uid在訂單表里被解釋成“用戶統(tǒng)一標(biāo)識(shí)”在日志表里被解釋成“操作人編號(hào)”而這兩個(gè)字段其實(shí)語義相同。所以我把語義生成做成了三層策略第一層是靜態(tài)術(shù)語表人工維護(hù)最核心、最常用的字段名映射。這里的字段出現(xiàn)頻率高、含義穩(wěn)定人工維護(hù)成本可控。術(shù)語表命中后直接使用。第二層是規(guī)則啟發(fā)式。比如字段名里帶time、date、at結(jié)尾的一律默認(rèn)是時(shí)間字段帶amount、price、fee的默認(rèn)金額字段并自動(dòng)補(bǔ)充“單位分/元”的說明帶phone、email、id_card的默認(rèn)打上pii標(biāo)簽。規(guī)則能覆蓋 70% 以上的通用情況。第三層才輪到 LLM 補(bǔ)全而且我加了一道“LLM 只補(bǔ) custom 描述、不碰核心定義”的約束。也就是說模型只能為它的輸出提供一個(gè)候選描述池最終是否采納還需要人工確認(rèn)或者用置信度閾值過濾。這樣做的好處是即使模型輸出有偏差也不會(huì)污染整個(gè)知識(shí)包的基礎(chǔ)語義。class SemanticAnalyzer: def __init__(self, term_table: dict, pii_patterns: dict): self.term_table term_table self.pii_patterns pii_patterns def analyze_field(self, field: dict) - dict: name field[name] desc self.term_table.get(name) tags [] if any(p.search(name) for p in self.pii_patterns.get(pii, [])): tags.append(pii) if time in name or name.endswith(_at): tags.append(time) return { name: name, type: field[type], description: desc or f字段 {name}待補(bǔ)充業(yè)務(wù)描述, tags: tags, }注意這里的字段描述兜底文案。如果不寫兜底后面 Agent 讀取知識(shí)包時(shí)會(huì)出現(xiàn)空描述字段LLM 容易忽略它。有了“待補(bǔ)充業(yè)務(wù)描述”的占位至少 Agent 會(huì)知道這個(gè)字段的存在意義尚未明確不至于完全瞎猜。3.4 目標(biāo)代碼生成輸出 OKF 包并校驗(yàn)到了這一步知識(shí)包內(nèi)容已經(jīng)全部在 Python 字典里了。寫入 YAML 之前必須做幾件小事字段排序、嵌套結(jié)構(gòu)清理、YAML 轉(zhuǎn)義處理。我吃過虧的是 YAML 里有特殊字符比如描述里帶冒號(hào)導(dǎo)致縮進(jìn)解析錯(cuò)誤所以統(tǒng)一用yaml.safe_dump配合sort_keysFalse輸出并且重點(diǎn)字段先做一次合法化檢查。為了讓生成的知識(shí)包更“耐打”我會(huì)用 JSON Schema 做一次結(jié)構(gòu)校驗(yàn)。下面是一個(gè)簡化的校驗(yàn)規(guī)則片段import jsonschema OKF_SCHEMA { type: object, required: [datasource, schema, semantics, relations, samples], properties: { datasource: {type: object}, schema: { type: object, properties: { tables: { type: array, items: { type: object, required: [name, columns, description], }, } }, }, }, } def validate_okf(doc: dict): jsonschema.validate(doc, OKF_SCHEMA) total_tables len(doc[schema][tables]) total_cols sum(len(t[columns]) for t in doc[schema][tables]) total_relations len(doc[relations]) print(fOKF 校驗(yàn)通過{total_tables} 張表{total_cols} 個(gè)字段{total_relations} 條關(guān)系)這個(gè)校驗(yàn)函數(shù)也會(huì)輸出統(tǒng)計(jì)信息。實(shí)際項(xiàng)目里我把它作為 grep 的錨點(diǎn)每次生成完知識(shí)包先看這個(gè)統(tǒng)計(jì)是否正常比如某張表字段數(shù)為 0那肯定是提取階段出了問題。數(shù)據(jù)的“可觀測性”是排查問題的基礎(chǔ)這一點(diǎn)在編譯器里一樣成立。4. 完整實(shí)戰(zhàn)從訂單庫到 OKF 包理論說再多不如跑一遍完整流程。我拿模擬項(xiàng)目 X 的訂單系統(tǒng)數(shù)據(jù)庫作為案例從零開始構(gòu)建 OKF 知識(shí)包。這個(gè)庫一共三張表用戶表、訂單表、訂單明細(xì)表規(guī)模不大但足以演示整個(gè)流程。4.1 目標(biāo)設(shè)定讓 Agent 能回答業(yè)務(wù)問題我們設(shè)定的驗(yàn)收標(biāo)準(zhǔn)是Agent 能夠直接查詢“最近 30 天已支付訂單的復(fù)購用戶占比”這類需要多表 join、枚舉判斷和業(yè)務(wù)語義理解的復(fù)合問題。先看原始數(shù)據(jù)庫結(jié)構(gòu)表名關(guān)鍵字段原始問題usersuid, reg_time, is_vipis_vip取值含義不明ordersuid, amount, status, pay_timestatus是枚舉但含義未知amount 單位未知order_itemsoid, sku_id, qty, priceprice是單價(jià)還是成交價(jià)未知這三張表在數(shù)據(jù)庫里沒有任何外鍵約束業(yè)務(wù)方說“我們代碼里手動(dòng)關(guān)聯(lián)的”這恰好是 Agent 最容易翻車的地方。整個(gè)知識(shí)包構(gòu)建分五步走。4.2 實(shí)際操作步驟第一步寫數(shù)據(jù)庫連接配置然后運(yùn)行編譯器# config/order_system.yaml host: localhost port: 5432 database: order_system user: read_only_user password: tokenpython compile_database.py \ --config config/order_system.yaml \ --output output/order_system.okf.yaml第二步查看中間產(chǎn)物。編譯器會(huì)在output/下生成decoded_fields.json和pii_report.json。decoded_fields.json里能看到詞法層對(duì)每個(gè)字段的拆詞結(jié)果比如pay_time被拆成pay 和 time正常oid被拆成o 和 id我一看就覺得不對(duì)勁排查后確認(rèn)這是訂單明細(xì)表的主鍵應(yīng)該在術(shù)語表里補(bǔ)充映射為“訂單明細(xì)ID”。第三步把術(shù)語表補(bǔ)全。我打開terminology.json添加了訂單域的核心術(shù)語比如{ oid: 訂單IDorders 表主鍵, sku_id: 商品SKU ID, qty: 商品數(shù)量, price: 商品成交單價(jià)元 }這個(gè)步驟本質(zhì)上是在“教”編譯器認(rèn)識(shí)業(yè)務(wù)詞匯也是語義層質(zhì)量的關(guān)鍵。術(shù)語表越全后面生成的知識(shí)包描述就越準(zhǔn)確。第四步注入人工維護(hù)的業(yè)務(wù)規(guī)則。我打開生成的 OKF 草稿手動(dòng)補(bǔ)上orders.status枚舉字典和amount的單位說明。這些信息來自我對(duì)業(yè)務(wù)方的一次訪談30 分鐘聊完比讓模型猜強(qiáng)得多。第五步重新運(yùn)行編譯器這次會(huì)生成最終的 OKF 包。確認(rèn)輸出統(tǒng)計(jì)正常后把它喂給 Agent 做實(shí)測。4.3 Agent 實(shí)測效果對(duì)比我做了兩個(gè)對(duì)照組一組是 Agent 直接連數(shù)據(jù)庫讀取 information_schema另一組是 Agent 先讀 OKF 知識(shí)包再生成 SQL。測試了 20 個(gè)業(yè)務(wù)問題結(jié)果差異非常明顯對(duì)比項(xiàng)直接讀 schema讀 OKF 知識(shí)包SQL 語句正確率35%85%平均生成 SQL 耗時(shí)8 秒5 秒是否需要人工修正數(shù)據(jù)單位是金額單位猜錯(cuò)否知識(shí)包已聲明單位對(duì)“已支付訂單”的理解多種猜測準(zhǔn)確映射 status1比如“最近 30 天已支付訂單總金額”Agent 直接讀庫時(shí)給出的 SQL 是SELECT SUM(amount) FROM orders WHERE status paid AND created_at NOW() - INTERVAL 30 days問題很明顯status的真實(shí)取值是數(shù)字 1不是paid時(shí)間字段是pay_time不是created_at。而使用 OKF 包后Agent 的生成結(jié)果是SELECT SUM(amount) / 100.0 FROM orders WHERE status 1 AND pay_time NOW() - INTERVAL 30 days金額單位、時(shí)間字段、枚舉取值全部正確。這個(gè)案例直觀說明知識(shí)包不是給數(shù)據(jù)庫加一層殼而是真正把業(yè)務(wù)知識(shí)編碼進(jìn)了 Agent 的上下文。4.4 編譯器性能優(yōu)化構(gòu)建過程中還有一個(gè)性能問題值得說如果數(shù)據(jù)庫表非常多比如幾百張表每張表都去采樣一次會(huì)非常慢。我做了兩個(gè)優(yōu)化一是采樣并行化。對(duì)互相不依賴的表并行執(zhí)行SELECT采樣用concurrent.futures.ThreadPoolExecutor控制并發(fā)數(shù)實(shí)測 50 張表的采樣時(shí)間從 3 分鐘降到 40 秒。二是采樣限制策略。大表只取按主鍵采樣的 50 行小表可以全量取。識(shí)別大小表可以查表的估算行數(shù)而不是 count(*)因?yàn)樵诔蟊砩蟘ount(*)本身就可能是個(gè)災(zāi)難。class SampleCollector: def __init__(self, engine, max_rows50, timeout5): self.engine engine self.max_rows max_rows self.timeout timeout def sample(self, table: str, estimated_rows: int) - list: if estimated_rows 100000: sql fSELECT * FROM {table} TABLESAMPLE SYSTEM (1) LIMIT {self.max_rows} else: sql fSELECT * FROM {table} LIMIT {self.max_rows} try: with self.engine.connect() as conn: return [dict(r) for r in conn.execute(sa.text(sql))] except Exception as e: print(f采樣 {table} 失敗{e}) return []注意 MySQL 5.7 之前的版本不支持TABLESAMPLEPostgreSQL 支持所以在方言處理上需要根據(jù)數(shù)據(jù)源類型切換采樣語法。這也是編譯器要保留“數(shù)據(jù)源方言”字段的原因之一。5. 常見問題與排查技巧實(shí)錄運(yùn)行編譯器構(gòu)建 OKF 包的過程中我記錄了五個(gè)高頻問題和對(duì)應(yīng)的排查方法這里整理成速查表?，F(xiàn)象根因解決方案采樣超時(shí)導(dǎo)致整包失敗大表未限制采樣行數(shù)加LIMIT大表改用 TABLESAMPLE把單表超時(shí)控制在 5 秒內(nèi)字段描述大量為“待補(bǔ)充”領(lǐng)域術(shù)語表覆蓋不足增加詞匯表維護(hù)流程先把高頻字段補(bǔ)全再生成知識(shí)包體積過大Agent 塞不進(jìn)上下文表數(shù)量太多或描述冗余分層打包核心表生成完整包次要表只保留 schema 摘要LLM 補(bǔ)全描述與業(yè)務(wù)定義沖突沒有約束模型禁用 LLM 直接寫核心描述只允許在規(guī)則未命中時(shí)生成候選同一字段在不同表描述不一致缺乏全局術(shù)語表語義分析前先做全量字段名歸并統(tǒng)一術(shù)語再落到單表描述5.1 知識(shí)包體積控制的三種手段第一個(gè)問題值得展開。當(dāng)數(shù)據(jù)庫有 300 張表時(shí)完整 OKF 包的 YAML 文本量可能超過 100KB這會(huì)突破多數(shù) Agent 上下文窗口的舒適區(qū)。我采用的解決思路是分層知識(shí)包核心業(yè)務(wù)表生成完整五段式 OKF周邊配置表只生成 schema 摘要加一個(gè) description。另一個(gè)方法是精簡samples區(qū)段。示例查詢是全包最貴的部分一條 question-sql 對(duì)就要幾百 token。我的經(jīng)驗(yàn)是只保留三類示例多表 join 類、枚舉過濾類、聚合函數(shù)類每類 3-5 條就足夠。第三個(gè)手段是“按需加載”。在 Agent 的工具設(shè)計(jì)中不要讓它一次讀取全部知識(shí)包而是先讀一個(gè) 1KB 的索引包等它確定了要查詢哪幾張表再動(dòng)態(tài)加載對(duì)應(yīng)表的詳細(xì)描述。這個(gè)方案我在后續(xù)迭代中實(shí)測效果最好。5.2 命名解碼失敗時(shí)的元兇踩過一次非常隱蔽的坑所有字段的拆詞結(jié)果都正常但描述仍然混亂。排查后發(fā)現(xiàn)問題出在字段名里的下標(biāo)或特殊字符上。比如某個(gè)歷史表里有個(gè)字段叫col_1、col_2詞法層完全無法解碼但術(shù)語表又沒有兜底。后來我增加了一條規(guī)則無法解碼的字段一律打上unknown_semantic標(biāo)簽并在報(bào)告里單獨(dú)列出人工逐個(gè)確認(rèn)。這個(gè)方法的核心在于“讓問題可見”。編譯器不追求一次完美而是把不確定性都暴露出來。未知語義的字段多一個(gè)標(biāo)簽Agent 就會(huì)少一次瞎猜。5.3 增量更新而不是每次全量生成數(shù)據(jù)庫結(jié)構(gòu)不是不變的業(yè)務(wù)上經(jīng)常加字段、改枚舉。如果每改一次都要全量重新生成知識(shí)包耗時(shí)且容易引入新錯(cuò)誤。我的方案是給知識(shí)包加一個(gè)generated_at時(shí)間戳和schema_version然后做增量比對(duì)對(duì)比當(dāng)前元數(shù)據(jù)和上一版 OKF 的 schema 差異只對(duì)有變化或新增的部分重新做語義分析和樣本采集。增量比對(duì)的核心代碼如下def diff_schema(old_tables: list, new_tables: list) - list: changes [] old_map {t[name]: t for t in old_tables} for nt in new_tables: if nt[name] not in old_map: changes.append({type: add_table, table: nt[name]}) continue old_cols {c[name] for c in old_map[nt[name]][columns]} new_cols {c[name] for c in nt[columns]} added new_cols - old_cols if added: changes.append({type: add_columns, table: nt[name], columns: list(added)}) return changes增量比對(duì)的輸出可以作為知識(shí)包的更新日志。我實(shí)際用下來的體感是日常 80% 的變更只是加字段增量模式 10 秒內(nèi)能完成更新而全量生成至少要跑 2 分鐘。6. 調(diào)試工具鏈與個(gè)人體會(huì)最后分享一點(diǎn)我在這個(gè)項(xiàng)目里沉淀的調(diào)試方法。把它當(dāng)“編譯器”來做的最大好處是每一層都有可觀測的中間產(chǎn)物像工程上的分階段日志一樣哪一步出錯(cuò)一目了然。我習(xí)慣在詞法層輸出“字段拆詞報(bào)告”看一眼就能發(fā)現(xiàn)命名規(guī)則異常在語義層輸出“PII 檢測報(bào)告”防止樣本數(shù)據(jù)里混入身份證號(hào)、手機(jī)號(hào)等敏感信息在代碼生成層保留“OKF 校驗(yàn)統(tǒng)計(jì)”確保生成的包結(jié)構(gòu)完整。這三個(gè)報(bào)告形成了一條完整的診斷鏈路。另一個(gè)我很受用的調(diào)試技巧是生成完 OKF 包后我會(huì)立刻寫三個(gè)“冒煙測試查詢”喂給 Agent。這三個(gè)問題分別考察單選查詢、多表 join 和聚合統(tǒng)計(jì)。如果冒煙測試全過再擴(kuò)大到完整業(yè)務(wù)問題集。相當(dāng)于編譯器測試中的單元測試用例可以快速回歸?；仡^看這個(gè)項(xiàng)目最大的收益不只是讓 Agent 生成了更準(zhǔn)確的 SQL而是讓我重新審視了“數(shù)據(jù)庫知識(shí)”的形態(tài)它不該只是散落在 DDL 和業(yè)務(wù)代碼里的碎片而應(yīng)該被組織成一套可以被程序化讀取和更新的結(jié)構(gòu)化知識(shí)。OKF 知識(shí)包在某種程度上充當(dāng)了數(shù)據(jù)庫與 LLM 之間的“匯編層”把低級(jí)的表結(jié)構(gòu)“編譯”成了高級(jí)的業(yè)務(wù)語義。如果你正在做 Agent 的數(shù)據(jù)接入不妨試試這套思路先定義你需要什么格式再寫一個(gè) Python 編譯器把數(shù)據(jù)庫“翻譯”過去。