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